From 6fbf600670fdb62f65ddd39c26cdb8e648faaf08 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Wed, 2 Sep 2026 18:26:59 +0530
Subject: [PATCH 01/21] feat(skills): rebuild live-preview support skill as a
 diagnostic protocol

Rename cms-live-preview-visual-builder-support-assistant to
cms-live-preview-visual-editor-support-assistant and rebuild it from one
268-line prose file into a 7-step intake protocol plus 12 reference files.

- SKILL.md: fixed protocol (product -> setup or regression -> Onboarding
  Check -> detect framework and rendering mode from code -> logs -> localise
  to one of four setup contracts -> fix, verify, or hand to Support), with a
  stop rule so evidence collection ends once a contract is localised
- onboarding-check.md: the setup-status gates as implemented in the editor;
  only the first failing gate is shown, and Live Preview, Visual Editor and
  Timeline resolve an unset visibility setting differently
- rendering-modes.md, frameworks.md, setup-docs.md: contract per rendering
  mode, init placement per framework, official docs as the setup source
- faq-*.md and symptom-index.md: 40 symptom / cause / fix / verification
  entries split by product (setup, preview runtime, Visual Editor, Timeline)
- contact-support.md: causes outside the application plus a handover-note
  template; console-noise.md: console output seen on healthy setups
- Terminology section: Visual Builder and Visual Editor are the same product
- router row updated; cursor/ and codex/ regenerated

Claims about product bug state, fix versions and Launch-hosting specifics
were removed on purpose so the skill does not go stale as fixes ship.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 codex/AGENTS.md                               |   2 +-
 .../SKILL.md                                  | 266 ------------
 .../SKILL.md                                  | 366 +++++++++++++++++
 .../references/console-noise.md               |  41 ++
 .../references/contact-support.md             |  61 +++
 .../references/faq-preview-runtime.md         | 161 ++++++++
 .../references/faq-setup.md                   | 377 ++++++++++++++++++
 .../references/faq-timeline.md                |  39 ++
 .../references/faq-visual-editor.md           | 100 +++++
 .../references/frameworks.md                  | 172 ++++++++
 .../references/onboarding-check.md            | 110 +++++
 .../references/preflight-checklist.md         |  93 +++++
 .../references/rendering-modes.md             | 126 ++++++
 .../references/setup-docs.md                  |  71 ++++
 .../references/symptom-index.md               |  69 ++++
 cursor/rules/00-router.mdc                    |   2 +-
 ...eview-visual-builder-support-assistant.mdc | 269 -------------
 ...review-visual-editor-support-assistant.mdc | 369 +++++++++++++++++
 skills/CLAUDE.md                              |   2 +-
 .../SKILL.md                                  | 269 -------------
 .../SKILL.md                                  | 369 +++++++++++++++++
 .../references/console-noise.md               |  41 ++
 .../references/contact-support.md             |  61 +++
 .../references/faq-preview-runtime.md         | 161 ++++++++
 .../references/faq-setup.md                   | 377 ++++++++++++++++++
 .../references/faq-timeline.md                |  39 ++
 .../references/faq-visual-editor.md           | 100 +++++
 .../references/frameworks.md                  | 172 ++++++++
 .../references/onboarding-check.md            | 110 +++++
 .../references/preflight-checklist.md         |  93 +++++
 .../references/rendering-modes.md             | 126 ++++++
 .../references/setup-docs.md                  |  71 ++++
 .../references/symptom-index.md               |  69 ++++
 33 files changed, 3947 insertions(+), 807 deletions(-)
 delete mode 100644 codex/cms-live-preview-visual-builder-support-assistant/SKILL.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
 delete mode 100644 cursor/rules/07-cms-live-preview-visual-builder-support-assistant.mdc
 create mode 100644 cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
 delete mode 100644 skills/cms-live-preview-visual-builder-support-assistant/SKILL.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md

diff --git a/codex/AGENTS.md b/codex/AGENTS.md
index e86f870..69f4fef 100644
--- a/codex/AGENTS.md
+++ b/codex/AGENTS.md
@@ -8,8 +8,8 @@ Use the table below to route a user request to the right skill. Each row maps a
 | Use when users want to migrate, move, switch, port, or re-platform from Contentful to Contentstack, including content models, content, assets, locales, application integrations, website code, migration prerequisites, migration progress checks, or post-migration validation. | [contentstack-migration-companion](./migration-companion/SKILL.md) |
 | Use when a user wants to migrate Contentstack Delivery SDK code from JavaScript to TypeScript. | [dx-migrate-js-to-ts-sdk](./dx-migrate-js-to-ts-sdk/SKILL.md) |
 | Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, Live Preview setup, Visual Builder support, SSR preview handling, or debugging SDK query chains. | [dx-delivery-sdk](./dx-delivery-sdk/SKILL.md) |
+| Use for any Contentstack Live Preview, Visual Editor or Visual Builder question (Visual Editor and Visual Builder are the same product), whether setting it up or debugging it: first-time integration in any framework, SDK upgrades, the SDK installed but nothing happening, a blank preview pane, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, canvas or edit-tag resolution failures, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](./cms-live-preview-visual-editor-support-assistant/SKILL.md) |
 | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](./cms-data-modeling-best-practices/SKILL.md) |
-| Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not. | [Live Preview and Visual Builder Support Assistant](./cms-live-preview-visual-builder-support-assistant/SKILL.md) |
 | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](./cms-entries/SKILL.md) |
 | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](./cms-assets/SKILL.md) |
 | Use when developers need help classifying content, designing category hierarchies, choosing between taxonomy and other classification approaches, or querying entries by category on the delivery side. | [Contentstack Taxonomy](./cms-taxonomy/SKILL.md) |
diff --git a/codex/cms-live-preview-visual-builder-support-assistant/SKILL.md b/codex/cms-live-preview-visual-builder-support-assistant/SKILL.md
deleted file mode 100644
index 8334330..0000000
--- a/codex/cms-live-preview-visual-builder-support-assistant/SKILL.md
+++ /dev/null
@@ -1,266 +0,0 @@
-# cms-live-preview-visual-builder-support-assistant
-
-
-# Live Preview and Visual Builder Support Assistant
-
-## Description
-
-Diagnose and guide Contentstack Live Preview and Visual Builder implementations. Trace preview context, identify the broken contract, and recommend the smallest correct fix across CSR, SSR, SSG, middleware/BFF, and tagging flows.
-
-## When to Use
-
-Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not.
-
-## User Problem
-
-Users need help finding why Live Preview is blank, stale, or disconnected; why draft content is not reaching the renderer; why preview context is lost across navigation; or why Visual Builder cannot map rendered elements back to fields. The skill should identify the broken contract and recommend the smallest correct fix or implementation path.
-
-## Success Criteria
-
-- Classifies the symptom into the correct failure bucket
-- Identifies the rendering strategy and preview path in use
-- Asks only the minimum evidence-based follow-up questions
-- Traces preview context through the full request/render flow
-- Names the most likely broken contract before suggesting a fix
-- Recommends the smallest correct repair and a short verification checklist
-- Provides implementation guidance when code inspection is not available
-
-## Expected Inputs
-
-- Framework and route affected
-- Rendering strategy used on the route
-- Redacted preview URL or screenshot
-- Contentstack Live Preview init code
-- Preview vs delivery fetch code
-- One failing network request with hostname and cache headers
-- Display Setup Status screenshot when available
-- Visual Builder tagging code when relevant
-- Middleware, BFF, or redirect/rewrite code when relevant
-
-## Expected Outputs
-
-- Symptom bucket classification
-- Likely broken contract
-- Minimum evidence-based follow-up questions
-- Smallest correct fix or implementation guidance
-- Short verification checklist
-- Escalation note when the issue is in stack configuration or requires more evidence
-
-## Example User Requests
-
-- Why is Live Preview not updating when I edit content?
-- How do I set up Contentstack Live Preview for SSR?
-- What is the difference between ssr: true and ssr: false?
-- My preview iframe is blank. What should I check?
-- How do preview tokens and live preview hashes work?
-
-## Workflow Summary
-
-1. Classify the symptom.
-2. Classify the rendering strategy.
-3. Request only the minimum evidence needed.
-4. Inspect the preview contract in code or provided snippets.
-5. Name the most likely broken contract.
-6. Recommend the smallest correct fix.
-7. Return a short verification checklist.
-
-## Instructions
-
-### 1. Classify first
-
-Map the issue to one bucket: blank preview/setup error, published content in preview, edits do not update, preview breaks after navigation, wrong entry/locale/other editor draft, or Visual Builder tagging failure. Do not branch until evidence forces it.
-
-### 2. Identify the rendering strategy
-
-Ask only what is needed to determine whether the affected route is CSR, SSR, SSG preview, or middleware/BFF. The ssr setting controls preview behavior, not the whole app.
-
-### 3. Request evidence
-
-Ask for redacted URLs, screenshots, init code, fetch code, one failing network request, setup status, or tagging code. Never ask for secrets, tokens, cookies, or auth headers.
-
-### 4. Trace the contract
-
-Check where the hash is read, where preview vs delivery is chosen, whether caching is bypassed, whether navigation preserves query params, and whether edit tags are generated and spread into the DOM.
-
-### 5. Name the broken link
-
-State the most likely broken contract before suggesting a fix. Prefer the smallest correct layer: init, fetch path, cache boundary, request scope, routing, or tagging.
-
-### 6. Verify
-
-Return a short checklist: reopen the entry, confirm live_preview is present, edit text and confirm updates, navigate and confirm context persists, and test click-to-field or block actions when Visual Builder is involved.
-
-## Output Format
-
-Use short, actionable bullets. Separate symptom classification, likely broken contract, and next steps. Call out when a behavior applies only to preview and not production. Prefer evidence-based conclusions over speculation. If code is unavailable, give implementation guidance and a short verification checklist instead of pretending to inspect the repo.
-
-## Tooling Notes
-
-Read-only guidance first. Use Read, Grep, and Glob when code is available. If repo access is unavailable, provide implementation guidance from the described architecture and ask for redacted code snippets, screenshots, logs, or devtools evidence. Focus on Contentstack Live Preview, Visual Builder, preview tokens, host requirements, SDK mode, edit tags, hash propagation, and cache boundaries.
-
-## Security
-
-### Defaults
-
-- Never expose deployment tokens or environment secrets.
-- Validate preview targets and host URLs before suggesting changes.
-- Never recommend enabling Live Preview in production builds.
-- Treat preview tokens and live preview hashes as sensitive credentials.
-- Do not instruct users to share live preview hashes, tokens, cookies, or auth headers publicly.
-
-### Destructive Actions
-
-Do not make changes automatically. Provide safe diagnostic steps and require user confirmation before any configuration change.
-
-### Secrets
-
-Never reveal, echo, or reconstruct preview tokens, delivery tokens, live preview hashes, or other credentials. If a secret appears in input, instruct the user to rotate it if exposed.
-
-### Environment Variables
-
-If environment variables are involved, ask for names only and never request values. Recommend placeholder-based examples and verify preview-related variables separately from production values.
-
-## Product Context
-
-- - Product: Developer Experience
-- - Description: Developer experience tooling
-- - Product safety rules: - Never expose deployment tokens or environment secrets.
-- Validate deployment targets before triggering.
-- Require confirmation for production deployments.
-- Never auto-deploy to production without review.
-
-## Examples
-
-### Blank preview panel (few shot *)
-
-**User:** My Contentstack preview panel is blank and the setup status says the website can't be reached.
-
-**Assistant:** Likely bucket: blank preview or setup status error.
-
-Check:
-- Does the preview URL open directly in a browser tab?
-- Are X-Frame-Options or frame-ancestors blocking embedding?
-- Is the Live Preview base URL correct for this environment and locale?
-- Does the previewed route call ContentstackLivePreview.init() in browser code?
-
-Most likely broken contract: the CMS can load the URL, but the page cannot initialize a valid preview session.
-
-Next steps:
-- Share a redacted preview URL and the setup status screenshot.
-- Confirm whether the route uses iframe embedding or new-tab preview.
-- Verify the SDK init runs on the actual previewed route.
-
-*Covers blank iframe/setup status failures.*
-
-### Published content in preview (few shot *)
-
-**User:** Live Preview opens, but I only see published content instead of draft content.
-
-**Assistant:** Likely bucket: published content in preview.
-
-Check:
-- Does the URL contain live_preview=...?
-- Are requests hitting the preview host, not the delivery host?
-- Is a preview token configured?
-- Does the fetch layer receive and forward the hash?
-- Is a proxy or middleware dropping the hash?
-
-Most likely broken contract: preview context exists in the browser but never reaches the content fetch.
-
-Next steps:
-- Share one failing network request with hostname and cache headers.
-- Share the code path that chooses preview vs delivery.
-- Confirm whether the page fetches directly or through a BFF/API route.
-
-*Covers missing hash or wrong API path.*
-
-### Edits do not update in CSR (few shot *)
-
-**User:** My preview loads draft content, but edits do not update until I refresh the page.
-
-**Assistant:** Likely bucket: edits do not update.
-
-For CSR, check:
-- Is ssr: false configured?
-- Is onEntryChange() or onLiveEdit() registered?
-- Does the callback refetch content?
-- Is the listener mounted once and early enough?
-- Does state get replaced atomically instead of merged?
-
-Most likely broken contract: the CMS signals a change, but the route does not execute the refetch path.
-
-Next steps:
-- Share the init code and the subscription code.
-- Confirm whether the page uses CSR, SSR, or a mix.
-- Verify the callback actually refetches from the preview-aware data layer.
-
-*Covers CSR refresh loop failures.*
-
-### Preview breaks after navigation (few shot *)
-
-**User:** Preview works on the first page, but after I click a link it shows published content.
-
-**Assistant:** Likely bucket: preview breaks after navigation.
-
-Treat this as hash propagation failure until proven otherwise.
-
-Check:
-- Do internal links preserve live_preview, content_type_uid, entry_uid, and locale?
-- Do redirects, rewrites, or auth guards strip query params?
-- Does client-side routing rebuild URLs without preview context?
-
-Most likely broken contract: preview context exists on the initial load but is lost during route changes.
-
-Next steps:
-- Share the navigation code or middleware/rewrites.
-- Inspect the post-navigation URL in devtools.
-- Preserve the full search string during preview navigation.
-
-*Covers hash loss after route changes.*
-
-### Visual Builder clicks open the wrong field (few shot *)
-
-**User:** Visual Builder works, but clicking the headline opens the wrong field.
-
-**Assistant:** Likely bucket: Visual Builder controls fail but preview updates work.
-
-Treat this as a tagging problem until proven otherwise.
-
-Check:
-- Is mode set to "builder"?
-- Does the fetched entry pass through addEditableTags() in the data layer?
-- Are the $ props spread onto real DOM nodes?
-- Are referenced entries tagged with their own content type UID?
-- Are modular block indices correct?
-
-Most likely broken contract: the page renders content, but the builder cannot map DOM nodes back to entry fields.
-
-Next steps:
-- Inspect the rendered data-cslp value in devtools.
-- Share the data-layer tagging code and one rendered component.
-- Verify the field path matches the content model exactly.
-
-*Covers edit-tag mapping failures.*
-
-### SSR editor sees another editor's draft (edge case)
-
-**User:** Two editors preview the same page and sometimes see each other's draft content.
-
-**Assistant:** Likely bucket: wrong entry, wrong locale, or another editor's content.
-
-Treat this as shared state or caching.
-
-Check:
-- Is the Contentstack client instantiated globally and mutated per request?
-- Is livePreviewQuery() called on a shared SDK instance?
-- Are preview responses cached at any layer?
-- Is preview data written to persistent storage?
-
-Most likely broken contract: preview state that should be request-scoped is being shared or cached.
-
-Next steps:
-- Move to request-scoped clients for SSR and BFF layers.
-- Disable caching whenever live_preview is present.
-- Keep preview data out of long-lived storage.
-
-*Covers SSR leakage and cache contamination.*
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
new file mode 100644
index 0000000..2636992
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -0,0 +1,366 @@
+# cms-live-preview-visual-editor-support-assistant
+
+
+# Live Preview and Visual Editor Support Assistant
+
+## Description
+
+Systematically set up and debug Contentstack Live Preview, Visual Editor (also called Visual Builder), and Timeline. Setup follows the official documentation. Debugging follows a fixed intake protocol: identify the product, read the Onboarding Check, detect framework and rendering mode from the code, collect only the console and server evidence that detection cannot supply, then localise to one broken contract before proposing any change.
+
+## When to Use
+
+Use for any Contentstack Live Preview, Visual Editor, or Timeline question, whether the integration has never worked or works and misbehaves.
+
+`dx-delivery-sdk` is the neighbouring skill. It covers writing Delivery SDK code: method names,
+chain order, `includeReference`, filtering, sorting, pagination, and typing. Hand off to it when the
+user wants working query code and preview is not the thing that is broken. Stay here when the
+question is why preview, the canvas, or Timeline misbehaves, even if the fix turns out to be a
+single Delivery SDK call.
+
+Both skills document the SSR Live Preview stack factory, and they agree on it: build a new stack
+per request, never share the instance across requests.
+
+## Terminology
+
+**Visual Builder and Visual Editor are the same product.** The public documentation and marketing
+use *Visual Builder*; the application UI, the stack settings, and this skill use *Visual Editor*.
+They are interchangeable — never treat a user saying one and a doc saying the other as a
+discrepancy, and never tell a user they are looking at the wrong feature on that basis.
+
+Mirror whichever term the user used. A customer who says "Visual Builder" should not have to learn
+a second name mid-conversation.
+
+Two related names worth keeping straight:
+
+- **Visual Experience** is the umbrella covering Live Preview, Visual Editor and Timeline. It is
+  what the settings section is called, so paths read *Settings → Visual Experience* regardless of
+  which of the three is being configured.
+- **`mode: "builder"`** is an SDK option and keeps its name. So does the
+  `visual_builder.onboarding-setup-visible` stack setting. Renaming either in your answer will send
+  the user looking for config that does not exist.
+
+## User Problem
+
+The same complaint has many unrelated causes. "Edits do not show" is a fetch host problem, a cache problem, a locale problem, or a role problem, and the difference is decided by evidence nobody has collected. Guessing produces a long thread of speculative fixes.
+
+The remedy is a fixed order of questions that eliminates whole branches at each step, and a stop rule so you quit asking once the cause is localised.
+
+## Success Criteria
+
+- Works the intake protocol in order rather than jumping to a plausible cause
+- Establishes the product first, because the three do not share a setup or a check
+- Asks for the Onboarding Check before anything else, and uses what its result already proves
+- Never asks a question the evidence has already answered
+- Stops collecting once one contract is localised
+- Uses the documentation for setup and the failure catalogue for debugging
+- Recognises causes outside the user's application and points the user to Contentstack Support instead of debugging
+
+## Expected Inputs
+
+Collected in the order set out below, not all at once. Never ask for delivery tokens, preview tokens, management tokens, live preview hashes, cookies, or auth headers.
+
+## Expected Outputs
+
+- The broken contract or mechanism, and the evidence for it
+- The smallest correct change, or a plain statement that no application-side fix exists
+- A verification the user runs themselves
+- What to send Contentstack Support, when the cause sits outside the user's code
+
+## Workflow Summary
+
+1. Identify the product.
+2. Setup or regression.
+3. Read the Onboarding Check.
+4. Detect framework and rendering mode from the code.
+5. Collect only the evidence detection could not supply.
+6. Localise to one contract.
+7. Fix, verify, or hand to Contentstack Support.
+
+## Instructions
+
+Work these in order. Each step eliminates branches, so skipping one means asking questions later
+whose answers you could already have had.
+
+**Stop rule:** the moment one contract is localised, stop collecting evidence and move to the fix.
+Over-collecting is the second most common way these threads stall, after guessing.
+
+### Step 1. Which product?
+
+Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
+Onboarding Check, or a failure set.
+
+| Product | What it is | Notes |
+|---|---|---|
+| **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
+| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags. Not a separate integration. |
+| **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
+| **Preview Sharing** | Share a preview link externally | Plan-gated. |
+
+If the user is on Visual Editor, confirm whether plain Live Preview works. If it does not, that is
+the problem, and the Visual Editor symptom is downstream noise.
+
+### Step 2. Setup, or regression?
+
+Ask: has this ever worked correctly, for anyone, on any route?
+
+**Never worked** goes to [references/setup-docs.md](references/setup-docs.md). Follow the official
+documentation for the framework and mode. Do not reconstruct setup steps from memory. Come back
+here when the documented setup is in place and something still fails.
+
+**Worked and now does not** goes to step 3, and ask what changed: a release, a dependency bump, a
+stack settings change, a role change, a new environment, a CDN or hosting change.
+
+### Step 3. Read the Onboarding Check
+
+Ask for a **screenshot** of the floating status card in the preview panel. Do this before any other
+diagnostic question. The product already ran the check you are about to run by hand.
+
+Ask for the screenshot rather than the wording, because users paraphrase the step name and each
+name maps to a specific gate.
+
+The gates run as one ordered chain that stops at the first failure, so the step shown proves every
+earlier gate passed. Full gate list, meanings, and the Timeline variant are in
+[references/onboarding-check.md](references/onboarding-check.md). In short, for Live Preview and
+Visual Editor:
+
+| Card | Localises to |
+|---|---|
+| Could Not Connect to Website | Frame headers, auth gate, Base URL, certificate, browser blocking localhost |
+| Live Preview SDK Not Initialized | `init()` never ran on the client in the deployed build |
+| Outdated Live Preview SDK Version | Version below the supported minimum |
+| Preview Service Not Enabled | The fetch never switched host and headers |
+| Default Environment Not Set | Setup is fine; no default preview environment on the stack |
+| Setup Complete | Reachability, handshake, version and Preview Service are all fine |
+
+**Timeline runs a different check.** Three gates, not these five, so do not map a Timeline card
+onto the table above:
+
+| Card | Localises to |
+|---|---|
+| Default Environment | No default preview environment on the stack |
+| Live Preview SDK | SDK version below the supported minimum |
+| Preview Token | Requests are not using the Preview Service |
+
+Timeline's check also waits a fixed delay before declaring failure, so a slow site can produce a
+failure card on a correct setup. Have the user reopen the panel on a warm cache before believing it.
+
+Two readings that decide the whole branch:
+
+- **Setup Complete, but nothing is editable.** The check never inspects `data-cslp`. This is edit
+  tags, every time. Go to contract 2 in step 6.
+- **No card at all.** Absence is not a pass. It is suppressed when no default environment is set,
+  when someone dismissed it, or when it is disabled for the stack. Verify the contracts by hand.
+
+### Step 4. Establish framework and rendering mode
+
+**Detect this, do not ask for it.** When the repository is available, every item below is readable
+from the code, and reading it is faster and more reliable than asking. Developers routinely answer
+"Next.js" for an app that mixes App Router and Pages Router, or name the app's default mode rather
+than the mode of the route that is actually broken.
+
+Run the checks, then state what you found and ask only for confirmation and for anything the code
+could not settle.
+
+| Question | Where to look | What it tells you |
+|---|---|---|
+| Framework and version | `package.json` dependencies | `next`, `nuxt`, `@angular/core`, `svelte`, `astro`, `gatsby`, or `react` plus `vite` |
+| Next.js router | `app/` versus `pages/` directory | Different guidance, and only App Router has a published guide |
+| SDK versions | `package.json`, lockfile | Against the minimums in Tooling Notes |
+| One SDK copy | lockfile, plus any `<script type="module">` in the HTML | An npm install alongside a CDN import of another version behaves like a config bug |
+| Rendering mode of the route | `export const dynamic`, `revalidate`, `getStaticProps`, `getServerSideProps`, `output: "export"` | The mode of that route, which is what matters |
+| `ssr` setting | the `init(` call site | Explicit value, or absent and therefore inferred |
+| `stackSdk` passed | the `init(` call site | Mandatory in CSR, and what the SDK uses to default `ssr` |
+| Init placement | the file containing `init(`, and whether it is `"use client"` | Contract 1. Server-only placement is the most common Next.js miss |
+| Edit tags | `addEditableTags` | Contract 2. Absent means Visual Editor cannot work, whatever else is true |
+| Fetch layer | `@contentstack/delivery-sdk` import, raw `fetch`, or a GraphQL client | Decides which form of contract 3 applies |
+| Preview host wiring | `preview_token`, `live_preview`, any hostname constant | Contract 3 |
+| Cache posture | `fetch` cache options, `revalidate`, CDN or middleware config | The "works locally, fails deployed" class |
+
+That sweep usually settles contracts 1, 2 and 3 in step 6 before you ask the user anything, and it
+often makes step 5 unnecessary.
+
+Two things the repository cannot tell you. Ask for these:
+
+1. **Where it is served**: localhost, a preview deployment, or production.
+2. **Whether the deployed build matches the branch you are reading.** An environment variable that
+   does not parse as a boolean, or a stale deploy, makes correct-looking code behave as if init
+   never ran.
+
+Without repository access, ask for the same list, in this order: framework and version, the mode of
+the affected route, the fetch layer, and the `init()` call site.
+
+The SDK ships no framework adapters, no framework peer dependencies, and no per-framework code
+paths. Framework choice decides only where `init()` may run and whether hydration preserves edit
+tags. Everything else follows from mode and fetch layer.
+
+| Mode | `ssr` | Hash travels via | Updates arrive as |
+|---|---|---|---|
+| CSR + REST | `false` | postMessage, into `stackSdk` | `onEntryChange` refetch, no reload |
+| SSR + REST | `true` | `live_preview` query parameter | full iframe reload |
+| CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch, manual host swap |
+| SSR + GraphQL | `true` | `request.query.live_preview` | full reload, manual host swap |
+| SSG | `false` | postMessage | runs as CSR at runtime |
+
+`stackSdk` is mandatory in CSR and is what the SDK uses to default `ssr`. A CSR app that omits it
+silently gets SSR behaviour; an SSG site initialised with `ssr: true` gives blank screens rather
+than an error. Two mode traps to check before prescribing: **SSR** needs a per-request Stack
+instance, because a module-level one leaks one editor's draft into other users' responses; **SSG** is
+supported, but only in CSR mode: a prerendered page never sees the `live_preview` query parameter,
+so the documented setup is `ssr: false` with `stackSdk`, where the hash arrives by postMessage
+instead. **ISR** is the harder case: a regenerated page is still a cached page, and caching has to be off
+on the preview path. There is no published recipe for combining ISR with Live Preview.
+
+Detail and the framework coverage table are in
+[references/rendering-modes.md](references/rendering-modes.md); init placement per framework is in
+[references/frameworks.md](references/frameworks.md).
+
+### Step 5. Collect logs and one request
+
+Only for what step 4 could not settle. With repository access the contracts are often already
+localised, and the single most valuable item left is the request host. Skip whatever you can
+already answer, and ask for the rest in one pass rather than one at a time.
+
+1. **Browser console, with the preview panel open.** Look for the init handshake, CSP or frame
+   refusals, CORS failures, and framework hydration errors. Ask them to reproduce with the console
+   open, because most of these fire once at load. Read it against the noise list below before
+   drawing any conclusion.
+2. **Server-side logs**, for SSR, middleware, BFF, or proxy setups. This is where a swallowed
+   preview fetch error lives, and it is invisible in the browser. Skip for pure CSR.
+3. **One failing request from the Network tab**: full request URL and host, response status, and
+   response headers. Redacted.
+
+**Check the console output against [references/console-noise.md](references/console-noise.md)
+before concluding anything from it.** Preview runs the site in an iframe with postMessage between
+two apps, so a healthy setup still produces console chatter — `NO_REQUEST_LISTENER_FOUND` and third-party script errors both appear on working
+integrations. If one of those is the only thing in the console, you have no console evidence, not
+evidence of a problem.
+
+The request host alone settles the most common failure of all. During an active preview
+session, content coming from `cdn.contentstack.io` or `graphql.contentstack.com` means the hash is
+not reaching the fetch, regardless of the reported symptom.
+
+Also ask, in one line each, the questions that separate causes:
+
+- **One user or everyone?** One user points at their role. Preview runs as that user and applies
+  their full ACL — content types, entries, fields, locales, assets — so anything they cannot read
+  comes back empty. Delivery uses a delivery token and applies none, which is why the published
+  page looks fine. This is by design: the fix is usually defensive rendering on the site, not a
+  product issue.
+- **Localhost or deployed?** Working locally and failing deployed is a cache on the preview path,
+  or a frame header.
+- **Consistent or intermittent?** Intermittent and user-dependent under SSR is a shared
+  module-level Stack instance. That one reaches public traffic.
+- **Which locale, and which variant?** Both change the fetch, and both are common false leads.
+
+### Step 6. Localise to one contract
+
+A working integration needs four independent contracts. They fail separately and complain
+identically. Name which one is unmet, with the evidence, before proposing anything.
+
+| # | Contract | One-look check |
+|---|---|---|
+| 1 | `init()` runs, on the client, in the deployed build | `POST /live-preview/tracker` returns 2xx when the panel loads |
+| 2 | Edit tags are generated and land on DOM elements | Some rendered element carries `data-cslp` |
+| 3 | The hash reaches the fetch, which switches host plus headers | Content requests hit a `*-preview.contentstack.com` host |
+| 4 | The preview target is reachable in an iframe | The pane renders at all |
+
+Contract 1 gates 2 and 3. Contract 4 gates everything. Steps 3, 4 and 5 have usually already decided
+this; if they have, do not re-derive it.
+
+For contract 2, the one the Onboarding Check cannot see:
+
+```jsx
+addEditableTags(entry, contentTypeUid, true, locale);
+<h1 {...data.$?.title}>{data.title}</h1>
+```
+
+`mode: "builder"` does not generate tags; only `addEditableTags()` does, it mutates the entry and
+returns nothing, and the third argument must be `true` for React and JSX. Mirror the data path
+exactly, because references come back as arrays: `post.author[0].$?.name`, not
+`post.$?.author.name`. Tag the leaf element, one `data-cslp` per element, and call it on referenced
+entries too.
+
+For contract 3:
+
+```js
+// SSR reads it from the request. CSR uses ContentstackLivePreview.hash.
+const livePreviewHash = request.query.live_preview;
+
+if (livePreviewHash) {
+  headers.append("live_preview", livePreviewHash);
+  headers.append("preview_token", PREVIEW_TOKEN);
+  url.hostname = LIVE_PREVIEW_HOST;   // rest-preview.contentstack.com
+} else {
+  url.hostname = CONTENTSTACK_CDN_HOST; // cdn.contentstack.io
+}
+```
+
+If the symptom is behavioural rather than a failed contract, look it up in
+[references/symptom-index.md](references/symptom-index.md), which routes to
+[faq-setup.md](references/faq-setup.md),
+[faq-preview-runtime.md](references/faq-preview-runtime.md),
+[faq-visual-editor.md](references/faq-visual-editor.md), and
+[faq-timeline.md](references/faq-timeline.md).
+
+For a first-time setup or an end-to-end sweep,
+[references/preflight-checklist.md](references/preflight-checklist.md) runs the contracts as 34
+ordered checks.
+
+### Step 7. Fix, verify, or hand to Contentstack Support
+
+Propose the smallest correct change at the right layer: init, tagging, fetch, cache boundary,
+routing, or stack configuration. Then give one verification the user runs themselves.
+
+Some causes sit outside the user's application entirely: stack provisioning, plan gating, and
+browser policy. Recognising one early beats any workaround, because no change to the site can
+resolve it. See [references/contact-support.md](references/contact-support.md) for the list, and
+**produce the handover note it defines** — filled from what steps 1–6 already collected — for the
+user to paste into their ticket to Contentstack Support.
+
+## Output Format
+
+Lead with the broken contract or mechanism and the evidence for it. Then the smallest correct
+change, as a snippet or diff, or a plain statement that no application-side fix exists. Then one
+verification. Attach mode-specific caveats to the step they affect.
+
+When you still need evidence, ask for the specific artifact that separates the remaining
+candidates, and say what each possible answer would mean. Do not send a generic list of requests.
+
+Say when a behaviour applies only to preview and not production, and say the reverse too, because
+preview output reaching real visitors is a production incident rather than an authoring annoyance.
+
+## Tooling Notes
+
+Read-only inspection first, with Read, Grep and Glob when the repository is available. Useful
+greps: the `init(` call site, `addEditableTags`, `onEntryChange`, `live_preview`, `preview_token`,
+any hostname constant, and cache configuration on the preview route.
+
+Minimum versions: Live Preview Utils v3.0+ and Delivery SDK v3.20.3+ for Visual Editor, and Live
+Preview Utils v4.4.4+ for `setPageContext()`. Confirm exactly one copy of the preview SDK is
+loaded.
+
+When the repository is not available, run the same protocol against described code and screenshots.
+Do not pretend to have inspected code.
+
+## Security
+
+### Defaults
+
+- Never expose delivery tokens, preview tokens, management tokens, or environment secrets.
+- Treat preview tokens and live preview hashes as credentials. Do not ask users to paste them, and
+  redact them if they appear. Ask for redacted logs and screenshots.
+- A management token in client-side Live Preview configuration is an exposure.
+- Do not recommend enabling Live Preview in production builds. An edit button on a public site is a
+  symptom of exactly that.
+- Preview output served to real visitors is a production data-exposure issue, not a cosmetic bug.
+- Validate preview target hosts before suggesting header or CSP changes.
+
+### Destructive Actions
+
+Do not change stack settings, roles, tokens, cache configuration, or environment configuration
+automatically. Propose the change, state the blast radius, and require confirmation.
+
+### Secrets
+
+Never reveal, echo, or reconstruct tokens or hashes. If a secret appears in provided input, tell
+the user to rotate it.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md b/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
new file mode 100644
index 0000000..482347e
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
@@ -0,0 +1,41 @@
+# Console output to ignore
+
+Preview runs the customer's site in an iframe, with two applications exchanging postMessage. That
+arrangement produces console output on healthy setups. Every entry below appears on integrations
+that are working correctly.
+
+Read a console log against this list **before** drawing any conclusion from it. Treating one of
+these as the cause is a reliable way to lose an hour, and worse, to tell a customer their
+integration is broken when it is not.
+
+**If one of these is the only thing in the console, you have no console evidence — not evidence of a
+problem.** Say so and move to the network tab.
+
+## The list
+
+### `NO_REQUEST_LISTENER_FOUND` / `No ack listener found`
+
+Routine. It means a postMessage arrived with no registered listener, which happens normally during
+load and teardown. Appears on working setups.
+
+Never conclude anything from it on its own. It does not affect SSR content, and it is not evidence
+that the handshake failed — check for the tracker POST instead.
+
+### Third-party script errors from ad, consent, or personalisation tags
+
+Expected. Those scripts key their targeting, delivery or storage off the top-level origin, which is
+the Contentstack app when the site is framed. They see the iframe context rather than the real
+site and behave differently.
+
+Not a Contentstack request failure — the calls fire and fail at the third party's own delivery
+stage. This is inherent to iframe rendering and has no product-side fix.
+
+## Adding to this list
+
+An entry earns a place here only if it appears on a **correctly working** integration. Something
+that shows up only when a setup is broken is a diagnostic signal and belongs in a FAQ entry, not
+here.
+
+Each entry should say what the message actually means, so a reader can tell it apart from a
+genuinely similar-looking error, and name the wrong conclusion people draw from it where there is a
+common one.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md b/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
new file mode 100644
index 0000000..f361144
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
@@ -0,0 +1,61 @@
+# When to contact Contentstack Support
+
+Symptoms whose cause sits outside the user's application. Recognising one of these early is worth
+more than any fix, because the alternative is a long debugging session in code that was never the
+problem.
+
+For each, the job is to confirm the identifying evidence, say plainly that this is not something
+they can fix in their own code, give the workaround if one exists, and tell them to open a ticket
+with Contentstack Support.
+
+## Provisioning and configuration, needs a support action
+
+| Symptom | What it actually is |
+|---|---|
+| The Visual Experience or builder-mode option is absent from navigation | The plan or org flag was never enabled for that stack. |
+| Custom Preview URLs or Open in New Tab are unavailable | Both are plan-gated. |
+
+## Not Contentstack at all
+
+| Symptom | What it actually is |
+|---|---|
+| A previously working `localhost` preview stops working, console shows a local network access error | Chrome's Local Network Access policy now blocks the app origin from framing localhost. Only the user can grant the permission, in the browser. |
+| Preview pane blank, and the site sits behind platform password protection or third-party SSO | Those screens set `X-Frame-Options: DENY` on themselves. Contentstack cannot inject headers into a browser-originated iframe request. Workarounds, cheapest first: enable **Open in New Tab**, which renders the site outside the iframe so frame headers stop applying; otherwise disable protection on the preview deployment, put a bypass token in the Base URL, or front it with a server-side proxy that strips the header. |
+| Ad slots, consent widgets, or other host-dependent third-party scripts misbehave in the pane | Those scripts key off the top-level origin, which is the Contentstack app inside an iframe. Expected, not a preview defect. |
+
+## How to hand it over
+
+State which category it falls into, quote the evidence that identifies it, and give the workaround
+if there is one. Then tell the user to raise it with Contentstack Support — as a next step for them,
+not as something happening behind the scenes. Nothing is routed anywhere on their behalf.
+
+
+### Produce a handover note
+
+Write the note below for the user to paste into the ticket. Fill it from what the protocol already
+collected in steps 1–6; do not start a new round of questions to complete it. Leave a field as
+"not checked" rather than guessing — an honest gap is more useful to the engineer than a filled-in
+assumption. Keep it to the fields; a Support or Product Engineer wants the facts, not the narrative.
+
+| Field | Value |
+|---|---|
+| Product | Live Preview / Visual Editor / Timeline |
+| Stack API key | `<api_key>` |
+| Environment / locale | `<environment>` / `<locale>` |
+| Branch or alias | only if not `main` |
+| Onboarding Check | exact card text shown, or "Setup Complete", or "card does not appear" |
+| Framework | name and major version; App Router or Pages Router where relevant |
+| Rendering mode | CSR / SSR / SSG / ISR / edge — for the affected route |
+| Fetch layer | Delivery SDK / REST / GraphQL / BFF, middleware or proxy |
+| SDK versions | `live-preview-utils x.y.z`, `delivery-sdk x.y.z` |
+| Scope | one user or everyone; localhost, deployed or both; consistent or intermittent |
+| Started after | new setup (never worked) / release / dependency bump / settings change / role change / nothing known |
+| Failing request | `METHOD host/path → status` — URL redacted, no tokens |
+| Console or server log | one-line excerpt, redacted |
+| Ruled out | contracts verified and how, e.g. "tracker POST 200; `data-cslp` present; requests hit the preview host" |
+| Suspected category | provisioning / plan gating / browser policy / other |
+| Workaround applied | what, or "none" |
+
+**Redact before sending.** Never include delivery tokens, preview tokens, management tokens, live
+preview hashes, cookies, or auth headers. The stack API key and environment name are fine and are
+what Support needs to find the stack.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
new file mode 100644
index 0000000..8109e83
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -0,0 +1,161 @@
+# Preview runtime FAQ
+
+Content correctness once the integration is confirmed wired up: staleness, lost preview context,
+caching, locale, variants, and Timeline.
+
+If the integration itself is not confirmed, work the four setup contracts in SKILL.md first. A
+fetch that never switched to the Preview Service produces most of the symptoms below and none of
+the fixes here will help.
+
+### variant-or-audience-switch-shows-base-entry
+- **bucket**: preview-runtime
+- **symptom**: Selecting a variant (or switching audience in Audience Preview) in Visual Experience keeps rendering the base entry. The side form shows the correct variant content, but the canvas does not. A manual browser refresh sometimes fixes it. Clicking into the element shows the correct variant value while the rendered page does not.
+- **frameworks**: Next.js, React, framework-agnostic
+- **rendering_modes**: CSR | SSR
+- **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-setup.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the parent Contentstack UI fetches the entry separately over the Management service. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
+- **fix**:
+  1. First confirm the preview path works at all: change a plain text field and check the canvas updates. If it does not, fix that first — the variant symptom is downstream of it.
+  2. Do **not** try to pass the variant yourself. The Preview Service resolves the variant from the UI selection; no extra `variant` query param is needed. `include_applied_variants=true` only adds metadata to the response body.
+  3. Confirm the Preview Service is actually configured: a preview token on the Stack's `live_preview` config, and content requests going to a `*-preview.contentstack.com` host during the session. This is the most common cause.
+  4. Register `ContentstackLivePreview.onEntryChange(fetchFn)` and make `fetchFn` re-query through the preview-configured Stack. This is the second most common cause. Confirm `ssr` matches the route's actual rendering mode while you are there.
+  5. Check the cache layer. If preview responses are cached under a key that ignores the `live_preview` hash, the base content is served no matter what. Bypass caching entirely for preview requests.
+  6. Variants on referenced entries: the referenced content type must be linked to the variant group for its variant content to resolve in preview, and that reference field must be in the `includeReference()` / `referenceFieldPath` list used for the page.
+  7. If a cache sits in front, it must not serve one variant's response for another. Do not key it by variant — bypass it for preview requests entirely.
+- **verification**: Switch variants; the network tab should show a fresh request to the preview host, and the rendered canvas should change without a manual refresh.
+
+---
+
+### cached-response-serves-stale-preview
+- **bucket**: preview-runtime
+- **symptom**: Preview works on localhost but not on a deployed environment with identical code and config — the setup status can even show "Setup Completed" and every edit return `{"notice":"Live Preview entry updated successfully."}` while the rendered page never changes. Or preview stops updating and only recovers in an incognito window or after a hard reload.
+- **frameworks**: Next.js, framework-agnostic
+- **rendering_modes**: SSR | SSG/ISR | edge
+- **root_cause**: A cache sits between the browser and the preview service. Whether or not its key includes the `live_preview` hash, preview requests get a stored payload instead of a live one. Seen with a customer CDN in front of the deployed environment, with an app-level fetch cache, and (on the Contentstack side) with stale JS bundles cached in the browser or CDN after a release. The Contentstack SDKs' own cache policies (`IGNORE_CACHE`, `CACHE_THEN_NETWORK`, `CACHE_ELSE_NETWORK`, `NETWORK_ELSE_CACHE`) do **not** switch themselves off for Live Preview — they cache regardless of the preview config.
+- **fix**:
+  1. Bypass every cache layer when a `live_preview` hash is present: no CDN caching of the preview host or the preview route, `cache: 'no-store'` on the fetch. If the app opted into SDK-level caching, also set `Policy.IGNORE_CACHE` in `cacheOptions` — but `cacheOptions` is optional and unset by default, so most apps have no SDK cache to disable and can skip this.
+  2. Do not cache preview responses at all, under any key. The `live_preview` hash identifies the preview **session**, not the content version, so it stays the same across every edit in that session. Keying a cache on it means the first response is served for the rest of the session and the canvas silently stops updating. There is no cache key that makes preview responses safe to cache — use the preview parameters to *bypass* the cache, never to key it.
+  3. Exclude the preview environment's base URL from the CDN entirely — the preview service cannot be cached at origin either, which is also why preview responses are measurably slower than CDN delivery (roughly 1s vs 100ms in one measured case). That gap is expected.
+- **verification**: Compare response headers on the preview request for cache hits. Reproduce in a private window; if the private window works and the normal one does not, it is a cache.
+
+---
+
+### locale-fallback-blank-or-wrong-locale-in-preview
+- **bucket**: preview-runtime
+- **symptom**: A page that renders fine in the entry editor and on the live site comes back blank in Visual Experience for a non-master locale. Or preview opens with a locale that does not exist in the stack (e.g. `en-us` on a stack that only has `fr-fr`) and 404s. Or one modular block referencing another entry renders empty in an unlocalized locale.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: CSR | SSR | SSG/ISR
+- **root_cause**: The Delivery API falls back to the master locale automatically; the Preview service does not. If the request to the preview service omits `include_fallback=true` (REST) or `fallback_locale: true` (GraphQL), an unlocalized entry — including an unlocalized *referenced* entry inside a modular block — returns nothing and the page renders empty. Separately, Visual Experience needs a base URL configured per locale in the environment; a locale with no base URL cannot load an iframe, and the preview URL falls back to a default locale that may not exist in the stack.
+- **fix**:
+  1. Add `include_fallback=true` (REST) / `fallback_locale: true` (GraphQL) to every preview fetch, and to nested reference includes.
+  2. Configure a base URL for every locale you want to author in, under the environment's Live Preview settings. A missing URL for one locale can disable the whole environment selector for that locale.
+  3. If a shared/common locale has no public market URL, create a preview-only route for it — it does not need to be publicly reachable, only loadable in the iframe.
+  4. If you need 404s for unlocalized entries outside preview but fallback inside preview, branch on the presence of the `live_preview` hash rather than turning fallback on globally.
+- **verification**: Open the locale in Visual Experience; the entry renders with master-locale content. Check the preview request URL contains the fallback parameter.
+
+---
+
+### csr-edits-need-manual-refresh
+- **bucket**: preview-runtime
+- **symptom**: Edits only appear after manually reloading the preview. Or the preview flashes/reloads but keeps the old values. Or after navigating to a second page inside the preview, editing an entry refetches and re-renders the *first* page instead.
+- **frameworks**: React, Next.js, Angular, Nuxt, Express
+- **rendering_modes**: CSR | SSR
+- **root_cause**: Three variants. (a) `onEntryChange` is never registered, or is registered but its callback fetches from the delivery path. (b) `ssr` does not match the route. With `ssr: true` the page is reloaded on change, so the fresh hash arrives on a new server request; with `ssr: false` the SDK calls `onChange()` instead and expects the app to refetch. Set the wrong one and neither path runs: an SSR route with `ssr: false` waits for a refetch the app never does, and a CSR route with `ssr: true` waits for a reload that does not repopulate client state. (c) Stale closure: `onEntryChange` is registered once in an effect with `[]` dependencies, but the fetch callback closed over the pathname captured at mount, so after a client-side route change it refetches the original path.
+- **fix**:
+  1. CSR: `ContentstackLivePreview.onEntryChange(fetchContent)` where `fetchContent` re-queries through the preview-configured Stack. Use `onEntryChange(fn, { skipInitialRender: true })` — equivalent to the older `onLiveEdit` — if you do not want the initial call.
+  2. Read the current route inside the callback (from a ref or `window.location.pathname`), never from a value captured at mount.
+  3. SSR: set `ssr: true`. The page is then reloaded on change and picks up the new hash on the server request. You do not need to add a `router.refresh()` or any manual re-render.
+  4. Do not call `stack.livePreviewQuery()` on the client in CSR mode. The SDK owns the hash there; a manual call that resets `live_preview: ""` when the browser URL lacks the params will clobber it and the refetch silently returns published content.
+- **verification**: Type into a field; the canvas updates without touching the browser. Navigate to a second page inside the preview and edit again — the second page should update, not the first.
+
+---
+
+### spa-client-navigation-loses-preview-context
+- **bucket**: preview-runtime
+- **symptom**: Preview works on the entry's own URL, but navigating within the site inside the preview panel breaks it — "Page Not Found", "You are currently previewing a different webpage", or edits silently stop applying. The address bar in the preview panel briefly shows an internal route that does not match the entry's `url` before settling back. Back button and refresh behave inconsistently.
+- **frameworks**: React (react-router), Next.js App Router, framework-agnostic
+- **rendering_modes**: CSR | SSR
+- **root_cause**: The SDK keeps the preview params on the URL by one mechanism only: a click listener that finds the clicked `<a>` and rewrites its `href` to include `live_preview` before the browser follows it. It does not patch the History API, so any navigation that does not go through a real anchor href — `router.push()`, `useNavigate()`, `history.pushState` — carries no params and the preview context is lost. Framework `<Link>` components are the common trap: they render an `<a>`, so the href is rewritten, but the router calls `preventDefault()` and pushes its own URL, so the rewrite is never used. Separately, if the app's routing does not map 1:1 to the entry's `url` field, the preview URL that Contentstack constructs (environment base URL + entry `url`) points at a route that does not exist. App Router soft navigation also does not re-run server-side hash gating.
+- **fix**:
+  1. Preserve `live_preview`, `content_type_uid`, `entry_uid`, and `preview_timestamp` in the URL across programmatic navigations, or trigger a hard navigation inside the preview.
+  2. For routes that cannot be derived from the entry `url` field, enable **Custom Preview URLs** and then call `setPageContext({ entryUid, contentTypeUid })` on each page (Live Preview Utils v4.4.4+). The call only takes effect when Custom Preview URLs is configured and enabled on the plan; otherwise it is silently ignored and the editor keeps resolving by URL.
+  3. For non-trivial URL structures, configure **Custom Preview URLs** in Settings → Visual Experience → Preview URL with placeholders (e.g. `/blog/{{entry.category}}/{{entry.slug}}`) and base URL aliases.
+  4. Confirm every route allows iframe embedding, not just the root — an `X-Frame-Options` or CSP `frame-ancestors` header, or a hard redirect to a different host, on a deep route will break navigation inside the panel.
+- **verification**: Click through the site's own nav inside the preview panel; the URL keeps its preview params and edits still apply on the new page.
+
+---
+
+### hash-empty-outside-the-preview-iframe
+- **bucket**: preview-runtime
+- **symptom**: `ContentstackLivePreview.hash` logs as an empty string, so the code that gates on it never switches to the preview host. Or an external tool calling the preview API directly gets `Please provide live preview hash in request` (error_code 382).
+- **frameworks**: framework-agnostic
+- **rendering_modes**: CSR | SSR
+- **root_cause**: The hash identifies a temporary preview session created by the Contentstack application. It only exists when the page is loaded inside the Live Preview / Visual Experience context (via the URL param the parent injects, or via the postMessage handshake). Outside that context there is no session and the hash is legitimately empty. There is no public way to mint one from your own code.
+- **fix**:
+  1. Treat an empty hash as "not in preview" and fall back to the delivery host. This is the correct branch, not a bug.
+  2. If the hash is empty *while inside* the preview panel, the postMessage handshake did not complete: check that the page is actually in the iframe, that `clientUrlParams.host` points at the right region's application host, that `init()` runs client-side (in a `"use client"` component for App Router), and that the SDK version is current.
+  3. SSR: do not rely on `ContentstackLivePreview.hash` on the server. Read `live_preview` from the request query string instead.
+  4. For an internal tool that needs draft data outside a browser preview session, the hash cannot be generated externally — that use case is not supported over the public preview API.
+- **verification**: Log the hash from inside the preview panel and from a normal tab. It should be populated in the first and empty in the second.
+
+---
+
+### stale-first-fetch-when-editing-a-referenced-entry
+- **bucket**: preview-runtime
+- **symptom**: The very first `onEntryChange` fetch after opening the preview returns published data even though the entry was already modified. Every subsequent keystroke-triggered fetch returns the correct draft data.
+- **frameworks**: Next.js (Pages Router), GraphQL
+- **rendering_modes**: CSR (on an SSG/ISR site)
+- **root_cause**: Service-side. It reproduced only when the entry being edited is a **referenced** entry and the site fetches the **parent** entry through a reference connection — the first preview response did not yet include the referenced entry's draft state.
+- **fix**:
+  1. Confirm the shape: are you editing a child/referenced entry while the page queries the parent through a reference connection? If so this is the known case and was fixed service-side.
+  2. Confirm the first request really is going to the preview host (the Onboarding Check reports this too) before assuming this issue — a first request to the delivery host looks identical from the outside.
+  3. Update to a current Live Preview Utils version.
+- **verification**: Modify a referenced entry, open the preview fresh, and confirm the draft value is present on the first render with no keystroke.
+
+---
+
+### legacy-management-token-preview-breaks-on-references
+- **bucket**: preview-runtime
+- **symptom**: Live Preview works for top-level fields but an edit to an entry that is referenced inside another entry does not update. Setup status reports "Preview Service Not Enabled" even though Live Preview is on for the stack. Migrating to preview tokens returns `401 Unauthorized` on the first attempt.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: The older Live Preview implementation authenticated with a read-only Management Token against the CMA host. On that path the reference-resolution optimizations of the Preview service are not available, so edits inside references do not propagate. "Preview Service Not Enabled" is exactly this: the site is still fetching draft data over CMA rather than the Preview service.
+- **fix**:
+  1. Migrate to the Preview Service: generate a Preview Token tied to your Delivery Token and replace `management_token` with `preview_token` in `live_preview`, and point `host` at the region's preview host.
+  2. Remove the CMA host override and any `setHost` calls left over from the old setup.
+  3. If preview requests 401 after the swap, confirm the Preview Token is tied to the Delivery Token you are actually using and that the token is sent as the `preview_token` header (not `authorization`).
+  4. Minimum versions for Visual Editor: Live Preview Utils v3.0+, Delivery SDK v3.20.3+ (v4.4.4+ of Live Preview Utils if you use `setPageContext`).
+- **verification**: Setup status stops reporting "Preview Service Not Enabled"; edits to a referenced entry appear in the parent page's preview.
+
+---
+
+### preview-renders-empty-for-a-restricted-user
+- **bucket**: preview-runtime
+- **symptom**: One user sees an empty or partly empty page in Live Preview / Visual Editor while colleagues on the same stack see it fully, and the published site is fine for everybody. Missing pieces can be a region, a single field, an image, or a referenced entry. Related shapes: the environment dropdown reads "No environments available" for that user alone (the role has no read permission on any environment, so there is nothing to preview against), or preview logs show `422 "The Content Type '<uid>' was not found."` for their request only.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: **By design.** Preview runs as the signed-in user and applies that user's full ACL — content types, entries, fields, locales and assets alike. Anything the user cannot read comes back empty rather than as an error the site can see. Delivery behaves differently because it uses a delivery token and applies no ACL at all, which is why the published page looks fine. So the same page legitimately renders differently for two users, and that is not a defect. A role granting read on *entries* but not on the *content type* produces the confusing case where the entry opens in the editor but preview returns 422 for it.
+- **fix**:
+  1. **Handle missing data in the site's rendering.** This is the durable fix. Preview can return an absent field, an empty reference array, a null asset or an unresolved locale for a perfectly valid reason, so components must degrade instead of throwing or rendering a blank region. A site that assumes every field is present will look broken for every restricted user.
+  2. Reproduce as the reporting user. This never shows up on an admin session, so testing as an admin proves nothing.
+  3. If the user *should* have had access, pull the role with `GET /v3/stacks/roles/{role_uid}` and compare it against what the page actually reads: content types (including referenced ones), the specific fields, the locale, the asset folders, and read access to the preview environment.
+  4. Grant read on the content type itself, not only on its entries. Granting entry access alone leaves the 422 in place.
+  5. Do not work around it by granting broader edit rights. Read access on the environment and the content types is the correct fix.
+  6. After changing the role, have the user sign out and back in before retesting. Role changes do not always apply to an existing session.
+  7. **Everyone** seeing "No environments available", not just one user, is a different problem: a missing Base URL — see `environment-base-url-misconfigured-or-missing-for-a-locale` in `faq-setup.md`.
+- **verification**: The restricted user's preview renders without gaps or errors, showing graceful fallbacks where access is limited; no `422 Content Type ... not found` in their preview requests. The environment dropdown lists the preview environment for their role.
+
+---
+
+### third-party-scripts-misbehave-inside-the-preview-iframe
+- **bucket**: preview-runtime
+- **symptom**: Ad slots, consent widgets, or other host-dependent third-party scripts intermittently fail to render inside Live Preview while working on the live site. Preview pages become unusable for pre-flight QA of those integrations.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: The preview renders inside a cross-origin iframe. Third-party scripts whose targeting or delivery logic depends on the top-level host, referrer, or first-party storage see the iframe context instead of the real site and behave differently. Not a Contentstack request failure: the calls fire and fail at the third party's delivery stage. This is inherent to rendering the site in an iframe and there is no product-side fix for it.
+- **fix**:
+  1. Where the third party allows it, add the Contentstack app origin to its allowed-referrer or allowed-domain configuration.
+  2. Use **Open in New Tab**, which renders the preview outside the iframe so the third party sees the real host. This is an existing feature, not something to request.
+  3. Where neither is possible, exclude those third-party scripts when the preview parameters are present, so authors preview content without them rather than with a broken version of them.
+- **verification**: Use Open in New Tab rather than the preview panel and confirm the third-party content renders. That difference confirms the iframe context is the trigger.
+
+---
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
new file mode 100644
index 0000000..6886b7f
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
@@ -0,0 +1,377 @@
+# Setup FAQ
+
+Setup and first-integration failures, ordered by how often they come up in practice. Each entry
+gives the symptom as users actually report it, the mechanism behind it, the fix, and a
+verification step.
+
+Read this after localising the problem to one of the four contracts in the parent skill. The
+contract tells you which section to read; this file tells you what to do.
+
+### app-fetches-from-delivery-cdn-instead-of-preview-service
+- **bucket**: setup
+- **symptom**: Live Preview / Visual Editor loads the site fine, but edits made in the entry form or the right-hand panel never appear in the preview. Content only changes after the entry is published. The Onboarding Check gets past the site-loading and SDK gates and then stops on **Preview Service Not Enabled**. Variant selection in Visual Editor also shows the base entry.
+- **frameworks**: Next.js (Pages + App Router), React, Angular, Gatsby, Vue/Nuxt, Java/Spring, framework-agnostic REST/GraphQL clients
+- **rendering_modes**: any
+- **root_cause**: The site is still calling the Content Delivery host (`cdn.contentstack.io` / `graphql.contentstack.com`) for its content. The `live_preview` hash reaches the page in the URL, but nothing in the fetch layer switches host + headers to the Preview Service, so the API returns published content. Most common with hand-rolled fetch wrappers, a BFF/middleware layer, GraphQL clients, or a separate fetch helper that bypasses the initialized Delivery SDK instance.
+- **fix**:
+  1. Generate a Preview Token against the Delivery Token you already use (Settings → Tokens → your Delivery Token → Preview Token), and enable Live Preview on the stack with a default preview environment.
+  2. If you use the Contentstack Delivery SDK: pass the same initialized Stack instance to every content fetch, and give it `live_preview: { enable: true, preview_token: <TOKEN>, host: <region preview host> }`. Do not create a second Stack instance just for `ContentstackLivePreview.init()`.
+  3. If you fetch over raw REST/GraphQL: branch on the hash before every request.
+     ```js
+     // SSR: read it off the request. CSR: use ContentstackLivePreview.hash
+     const livePreviewHash = request.query.live_preview;
+     if (livePreviewHash) {
+       headers.append("live_preview", livePreviewHash);
+       headers.append("preview_token", CONTENTSTACK_PREVIEW_TOKEN);
+       url.hostname = LIVE_PREVIEW_HOST; // e.g. rest-preview.contentstack.com
+     } else {
+       url.hostname = CONTENTSTACK_CDN_HOST; // e.g. cdn.contentstack.io
+     }
+     ```
+     For GraphQL the equivalent is swapping `graphql.contentstack.com` → `graphql-preview.contentstack.com` and adding the same two headers.
+  4. Bypass any cache layer for preview requests. Do not try to fix it with a smarter cache key: the hash is stable for the whole preview session, so any cache on this path serves the first response for the rest of it.
+- **verification**: Open the entry in Live Preview, then in DevTools → Network confirm requests go to the `*-preview.contentstack.com` host, carry `preview_token` and `live_preview` headers, and return 200. Edit a field without saving; the preview must update. The Onboarding Check should reach **Setup Complete**.
+
+---
+
+### iframe-blocked-by-x-frame-options-or-csp-frame-ancestors
+- **bucket**: setup
+- **symptom**: The Live Preview / Visual Editor pane is blank or shows "`<your-host>` refused to connect". Console shows `Refused to display '<url>' in a frame because it set 'X-Frame-Options' to 'sameorigin'` (or `deny`), or a `frame-ancestors` CSP violation. Frequently paired with a `401` on a `HEAD`/`GET` of the site root. Works on localhost, fails on the deployed dev/QA/staging host.
+- **frameworks**: framework-agnostic (server / CDN / hosting-platform header config)
+- **rendering_modes**: any
+- **root_cause**: Contentstack renders the site inside an iframe on the app origin. Any `X-Frame-Options: SAMEORIGIN|DENY` or a CSP `frame-ancestors` directive that does not include the Contentstack app origin makes the browser refuse the frame before the page can run. Platform-level deployment protection (for example a hosting provider's password protection) adds `X-Frame-Options: DENY` to the password screen itself, so even the auth prompt cannot render.
+- **fix**:
+  1. Remove `X-Frame-Options` for the preview host and use CSP instead: `Content-Security-Policy: frame-ancestors 'self' https://*.contentstack.com https://*.contentstack.io;` (`X-Frame-Options` has no allowlist syntax; a bare `SAMEORIGIN` always wins).
+  2. Apply the header on every route, not just the site root. A route that redirects to a different hostname than the configured Base URL will also fail.
+  3. If the deployment sits behind platform password protection, note that no header or query parameter can be injected into a browser-originated iframe request from Contentstack. Options: disable protection on the preview deployment, use a bypass token embedded in the Base URL, put a server-side proxy in front that injects the header, or use Live Preview → Open in New Tab (a plan-gated feature that renders outside the iframe).
+  4. Third-party SSO screens that themselves set `X-Frame-Options: DENY` cannot render in the iframe at all. Use Open in New Tab, which renders the preview outside the iframe so those screens can load.
+- **verification**: `curl -I https://<preview-host>/<some-deep-route>` and confirm no `X-Frame-Options` and a `frame-ancestors` value that includes the Contentstack app origin. Reload Live Preview; the pane should render.
+
+---
+
+### error-382-create-tracker-before-starting-live-preview-session
+- **bucket**: setup
+- **symptom**: Preview API requests fail with
+  `{"error_message":"Please create tracker before starting live preview session","error_code":382,"status":400}`
+  (a sibling variant is `{"error_message":"Please provide live preview hash in request","error_code":382}`). Often appears the moment `mode: "builder"` is set, or when the site is opened directly rather than from inside the Contentstack preview pane. Sometimes reproduces for one developer and not another on "identical" setups.
+- **frameworks**: Next.js, React, framework-agnostic REST/GraphQL clients
+- **rendering_modes**: CSR, SSR
+- **root_cause**: The `live_preview` hash sent on the request has no matching tracker document. Contentstack creates that tracker with a `POST /live-preview/tracker` when the preview session starts inside the CMS. The error means either (a) the app sent a hardcoded, stale, or hand-invented hash, (b) the app sent `live_preview=true` or an empty value instead of the real hash, or (c) the request was made outside any preview session (the site opened directly, or a custom preview tool that has no way to obtain a hash).
+- **fix**:
+  1. Never hardcode or invent a hash. Read it from `?live_preview=` on the request (SSR) or from `ContentstackLivePreview.hash` (CSR), and skip the preview host entirely when it is absent.
+  2. Confirm the tracker call fires: in DevTools → Network, look for `POST /live-preview/tracker` returning 2xx when the preview pane loads. If it never fires, the SDK did not initialize (check `enable`, the `.env` value actually parsing as `true`, and that `init()` runs on the client).
+  3. If the app proxies Contentstack through its own backend, forward the hash end to end. The front end must pass the hash it received to the backend, and the backend must put it in the `live_preview` header.
+  4. Building a preview tool entirely outside Contentstack is not supported with a Preview Token alone; the hash originates in the CMS session. Use a dedicated publishing environment for an internal preview tool instead.
+- **verification**: With the entry open in Live Preview, the network log shows a successful tracker POST followed by preview reads returning 200 with the same hash value.
+
+---
+
+### edit-tags-not-generated-or-not-spread
+- **bucket**: setup
+- **symptom**: Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar. Clicking the canvas does nothing, or selects the wrong (parent) element. `entry.$` / `post.$` is `undefined` in the app, or `data-cslp` renders as literal text instead of an attribute. Live Preview auto-refresh often still works, which makes it look like a Visual Editor bug.
+- **frameworks**: React, Next.js, Vue, Angular, Gatsby, Blazor/.NET, jQuery
+- **rendering_modes**: any
+- **root_cause**: Tags need two independent things and teams usually do only one: `addEditableTags()` must run on every fetched entry, **and** the generated `$` attributes must be spread onto the DOM elements that render each field. `mode: "builder"` does not generate tags — it only controls where **Start Editing** redirects. Four ways this goes wrong: the call is missing entirely (commonly commented out during a migration); `tagsAsObject` is `false` or omitted, producing a `data-cslp` string React cannot spread; the content type **title** is passed instead of its **uid**; or the call is correct but nothing spreads the result into the markup.
+- **fix**:
+  1. Call it on every entry right after fetching, including referenced entries: `addEditableTags(entry, contentTypeUid, true, locale)`. The third argument must be `true` for React and JSX.
+  2. Pass the content type **uid**, not its display title.
+  3. Spread onto the element that renders the value: `<h1 {...post.$?.title}>{post.title}</h1>`.
+  4. Mirror the data path exactly. References come back as arrays, so it is `post.author[0].$?.name`, not `post.$?.author.name`.
+  5. Tag the leaf element that holds the value, one `data-cslp` per element. Tagging a wrapper group instead of the field makes Visual Editor select the wrong field.
+  6. Check nothing strips them at build time: `cleanCslpOnProduction: true` removes `data-cslp` from the DOM, and `PURGE_PREVIEW_SDK=true` no-ops the whole SDK.
+  7. For GraphQL, the response shape itself breaks tag paths — see `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md` for the normalizer that has to run before `addEditableTags()`.
+  8. If you only want auto-refresh and not in-context editing, use `mode: "preview"` rather than `mode: "builder"` with no tags.
+- **verification**: In DevTools on the previewed page, `document.querySelectorAll('[data-cslp]').length` must be greater than 0, and a rendered field must carry `data-cslp="<content_type_uid>.<entry_uid>.<locale>.<field_path>"`. Hovering it in the canvas should highlight it, and clicking should focus the matching field in the form panel.
+
+---
+
+### preview-url-does-not-resolve-to-the-app-route
+- **bucket**: setup
+- **symptom**: Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited. Navigating inside the preview 404s. Sometimes the pane says "You are currently previewing a different webpage". Affects entries whose real URL is nested, taxonomy-driven, multi-tenant, or has no `url` field at all.
+- **frameworks**: Next.js, React, framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: By default the preview URL is `environment Base URL` + the entry's `url` field. That only works when app routing maps 1:1 to the `url` field. Nested paths, custom route prefixes, several content types with different URL shapes, multiple sites served from one stack, or a URL stored in a custom text field instead of the built-in `url` field all break the concatenation.
+- **fix**:
+  1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL) with pattern placeholders such as `/blog/{{entry.category}}/{{entry.slug}}`, plus Base URL aliases when several hostnames map to one stack. This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated and has to be enabled on the account.
+  2. With Custom Preview URLs enabled, tell the editor which entry each page is by calling `setPageContext({ entryUid, contentTypeUid })` on every page (Live Preview Utils v4.4.4+). Fallbacks: the `window.__CS_PAGE_CONTEXT__` global, or `<meta name="contentstack:entry-uid">` and `<meta name="contentstack:content-type-uid">`. **This only has an effect when Custom Preview URLs is configured and enabled on the plan.** Without it the editor resolves by URL alone and the call is silently ignored — it does not error, so a missing feature flag looks like `setPageContext` not working.
+  3. Do not narrow the environment Base URL to one content type's prefix (for example `.../inspiration/articles/`) — that fixes one content type and breaks all others.
+  4. Verify the entry's `url` field actually corresponds to a route the app serves, and that the route renders the content type you expect.
+- **verification**: Open entries from several content types (root page, nested page, no-URL page). Each should load its own page in the preview pane, and the URL bar in the pane should show the real route.
+
+---
+
+### sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade
+- **bucket**: setup
+- **symptom**: Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump breaks a previously working integration — `setConfigFromParams` disappears, `ReferenceError: window is not defined` in server code, the Edit button suddenly renders in production, or `Live_Preview_SDK: To use edit tags, you must provide the stack API key`.
+- **frameworks**: Next.js, React, Gatsby, Angular
+- **rendering_modes**: any
+- **root_cause**: Feature availability is version-gated and majors carry breaking changes that were not always documented. Pinned-old dependency policies (auto-update disabled) leave teams on v1.x where the required callbacks do not exist. The v2 → v3 jump removed `setConfigFromParams` (its replacement reads `window`, which throws in SSR) and made `stackDetails.apiKey` mandatory for edit tags.
+- **fix**:
+  1. Meet the minimums: Live Preview Utils **v3.0+** and Delivery SDK **v3.20.3+** for Visual Editor; **v4.4.4+** if you use `setPageContext()`.
+  2. Pass `stackDetails: { apiKey, environment }` explicitly in `init()` — v2+ no longer derives the API key from the Stack object for edit tags.
+  3. In SSR, stop calling `setConfigFromParams`. Read the query parameters from the request and apply them with `livePreviewQuery()` instead of relying on any SDK helper that touches `window`.
+  4. Pin one delivery method for the SDK. Mixing an npm install with an ESM/CDN `<script type="module">` import of a different version produces version-specific behaviour differences (for example the Edit button appearing after a CDN bump).
+  5. Read the SDK release notes before a major bump rather than the setup docs alone.
+- **verification**: `npm ls @contentstack/live-preview-utils @contentstack/delivery-sdk` (or `contentstack`) shows versions at or above the minimums, and only one copy of the preview SDK is loaded in the page.
+
+---
+
+### environment-base-url-misconfigured-or-missing-for-a-locale
+- **bucket**: setup
+- **symptom**: The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wrong path or the site root; a specific locale cannot be previewed at all while others work; the preview pane keeps showing the previous environment's URL after switching.
+- **frameworks**: framework-agnostic (stack configuration)
+- **rendering_modes**: any
+- **root_cause**: Live Preview builds the iframe URL from the environment's Base URL for the entry's locale. If any environment is missing a Base URL for that locale, the whole selector can be disabled for the locale. A Base URL missing its locale segment (for example `https://host` instead of `https://host/en`) resolves to the wrong page. A Base URL without a scheme (`localhost:3001` instead of `http://localhost:3001`) silently fails. Locales with no configured Base URL are not supported in Visual Editor at all.
+- **fix**:
+  1. Settings → Environments: set a Base URL for **every** environment/locale pair you intend to preview, including the locale path segment where the app uses one.
+  2. Always include the scheme (`http://` or `https://`).
+  3. For a locale that only exists via fallback, either add a Base URL that resolves fallback content (and add `include_fallback=true` on your queries) or accept that Visual Editor cannot render it.
+  4. Environment publish permissions affect which Base URLs a role can select; a restricted user can still preview by typing the correct Base URL into the Live Preview URL bar.
+  5. If **only one user** sees "No environments available" while colleagues do not, it is not the Base URL — that user's role has no read permission on any environment. See `preview-renders-empty-for-a-restricted-user` in `faq-preview-runtime.md`.
+- **verification**: For each locale, open the Live Preview environment dropdown — every environment should be selectable and the resolved URL should load the correct localized page.
+
+---
+
+### edit-button-rendered-outside-a-live-preview-session
+- **bucket**: setup
+- **symptom**: The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or the `#cslp-tooltip` button element is injected into `document.body` on production even when not visible (usually caught in an accessibility audit). Sometimes intermittent, correlating with client-side route changes rather than fresh page loads.
+- **frameworks**: Next.js (App Router especially), React
+- **rendering_modes**: CSR, SSR
+- **root_cause**: With `editButton.enable: true`, the SDK gates the button on `enable` + `inIframe()` + the `cslp-buttons` query parameter. It never checks the `live_preview` hash or any active-session signal, so a normally loaded page with the SDK initialized renders the button by design. Teams that gate `init()` on a server-read hash also get bitten by App Router soft navigation, which does not re-run that server-side gate while the SDK's button instance persists across route changes.
+- **fix**:
+  1. Add `editButton: { enable: true, exclude: ['outsideLivePreviewPortal'] }`. Outside the iframe `inIframe()` is false, so the button will not render, while Live Preview inside the pane keeps working.
+  2. If Live Preview is not used on production at all, strip it from the production build: `cleanCslpOnProduction: true` removes `data-cslp` from the DOM, and the `PURGE_PREVIEW_SDK=true` build flag no-ops the SDK entirely.
+  3. Do not rely on a server-side hash check alone in an App Router app; soft navigation will not re-evaluate it.
+- **verification**: Load the production URL in a normal tab with DevTools open. `document.getElementById('cslp-tooltip')` should be absent, and no `data-cslp` attributes should be present if `cleanCslpOnProduction` is set.
+
+---
+
+### cors-blocked-on-preview-api-requests
+- **bucket**: setup
+- **symptom**: `Access to fetch at 'https://<region>-rest-preview.contentstack.com/v3/...' from origin '<site origin>' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource`, frequently alongside a `401 (Unauthorized)` on the same request. Works on localhost, fails on the deployed dev/staging host.
+- **frameworks**: Gatsby, Angular, Next.js, React
+- **rendering_modes**: CSR mainly
+- **root_cause**: Two distinct problems that surface as one console message. (1) The site's own Content Security Policy (`connect-src` / `default-src`) does not allow calls to Contentstack hosts, which most frameworks restrict by default in production but not in local dev. (2) The preview request is genuinely rejected (bad or wrong-type token), and the error response carries no CORS headers, so the browser reports it as a CORS failure instead of a 401. There is no per-stack "CORS allowlist" on the Contentstack side to add origins to.
+- **fix**:
+  1. Widen the site's CSP to the whole Contentstack domain rather than individual hosts. Listing only `app.contentstack.com` and `rest-preview.contentstack.com` has repeatedly been insufficient; `https://*.contentstack.com` (and `https://*.contentstack.io` where delivery/asset hosts are used) is what worked.
+  2. Fix the 401 separately: confirm you are sending a valid **Preview Token** (not a Delivery Token, not a Management Token) in the `preview_token` header, and regenerate it if in doubt. Resolve the CSP first, or the server error stays masked.
+  3. Recheck env vars after a stack migration or API key change — a stale API key produces the same 401-behind-CORS shape.
+- **verification**: `curl` the same preview URL with the same headers from a terminal. A 200 proves the token is valid and the remaining problem is browser-side CSP. In the browser, the request should complete with `Access-Control-Allow-Origin` present.
+
+---
+
+### ssr-stack-instance-shared-or-duplicated
+- **bucket**: setup
+- **symptom**: Two opposite failures from the same mistake. **(A) Hash never arrives:** `init()` succeeds and `ContentstackLivePreview.hash` is populated on the client, but server-rendered pages still return published content. Deterministic, and only the author notices. **(B) Preview state leaks out:** intermittent, user-dependent wrong content, and the **production** site failing with `The Live Preview tracker is invalid or no longer exists. Create a new tracker to continue.` (error_code 382) or `The requested tracker was created for the 'dev' branch. Access using the 'main' branch is not allowed.`; preview stalling after a while; `TypeError: Cannot read properties of undefined (reading 'uid')` after idle hours in production; two editors seeing each other's content; personalization on the public site stopping resolving per visitor because a cached preview render is being served instead. This one reaches real visitors.
+- **frameworks**: Next.js (App Router and Pages Router), Express/Node, Nuxt
+- **rendering_modes**: SSR | edge
+- **root_cause**: In SSR the SDK does not fetch content. It puts `?live_preview=<hash>&content_type_uid=...&entry_uid=...` on the URL and reloads, and preview state lives **on the Stack instance**. Failure (A) is having two instances: a long-lived "default" Stack for page queries plus a second Stack passed only to `init()`, so the hash never lands on the instance that queries. Failure (B) is having one module-level instance shared across requests: once any request puts it into preview mode, unrelated requests inherit it, and ordinary delivery traffic starts hitting the preview service with a hash that has expired (the tracker lasts about a day; the session hash rotates roughly every 30 minutes) or belongs to another branch. Under concurrency requests can also overwrite each other's config mid-flight.
+- **fix**:
+  1. Create a fresh Delivery SDK instance **per request**. Do not share a module-level Stack, and pass the instance down through request-scoped context rather than importing a singleton. This one change fixes both failures.
+  2. Read the hash off the incoming request each time and apply it to that instance: `stack.livePreviewQuery({ live_preview: hash, contentTypeUid, entryUid })`.
+  3. Call `livePreviewQuery(...)` **unconditionally** per request, with empty values when there is no hash. Calling it only when a hash exists leaves the previous request's hash in place.
+  4. Run every query that should show drafts on that instance. A query on an un-hashed instance returns published content.
+  5. Drop any separate "live preview only" Stack. `init()` does not need a Stack in SSR.
+  6. Never reuse a hash captured in a preview session on a normal page load, and never hardcode or persist one. Keep the branch consistent: a tracker created against one branch cannot be used against another.
+  7. Ignore `No ack listener found` / `NO_REQUEST_LISTENER_FOUND` here. Routine postMessage chatter that appears on working setups; it does not affect SSR content.
+- **verification**: Log the hash on the server per request and confirm it is non-empty and changes per session, and that preview requests hit the preview host. Editing a field without saving should change the SSR output on reload. Then load the production URL directly on a cold server and confirm requests go to the CDN host with no `live_preview` header, and that mixed preview / non-preview traffic does not contaminate either side.
+
+---
+
+### nextjs-app-router-init-must-run-in-a-client-component
+- **bucket**: setup
+- **symptom**: In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit tags render but do nothing, or nothing at all happens when the entry is edited. The same code works in a Pages Router project.
+- **frameworks**: Next.js App Router
+- **rendering_modes**: SSR, CSR
+- **root_cause**: `ContentstackLivePreview.init()` has to run in the browser. In App Router, code placed in a server component or in the root layout module body never executes client-side, so the SDK never installs its postMessage listeners and never advertises SSR mode.
+- **fix**:
+  1. Create a dedicated client component and call `init()` from an effect:
+     ```tsx
+     "use client";
+     import ContentstackLivePreview from "@contentstack/live-preview-utils";
+     import { useEffect } from "react";
+     export default function LivePreviewClient() {
+       useEffect(() => { ContentstackLivePreview.init({ /* ... */ }); }, []);
+       return null;
+     }
+     ```
+  2. Render that component from the root layout.
+  3. On the server side, read `live_preview`, `content_type_uid`, and `entry_uid` from `searchParams` (or from request headers set in middleware) and apply them with `livePreviewQuery()` per request. Do not expect the client SDK to hand the hash to server code.
+  4. Keep the SDK init code in its own module so re-renders do not reset the configuration.
+- **verification**: With the entry open in Live Preview, the iframe URL contains `?live_preview=...`, the console reports SSR mode where applicable, and the server sees the hash on each request.
+
+---
+
+### legacy-management-token-setup-not-migrated-to-preview-token
+- **bucket**: setup
+- **symptom**: "Preview Service Not Enabled" shows in the preview panel on a setup that otherwise works. Or a setup copied from older docs / an older starter app passes a `management_token` to `live_preview` and fails with 401/422 after tokens were rotated.
+- **frameworks**: Next.js, Gatsby, React, framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: The original Live Preview implementation read drafts through the CMA using a read-only Management Token. That was replaced by the Preview Service and a read-only Preview Token issued against a Delivery Token. Applications left on the legacy path still work but are flagged, and older starter apps / source plugins shipped `management_token` in the `live_preview` config long after the docs switched to `preview_token`.
+- **fix**:
+  1. Generate a Preview Token on the Delivery Token you already use.
+  2. Replace `live_preview.management_token` with `live_preview.preview_token` and point `live_preview.host` at the region's `*-rest-preview.contentstack.com`.
+  3. Update any framework source plugin to a version whose build output actually reads `preview_token` (some releases had source and build output disagreeing).
+  4. Remove the Management Token from client-side code entirely. Stack API Key, Delivery Token, and Preview Token are read-only and safe to ship to the browser; a Management Token has write access and is not.
+- **verification**: No Management Token appears in any client bundle or preview request; the "Preview Service Not Enabled" card is gone and the Onboarding Check reaches Setup Complete.
+
+---
+
+### branch-or-alias-mismatch-between-app-token-and-entry
+- **bucket**: setup
+- **symptom**: Preview opens for pages that already exist on the main branch but never shows updates, and any page that exists only on the working branch 404s. Or: `error_code: 901, "Access denied. You have insufficient permissions to perform operation on this branch"`.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: Two misalignments. The deployed preview site is pinned to one branch (often a production replica on `main`) while the author edits on another. Or the Delivery/Preview Token scope does not include the branch or alias being previewed, which surfaces as the 901. Aliases themselves resolve to their target branch correctly, so an alias in the URL is not a cause.
+- **fix**:
+  1. Make the branch the app queries match the branch the entry is edited on — either configure a per-branch preview deployment or read the branch from the preview request and pass it as the `branch` header.
+  2. Extend the Delivery Token scope to include every branch **and** alias you preview against. Adding a branch to the scope after the fact is what cleared the 901.
+  3. Aliases are fine to use in preview URLs. If you scope a token to an alias, confirm the alias points at the branch you think it does, since repointing an alias silently changes what preview reads.
+- **verification**: Edit an entry that exists only on the non-main branch; it should load and update in the preview. Preview requests should carry the expected `branch` header and return 200.
+
+---
+
+### wrong-region-hosts-in-sdk-and-preview-config
+- **bucket**: setup
+- **symptom**: Live Preview never activates or the preview panel reports the service is not enabled, even though the stack settings look correct. Requests in the network tab go to the default North America hosts while the stack lives in another region.
+- **frameworks**: Next.js, Angular, React
+- **rendering_modes**: any
+- **root_cause**: Region is not inferred. Each of the delivery host, preview host, API host, and app host has a region-specific name, and the SDK defaults to the AWS NA set. A stack in EU / Azure / GCP that is left on the defaults gets rejected or served from the wrong region.
+- **fix**:
+  1. Set every host explicitly and consistently for the stack's region. All four move together:
+     - delivery: `cdn.contentstack.io` → e.g. `eu-cdn.contentstack.com`, `azure-na-cdn.contentstack.com`, `gcp-eu-cdn.contentstack.com`
+     - preview: `rest-preview.contentstack.com` → e.g. `eu-rest-preview.contentstack.com`, `azure-na-rest-preview.contentstack.com`, `gcp-eu-rest-preview.contentstack.com`
+     - GraphQL preview: `graphql-preview.contentstack.com` → the region-prefixed equivalent
+     - app host (`clientUrlParams.host`): `app.contentstack.com` → e.g. `eu-app.contentstack.com`, `gcp-na-app.contentstack.com`
+  2. Use the SDK's `region` option where available rather than hand-writing hosts, and make sure a hardcoded `host` does not override it.
+  3. Re-check every host after a stack migration; the API key changes too.
+- **verification**: In DevTools → Network, every Contentstack request goes to a host carrying the correct region prefix, and returns 200.
+
+---
+
+### locale-defaults-to-en-us-in-init
+- **bucket**: setup
+- **symptom**: Start Editing / the Edit button opens Visual Editor or the entry editor with `locale=en-us` even though the stack has no `en-us` language, producing a 404 or a "Language not found" toast. Works on one deployment and not another with identical code.
+- **frameworks**: React, Angular, framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: When `stackDetails.locale` is not set in `init()`, the SDK tries to infer the locale by finding an element with `data-cslp` in the DOM and reading the locale out of it. If no tagged element is present at that moment, it falls back to `en-us`. That fallback is invalid on stacks whose master language is something else, and it explains why the same code behaves differently on two deployments (one happens to have tagged content in the DOM, the other does not).
+- **fix**:
+  1. Set the locale explicitly:
+     `ContentstackLivePreview.init({ stackDetails: { apiKey, environment, locale: '<your-locale>' } })`.
+  2. Also pass the locale to `addEditableTags(entry, contentTypeUid, true, locale)` so the generated `data-cslp` carries the right locale.
+  3. Do not add a dummy `en-us` language to the stack as a workaround.
+- **verification**: Click an edit tag; the URL that opens should carry your real locale, and the entry should load without a "Language not found" error.
+
+---
+
+### start-editing-button-cannot-be-hidden-in-editor-mode
+- **bucket**: setup
+- **symptom**: The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `mode: "builder"` is set, including production. Setting `editButton.enable: false` removes the per-field edit tags but not this button.
+- **frameworks**: React, Next.js, Gatsby
+- **rendering_modes**: any
+- **root_cause**: "Start Editing" is a separate control from the per-field edit tags. It is enabled implicitly by `mode: "builder"` and has its own config key, which was not obvious from the setup docs. `editButton` governs only the field-level tags.
+- **fix**:
+  1. Disable it explicitly:
+     ```js
+     ContentstackLivePreview.init({
+       mode: "builder",
+       editInVisualBuilderButton: { enable: false },
+     });
+     ```
+  2. Better for production builds: do not initialize the SDK there at all, or use `PURGE_PREVIEW_SDK=true` / `cleanCslpOnProduction: true`.
+- **verification**: Load the production URL; no floating Start Editing button. Load the preview environment; the button is present when you want it.
+
+---
+
+### onboarding-check-card-not-visible-or-appears-unexpectedly
+- **bucket**: setup
+- **symptom**: A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days later on its own. Conversely, other teams never see the status card at all when they want to diagnose a failing integration.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: Each product keeps its own stack setting, and they do not agree on what "unset" means. Timeline treats an unset value as visible. Live Preview treats an unset value as hidden. Visual Editor depends on whether its settings object exists at all. Meanwhile the Visual Experience settings screen renders the toggle as on whenever the value is unset, so a stack that never explicitly saved the setting can show the toggle on while Live Preview behaves as though it is off. Separately, the checks run asynchronously with a timeout, so the card can appear briefly on a correctly configured site whose first preview fetch is slow, then clear itself once the request lands.
+- **fix**:
+  1. Open Settings → Visual Experience and click Save without changing anything. The form always submits all three products' visibility keys, and an unset value arrives in the form as on, so a single save writes an explicit `true` for Live Preview, Visual Editor and Timeline at once. That removes the unset ambiguity and makes all three agree.
+  2. Check the setting for the product actually being used. Live Preview, Visual Editor and Timeline each have their own, under Settings → Visual Experience.
+  3. Read the one step the card shows. The gates run as an ordered chain that stops at the first failure, so the card names a single gate — that is the configuration gap, and every gate before it has already passed.
+  4. If it still does not appear for one user but does for others, that user dismissed it. The suppression is stored per stack in their browser, and no stack-level save clears it — they need to clear site data for the app origin, or use another browser profile.
+  5. If the card flashes then clears on a working site, no action is needed — the first preview request simply arrived after the check timeout.
+- **verification**: Open an entry in the product in question and confirm the status card appears. If it does not appear after saving the setting explicitly, it is being suppressed locally rather than by the stack setting.
+
+---
+
+### visual-experience-navigation-missing-for-the-stack
+- **bucket**: setup
+- **symptom**: The "Visual Experience" / builder-mode option does not appear in the Contentstack navigation at all, so the team cannot open the builder and assumes their integration is wrong.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: Entirely CMS-side. Three things gate the navigation entry: plan entitlement, organization-level enablement, and the stack's own Live Preview setting. **Nothing in the application affects it.** If the nav entry is absent, stop looking at the site: no SDK version, `init()` option, edit tag or fetch change can make it appear. Only the third of those is visible to the customer — plan entitlement and org enablement cannot be checked from the CMS UI.
+- **fix**:
+  1. Have the user check the one thing they can see: Live Preview enabled on the stack, under Settings → Visual Experience.
+  2. If that is on and the navigation entry is still missing, stop there and contact Contentstack Support. Whether the plan includes Visual Editor, and whether it is enabled for the organization, are not things the user can verify or change, so do not send them looking.
+- **verification**: The Visual Experience option appears in the entry's navigation. Only once it opens is there any point looking at the integration itself.
+
+---
+
+### third-party-cookies-blocked-inside-the-preview-iframe
+- **bucket**: setup
+- **symptom**: The site renders in the preview pane but behaves as if logged out, or without personalization, locale or currency preferences. Anything driven by the site's own cookies is lost.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: Inside the preview iframe the site is a third-party context relative to the Contentstack app origin, and browsers block third-party cookies by default. Only cookies set with `SameSite=None; Secure` survive, and that attribute deliberately weakens the protection that stops a cookie being sent from other sites.
+- **fix**:
+  1. **Start by asking whether the cookie matters here at all.** Preview is for reviewing content, not for exercising session state. Most sites do not need their cookies to render the page an author is checking, and the right outcome is usually that the site degrades gracefully in the iframe rather than that the cookie policy changes.
+  2. If the content genuinely cannot render without it, prefer an alternative to loosening cookies: drive the preference from a query parameter or header the preview URL can carry, or give preview a dedicated path that does not depend on the cookie.
+  3. Only if neither works, set `SameSite=None; Secure` — **and only on the preview deployment, never on production**. Scope it to the preview host so the production site keeps its stricter policy. Do not apply it site-wide to make preview convenient.
+  4. Cookie-gated content needs a preview-specific auth path regardless. The iframe cannot inherit the parent's session.
+- **verification**: The page renders in the intended state inside the preview iframe, and the production site's cookies still carry their original `SameSite` policy. Confirm the second part explicitly — this is the step most likely to be applied too broadly.
+
+---
+
+### chrome-local-network-access-blocks-preview-of-localhost
+- **bucket**: setup
+- **symptom**: A previously working local Live Preview setup breaks with
+  `Access to fetch at 'http://localhost:5173/' from origin 'https://<region>-app.contentstack.com' has been blocked by CORS policy: Permission was denied for this request to access the 'unknown' address space`.
+  Chrome only; Safari unaffected. Downgrading the SDK does not help.
+- **frameworks**: framework-agnostic (Vite, Next.js dev servers)
+- **rendering_modes**: any
+- **root_cause**: Chrome's Local Network Access / Private Network Access restriction. A public HTTPS origin (the Contentstack app) reaching a private or loopback address (`localhost`) now requires an explicit browser permission. Nothing changed in the SDK or in Contentstack.
+- **fix**:
+  1. Accept the Chrome "Local network access" permission prompt for the Contentstack app origin, or enable it manually in Chrome → Site settings for that origin.
+  2. If you would rather not ask every author to grant it, preview against a deployed HTTPS host instead of `localhost`.
+- **verification**: Reload Live Preview in Chrome; the `OPTIONS`/`GET` to the local dev server succeeds and the iframe renders.
+
+---
+
+### cslp-tags-contain-the-literal-string-undefined
+- **bucket**: setup
+- **symptom**: `data-cslp` attributes in the DOM contain `undefined` where the entry uid should be. Inline editing does not work and edit mapping silently fails on those elements.
+- **frameworks**: Next.js
+- **rendering_modes**: SSR
+- **root_cause**: `addEditableTags()` was called once with an array or collection of entries rather than with a single entry object. It reads `uid` off the object it is handed; an array has no `uid`, so every generated tag interpolates `undefined`.
+- **fix**:
+  1. Loop the result set and call the helper per entry:
+     ```
+     for (const entry of result) {
+       addEditableTags(entry, contentTypeUid, true, entry.locale);
+     }
+     ```
+  2. Pass each entry's own content type uid, not the page's, when the collection mixes content types.
+  3. Confirm the object you pass actually has a `uid` property; if your fetch layer strips system fields, restore them first.
+- **verification**: Search the rendered HTML for `cslp` and confirm no attribute value contains `undefined`.
+
+---
+
+### ssg-preview-needs-csr-mode
+- **bucket**: setup
+- **symptom**: Live Preview on a statically generated site is unreliable or simply shows build-time content: blank or black screens, flicker, an auth prompt on reload, or edits that never appear no matter what. The hash is on the URL and never reaches the fetch.
+- **frameworks**: Next.js, Gatsby, Astro, framework-agnostic
+- **rendering_modes**: SSG/ISR
+- **root_cause**: Two halves of the same mistake. A prerendered page cannot read query parameters at request time, so the `live_preview` hash can never reach a build-time data fetch — static output is published-only content by definition. And in SSR mode the SDK reloads the page after every edit, which on a static site just re-serves the same prerendered HTML. SSG is supported, but only in CSR mode.
+- **fix**:
+  1. Initialize with `ssr: false`. Edits then fire an `onEntryChange` callback instead of a page reload.
+  2. Pass `stackSdk` in the init config. It is mandatory in CSR mode, and it is also what the SDK uses to default `ssr`, so omitting it silently selects SSR behaviour.
+  3. Implement `onEntryChange`: subscribe on the client, refetch the entry, update the UI. No rebuild is needed.
+  4. Remove any `Stack.livePreviewQuery()` call from middleware. It is SSR-only and must not run on a static route.
+  5. If the site mixes static and server-rendered routes, make the mode conditional per route rather than per app.
+  6. If a route must stay server-rendered, make only the preview path dynamic: detect `live_preview` in `searchParams` and force that request dynamic. Do not combine a whole-route cache directive with a page that needs `searchParams` — split the condition at the fetch, not the route.
+- **verification**: Edit a field. The preview updates in place with no page reload, no flicker and no auth prompt, and the network tab shows a request to the preview host carrying the unsaved value.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
new file mode 100644
index 0000000..52e93ba
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
@@ -0,0 +1,39 @@
+# Timeline FAQ
+
+Timeline previews an entry at a point in time. It shares the Live Preview SDK and the same preview
+host, but it is a distinct product: it has its own Onboarding Check with three gates rather than
+five (see [onboarding-check.md](onboarding-check.md)), and it carries a `preview_timestamp` alongside the usual
+`live_preview` hash.
+
+If plain Live Preview does not work, fix that first — everything here assumes the preview path is
+already good.
+
+### timeline-preview-timestamp-ignored-or-dropped
+- **bucket**: preview-runtime
+- **symptom**: Timeline preview shows the wrong point in time — either the current version regardless of the date picked, or version 1 of the entry for every timestamp. Reference-field changes that render correctly on the live site, in Live Preview, and in Visual Editor do not show in Timeline. Clicking an internal link inside Timeline preview loses the timestamp and the page reloads twice.
+- **frameworks**: Next.js, React, framework-agnostic
+- **rendering_modes**: CSR | SSR
+- **root_cause**: Timeline adds `preview_timestamp` to the iframe URL alongside the `live_preview` hash, and the site must forward **both** to the preview service. Common failures: (a) the app only forwards the hash; (b) the app calls `stack.livePreviewQuery()` manually on the client and passes the hash without `preview_timestamp`, overwriting what the SDK had; (c) client-side internal navigation rewrites the iframe URL and drops the query params, so the next render has no timestamp (the double reload is Timeline re-injecting it); (d) a Timeline tracker is a different tracker type than a Visual Editor tracker, so a hash captured from one context does not work in the other.
+- **fix**:
+  1. On the server, read `preview_timestamp` from the request URL on every request and pass it with the hash: `stack.livePreviewQuery({ live_preview: hash, preview_timestamp: ts, content_type_uid, entry_uid })`.
+  2. On the client, prefer letting the SDK read the params from `document.location` — do not call `livePreviewQuery()` yourself. If you must, always include `preview_timestamp` next to the hash.
+  3. Preserve `live_preview` and `preview_timestamp` across client-side route changes, or force a full navigation inside preview. Use Timeline's URL navigation box rather than in-page link clicks when demoing.
+  4. Do not reuse a hash across contexts. A Timeline hash comes from the Timeline preview page's tracker call; a Visual Editor hash comes from Visual Editor.
+  5. Append the params correctly when the base URL already carries a query string, rather than overwriting the existing one.
+- **verification**: Pick a future scheduled-publish marker; the request to the preview host should carry both headers and the response `_version` should match the version expected at that timestamp.
+
+---
+
+### timeline-compare-highlights-no-differences
+- **bucket**: visual-editor
+- **symptom**: Timeline **Compare Website** renders both versions but highlights no differences between them.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: Highlight Differences works by matching changed fields to DOM elements through their `data-cslp` attributes. It needs live edit tags enabled on the site **and** a `data-cslp` physically present on the element that renders the changed field. Where the tag coverage is thin, or the specific field that changed carries no tag, the diff has nothing to attach the highlight to and the comparison looks empty even though both versions rendered.
+- **fix**:
+  1. Confirm live edit tags are enabled and rendered — see `edit-tags-not-generated-or-not-spread` in `faq-setup.md`.
+  2. In the Timeline iframe, run
+     `[...document.querySelectorAll('[data-cslp]')].map(el => ({tag: el.tagName, cslp: el.getAttribute('data-cslp')}))`
+     and confirm the **specific field you changed** appears in that list.
+  3. If the changed field has no tag, add it and retest.
+- **verification**: Change one plain text field in a release, open Timeline → Compare Website, and confirm that element is highlighted.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
new file mode 100644
index 0000000..bc50f2c
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -0,0 +1,100 @@
+# Visual Editor FAQ
+
+In-canvas behaviour once Live Preview itself is confirmed working: edit-tag resolution, the empty-block
+affordance, and what the canvas does with the site's own clicks. Live Preview refreshing correctly while
+the canvas misbehaves points here.
+
+If nothing on the canvas is editable at all, start with `edit-tags-not-generated-or-not-spread` in
+`faq-setup.md` — that is setup contract 2, and everything here assumes it is met.
+
+### cslp-not-rebased-to-referenced-entry
+- **bucket**: visual-editor
+- **symptom**: Edit tags on fields that come from a **referenced** entry do nothing when clicked. Tags on the page's own fields work. Console may show `{code: 'NO_REQUEST_LISTENER_FOUND', message: 'contentstack-adv-post-message: No request listener found for event "scroll"'}`, but that message is routine and appears on healthy setups too — treat it as incidental, not as the identifying evidence. Diagnose from the tags themselves.
+- **frameworks**: React, Next.js, framework-agnostic
+- **rendering_modes**: CSR, SSR
+- **root_cause**: `addEditableTags()` rebases a tag onto the referenced entry only when the resolved reference object carries both `uid` and `_content_type_uid`. Without them the tag stays anchored to the parent entry (`product.<parent_entry_uid>.<locale>.<reference_field>.<index>.<field>`), so there is no entry to navigate to. Common causes: references fetched separately and merged by hand (which drops those keys), or a GraphQL query that omits `system`. Hardcoding `data-cslp` by hand is a related failure — the referenced entry's uid and content type uid are not the ones being edited.
+- **fix**:
+  1. Inspect the referenced field in DevTools. Working shape is `<referenced_ct_uid>.<referenced_entry_uid>.<locale>.<field>`. If you see the parent entry's uid, this is the bug.
+  2. REST / Delivery SDK: resolve references with `includeReference()` / `include[]` so resolved objects keep `uid` and `_content_type_uid`.
+  3. GraphQL: request `system { uid, content_type_uid, locale }` on every reference.
+  4. If references are fetched separately, either preserve those two keys when merging, or call `addEditableTags()` on each referenced entry with its own content type uid.
+  5. Never hardcode `data-cslp` — always read the value the SDK put on the entry object.
+- **verification**: Click the edit tag on a referenced field; the CMS should open the referenced entry's editor and scroll to that field.
+
+---
+
+### locale-case-mismatch-lowercased-cslp
+- **bucket**: visual-editor
+- **symptom**: Visual Editor will not initialize for any non-fallback locale on an older stack, while Live Preview works. Locales defined with mixed case (for example `en-GB`) never match; only the fallback locale partially works, and updates still fail.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: `addEditableTags()` lowercases the locale segment when it builds `data-cslp`, and it does so **by default** — `useLowerCaseLocale` defaults to `true`. The generated tags therefore never match a stack whose locale codes were created with uppercase characters. Newer stacks create locales lowercase by default, which is why this is specific to older stacks. The fix is an opt-out flag, not a change in default behaviour.
+- **fix**:
+  1. Pass the opt-out as the fifth argument:
+     `addEditableTags(entry, "<content_type_uid>", true, locale, { useLowerCaseLocale: false });`
+     `addEditableTags` is an alias of `addTags` in `@contentstack/utils`; the option is typed as `options?: { useLowerCaseLocale?: boolean }`.
+  2. Confirm your `@contentstack/utils` version accepts a fifth argument. If your installed `addEditableTags` signature stops at `locale`, upgrade — 1.9.1 has it. Do not rely on the flag silently working on an older version; an extra argument is ignored without error.
+  3. Alternatively, normalise the stack's locale codes to lowercase — but only if nothing else depends on the existing casing.
+- **verification**: `data-cslp` values carry the locale in the stack's own casing (for example `...en-GB...`, not `...en-gb...`), and the editor opens for a non-fallback locale.
+
+---
+
+### empty-fields-are-not-clickable-on-the-canvas
+- **bucket**: visual-editor
+- **symptom**: An empty rich text field renders with zero height in preview mode, so there is nothing to click and the author cannot start editing it from the canvas. Same class of problem for any field that renders nothing when empty.
+- **frameworks**: React (reported); applies to any frontend
+- **rendering_modes**: any
+- **root_cause**: The canvas can only target what the page renders. A field whose empty state produces no DOM box has no hit area for the click-to-edit overlay.
+- **fix**:
+  1. Render a placeholder element for empty fields when the page is in preview or builder mode, so the field has a clickable box.
+  2. Detect preview/builder mode through the SDK rather than threading a prop through every nested component.
+  3. Give the placeholder a minimum height and keep the `data-cslp` attributes on it so the overlay targets it correctly.
+  4. This is about a **scalar field whose empty state renders no box**. An empty modular-block or multiple field is handled differently — the SDK draws its own "+ Add Component" affordance if the wrapper is marked correctly; see `empty-block-add-button-not-appearing-or-failing`.
+- **verification**: Clear a rich text field, reload the canvas, and confirm the empty field is still clickable and opens the correct field in the form.
+
+---
+
+---
+
+### empty-block-add-button-not-appearing-or-failing
+- **bucket**: visual-editor
+- **symptom**: A page or component with an empty modular-block / multiple field shows no "+ Add Component" affordance, so authors have to go to the form panel to add the first block.
+- **frameworks**: React, Next.js
+- **rendering_modes**: CSR, SSR
+- **root_cause**: The empty-block placeholder only renders when the wrapper carries **both** the `VB_EmptyBlockParentClass` class (exported by the SDK; its literal value is `visual-builder__empty-block-parent`) and a `data-cslp` pointing at the block field itself. Miss either and there is nothing for the canvas to attach the affordance to.
+- **fix**:
+  1. Confirm the wrapper renders both the class and a `data-cslp` pointing at the block field (for example `<page_ct>.<entry_uid>.<locale>.components`), and that it is rendered conditionally when the array is empty.
+  2. Confirm the wrapper is visible and has height. A zero-height container gives nothing to hover.
+  3. For nested blocks, put the same class and `data-cslp` on the inner block container, not only at page level.
+  4. This is specifically about a **block or multiple field with zero items**, where the SDK draws the affordance for you. A scalar field that renders nothing when empty is a different problem — see `empty-fields-are-not-clickable-on-the-canvas`.
+- **verification**: Open a page whose block field is empty. The "+ Add Component" placeholder appears on hover, and adding a block inserts it into both the canvas and the form.
+
+---
+
+### graphql-connection-wrappers-break-cslp
+- **bucket**: visual-editor
+- **symptom**: With GraphQL, edit tags are generated but Visual Editor cannot resolve them. The `data-cslp` values contain connection plumbing — for example `...edges.0.node.hero.heading` — and clicking a tagged element does nothing, or edit buttons on referenced fields are inert. The same integration over REST works.
+- **frameworks**: Next.js, React, any GraphQL client
+- **rendering_modes**: any
+- **root_cause**: `addEditableTags()` walks the response object and bakes every traversed layer into the `data-cslp` path. A GraphQL response nests values under `Connection -> edges -> node`, so those wrapper layers end up in the path and no field path resolves against the entry. This is by design — the SDK has no knowledge of GraphQL response shapes — so it needs a normalizer on the application side.
+- **fix**:
+  1. Request `system { uid, content_type_uid }` on every node the page renders, including referenced entries. Without those the tags cannot be attributed to an entry at all.
+  2. Flatten the response before tagging: collapse each `Connection -> edges -> node` into the plain object or array the REST shape would have produced, so a reference is an array of entries and a field is a direct property.
+  3. Call `addEditableTags()` on the flattened object, never on the raw GraphQL response.
+  4. Confirm the resulting `data-cslp` values contain no `edges` or `node` segments.
+- **verification**: Inspect a tagged element. Its `data-cslp` reads `<content_type_uid>.<entry_uid>.<locale>.<field_path>` with no connection segments, and clicking it focuses the field in the form panel.
+
+---
+
+### canvas-swallows-site-click-events
+- **bucket**: visual-editor
+- **symptom**: Interactive components stop working inside the editor canvas: carousel arrows, tab strips, accordions, dropdowns and links do nothing when clicked, while the same page works normally outside the editor. Often noticed as soon as a parent container gets a `data-cslp`.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: By design. In builder mode the SDK intercepts clicks so the canvas can capture them for editing: a click on any anchor, or on any element that is or sits inside a `data-cslp` element, gets `preventDefault()` and `stopPropagation()` before the site's own handler sees it. Anything interactive inside a tagged container is therefore inert in the canvas. This is what makes click-to-edit possible, so it cannot be switched off per element.
+- **fix**:
+  1. Recognise it as expected editor behaviour and say so. Authors are editing content, not exercising the site; interactivity is suspended in the canvas the same way it is in most visual editors.
+  2. Alt+click a link to follow it. The SDK navigates explicitly on alt+click, which is the supported way to move through the site inside the canvas.
+  3. Where a control must stay usable while editing, keep it outside any `data-cslp` container. Tag the content that is editable, not the interactive chrome around it.
+  4. Do not try to re-enable the site's handlers by stopping the SDK's interception. That breaks click-to-edit for every field under that element.
+- **verification**: The same control works on the public site and via alt+click in the canvas; tagged content around it still opens the field on click.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md b/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
new file mode 100644
index 0000000..555a2e5
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -0,0 +1,172 @@
+# Init placement by framework
+
+The SDK has no framework adapters. Framework choice decides exactly two things: where `init()` is
+allowed to run, and whether the framework's hydration preserves the edit-tag attributes you spread
+into the markup. Everything else follows from the rendering mode, covered in `rendering-modes.md`.
+
+`init()` touches `window`. It must run in the browser, once, before the first content render that
+needs to be previewable.
+
+## Next.js, App Router
+
+The most common setup mistake in this framework, and the one that produces "the SDK is installed
+and nothing happens" with no error anywhere.
+
+`init()` cannot run in a server component. Put it in a client component and import that into the
+layout so it runs once per app load:
+
+```tsx
+"use client";
+
+import { useEffect } from "react";
+import ContentstackLivePreview from "@contentstack/live-preview-utils";
+
+export function LivePreviewInit() {
+  useEffect(() => {
+    ContentstackLivePreview.init({
+      ssr: false,
+      mode: "builder",
+      stackSdk: stack.config,
+      stackDetails: { apiKey: API_KEY, environment: ENVIRONMENT },
+    });
+  }, []);
+
+  return null;
+}
+```
+
+Watch for three things here:
+
+- Soft navigation does not re-run server-side gating, and the SDK's module-level state persists
+  across route changes. Gate the edit button on something that is re-evaluated client-side, or it
+  will appear on production pages after a client-side navigation.
+- App Router metadata is produced by `generateMetadata()`, which has no hook for injecting window
+  globals. If you are using the `window.__CS_PAGE_CONTEXT__` route for page context, set it from a
+  client component, or use the `<meta>` tag form instead. Page context is only honoured when
+  **Custom Preview URLs** is configured and enabled on the plan; without that it is silently ignored.
+- Reading `searchParams` opts the route out of static rendering. Expect that when you add the SSR
+  hash path.
+
+For SSR, build the Stack instance inside the request rather than at module scope. See
+`rendering-modes.md`.
+
+## Next.js, Pages Router
+
+Works, in both of its data-fetching modes. Which contract applies depends on the method the route
+uses, not on the router:
+
+- **`getServerSideProps`** is SSR. Apply the SSR contract from `rendering-modes.md`: build the Stack
+  inside the function so it is per request, read the hash from `context.query.live_preview`, apply it
+  with `livePreviewQuery()`, and initialise with `ssr: true`.
+- **`getStaticProps`** is SSG. The page is prerendered and never sees the query string, so run
+  Live Preview in CSR mode: `ssr: false`, `stackSdk` passed, content refetched in `onEntryChange`.
+  No rebuild is needed for preview.
+
+Initialise once in `_app`, guarded to the client, since `init()` touches `window`.
+
+There is no page dedicated to the Pages Router in the Contentstack docs. Use the general pages for
+the mode in play — Set Up Live Preview with REST for SSR for `getServerSideProps`, and the SSG page
+for `getStaticProps` — and the same contracts hold. Contentstack's own Live Preview sanity fixture
+runs on the Pages Router.
+
+## React SPA with Vite
+
+The simplest case and the reference implementation. Init at the app entry point, before the first
+render:
+
+```ts
+ContentstackLivePreview.init({
+  ssr: false,
+  mode: "builder",
+  stackSdk: stack.config,
+  stackDetails: { apiKey: API_KEY, environment: ENVIRONMENT },
+});
+```
+
+`stackSdk` is mandatory in CSR mode. Omitting it also flips the automatic `ssr` default to `true`,
+which is a silent misconfiguration rather than an error.
+
+Refresh content through `onEntryChange`. If edits only appear after a manual reload, the callback
+was never registered, or it closed over a pathname captured at mount and is refetching the previous
+route.
+
+## Nuxt
+
+Init in a client-only plugin. For page context, `useHead()` is the natural place to emit the
+`<meta>` tags, since Nuxt produces head tags natively and has no built-in hook for injecting window
+globals. As everywhere, page context only takes effect with **Custom Preview URLs** configured and
+enabled on the plan.
+
+The Nuxt CSR and SSR stories differ on whether Visual Editor overlays appear, and Contentstack's
+own material is inconsistent on this point. Verify against the actual app before promising overlay
+support.
+
+## Angular
+
+Init in `APP_INITIALIZER` or the root component. By contract this is the same as the React SPA
+case: CSR, `stackSdk` mandatory, `onEntryChange` for refresh. Only the placement idiom differs.
+
+Angular Universal (SSR) is not covered by documentation. Apply the SSR contract from
+`rendering-modes.md` and verify.
+
+## SvelteKit and Astro
+
+Both are SSR with a Node adapter in their documented form, so the SSR contract applies unchanged:
+hash from the request, fresh Stack instance per request, full reload on update.
+
+Astro on some hosting platforms has an environment-variable parsing trap where the enable flag does
+not arrive as a boolean in the deployed build. If init appears not to run there, check the parsed
+value before checking anything else.
+
+Neither has support history. Do not present either as proven.
+
+## Gatsby
+
+Gatsby uses its own path via `ContentstackGatsby`, which previews without a rebuild. It needs
+`__typename` and `uid` in the GraphQL query, plus `addContentTypeUidFromTypename`.
+
+Two cautions. The published Gatsby starter is pinned to a Live Preview Utils v1.x release that
+predates Visual Editor, so it is not a valid Visual Editor reference. And whether Visual Editor
+works on a Gatsby static architecture is an open question internally, not a settled yes. Scope
+Gatsby answers to Live Preview unless the user has verified Visual Editor themselves.
+
+Note that `getGatsbyDataFormat` still appears in the SDK's README and configuration docs but has no
+implementation in the current source. It was removed in v3. Do not recommend it.
+
+## No SDK, or a non-JavaScript backend
+
+A first-class population, not a fallback. This shape covers every BFF, middleware, proxy, and
+non-JavaScript server.
+
+There is no `init()` to place on the server. The whole server-side integration is the fetch branch
+from contract 3 in the parent skill: read the hash from the request, switch host, add the
+`live_preview` and `preview_token` headers, and bypass cache for that request. If the application
+proxies Contentstack through its own backend, the hash has to be forwarded end to end, from the
+browser through the backend and into the outbound header. The JavaScript Live Preview Utils SDK is
+still required in the rendered page, whatever the backend is — it is what talks to the editor.
+
+### .NET
+
+The best-covered non-JavaScript stack. Verified against the SDK sources, not inferred:
+
+- **Live Preview** is documented for both SSR and CSR in
+  [Get Started with .Net SDK and Live Preview](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/dot-net/get-started-with-dot-net-sdk-and-live-preview).
+  The hash is applied with `await contentstackClient.LivePreviewQueryAsync(dict)`, where `dict`
+  carries the request's query parameters. The same per-request-instance rule as every SSR stack
+  applies. Timeline is supported by the same SDK.
+- **Edit tags, and therefore Visual Editor,** are supported through the `Contentstack.Utils` package:
+  `Contentstack.Utils.addEditableTags(entry, contentTypeUid, tagsAsObject, locale, options)`, with an
+  `addTags` alias and an `AddEditableTagsOptions.UseLowerCaseLocale` flag. It is written for parity
+  with the JavaScript `addEditableTags` and emits the same `data-cslp` and `data-cslp-parent-field`
+  attributes, so everything in the edit-tag entries applies unchanged.
+- **Two gaps to be honest about.** The .NET Live Preview docs page does not mention edit tags or
+  Visual Editor at all, and none of the public .NET example apps (Blazor starter, Razor Pages,
+  GraphQL) wire up Live Preview. So a user setting up Visual Editor on .NET is working from the
+  utils SDK rather than from a walkthrough. Point them at `Contentstack.Utils` and the edit-tag
+  entries, and do not promise a reference app.
+
+### Other server SDKs
+
+Java, PHP, Python and Ruby have Live Preview get-started pages in the same SSR shape. Whether their
+utils packages implement edit tags has not been verified here — check the package before promising
+Visual Editor on those stacks, and say so if it is absent.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
new file mode 100644
index 0000000..89566f9
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -0,0 +1,110 @@
+# The Onboarding Check
+
+Every visual experience product ships a setup check that runs automatically when the preview panel
+opens and reports its result in a small floating status card. It is the highest-yield thing to ask
+about, because it has already run the diagnosis the user is asking you to do.
+
+**Always ask for a screenshot of this card before asking anything else.** The step name on it
+localises the problem to one gate, and because of how the check is structured, it also tells you
+everything that already passed.
+
+## The property that makes it powerful
+
+The gates are evaluated as a single ordered chain, and it stops at the first failure. Only one
+step is ever shown.
+
+So a card reading "Preview Service Not Enabled" is not just one fact. It proves the website loaded
+in the frame, the SDK initialised, and the SDK version is supported. Three contracts are already
+ruled out. Do not re-ask about them.
+
+The inverse also holds. A card stuck on the first gate tells you nothing about any later gate,
+because none of them ran. Do not theorise about the SDK when the site never loaded.
+
+## Live Preview and Visual Editor
+
+Five gates, in this order.
+
+| # | Card while checking | Card on failure | What the failure means |
+|---|---|---|---|
+| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, HTTP or an untrusted certificate, or the browser blocking localhost. Nothing after this ran. |
+| 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | The frame loaded but no init handshake arrived. `init()` is in server-only code, the enable flag did not parse as a boolean in the deployed build, the init module was tree-shaken out, or init runs after the check window. |
+| 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake arrived from a version below the supported minimum. Upgrade Live Preview Utils. |
+| 4 | Verifying Preview Service | **Preview Service Not Enabled** | The SDK is fine and the site is fine, but content is not coming from the Preview Service. This is the fetch layer never switching host and headers, which is the most common failure of all. |
+| 5 | — | **Default Environment Not Set** | Everything works. Setup is recorded as complete. The stack simply has no default preview environment, set in stack settings. |
+| — | — | **Setup Complete** | All gates passed. |
+
+The exact body text is worth quoting back to users, because they often paraphrase it into
+something ambiguous. Gate 1 reads "Ensure the website is live and accessible via Contentstack
+origins." Gate 4 reads "Please enable the Preview Service for a seamless live preview experience."
+
+## Timeline
+
+Timeline runs its own check with three gates, not the five above. Do not map one onto the other.
+
+| # | Card | On failure | Meaning |
+|---|---|---|---|
+| 1 | Default Environment | Set default environment | No default environment configured |
+| 2 | Live Preview SDK | Use updated SDK | SDK version below the supported minimum |
+| 3 | Preview Token | Use preview token | Requests are not using the Preview Service |
+
+**Timeline's check has a fixed delay before it declares failure.** A site slower than that window
+produces a failure card even though the setup is correct. If a Timeline user reports a failing gate
+on a site you know is slow, have them re-open the panel on a warm cache before believing the card.
+
+## What the check does not cover
+
+This is where the check earns its keep as a diagnostic, and where people over-trust it. "Setup
+Complete" and a broken experience is a real and informative combination.
+
+The check verifies reachability, the SDK handshake, SDK version, and that the Preview Service is in
+use. It does not look at any of the following:
+
+- **Edit tags.** Nothing in the chain inspects `data-cslp`. If the card says Setup Complete and
+  nothing on the canvas is editable, the answer is edit-tag generation, every time. This is the
+  single most useful inference the check supports.
+- **Preview URL resolution.** The site loading is not the same as the correct entry loading. A card
+  reading Setup Complete on the wrong page is a routing problem.
+- **Locale, variants, and Timeline timestamps.**
+- **Caching.** Any cache on the preview path can serve published content while every gate passes.
+- **Roles.** The check runs as the signed-in user but does not report permission gaps, which is why
+  a role problem looks like "works for everyone except one person" rather than a failed gate.
+
+## When the card does not appear at all
+
+Absence is not a pass. Before treating a missing card as "the check succeeded", rule out:
+
+- No default environment is set and none is remembered locally for that locale, in which case the
+  overlay is deliberately not shown.
+- The user, or someone on their team, dismissed it. The preference persists per stack.
+- The stack setting suppresses it.
+
+**Do not reason about the default.** Each product keeps its own stack setting, and they disagree on
+what an unset value means:
+
+| Product | Setting | Unset resolves to |
+|---|---|---|
+| Timeline | `timeline.onboarding-setup-visible` | visible |
+| Live Preview | `live_preview.lp-onboarding-setup-visible` | hidden |
+| Visual Editor | `visual_builder.onboarding-setup-visible` | depends on whether the settings object exists |
+
+The Visual Experience settings screen renders every one of these as **on** when unset, so a stack
+that never explicitly saved the setting can show the toggle on while the card never appears.
+
+The fix is one action: open Settings → Visual Experience and Save, without changing anything. That
+form submits all three products' keys together and an unset value arrives as on, so one save writes
+an explicit value for all three and they stop disagreeing.
+
+If it then appears for colleagues but not for the reporter, they dismissed it. That suppression
+lives per stack in their own browser storage and no stack-level save clears it.
+
+If the user cannot produce the card, fall back to the four contracts in SKILL.md and verify them by
+hand.
+
+## How to ask for it
+
+Ask for the screenshot rather than the wording. Users paraphrase the step name into a different
+one, and since each name maps to a specific gate, a paraphrase can send you down the wrong branch.
+
+If they cannot screenshot it, ask for the exact step name and body text as displayed, and confirm
+which product they are in, because Live Preview and Timeline share a visual style but not a set of
+gates.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
new file mode 100644
index 0000000..2bcb6ff
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -0,0 +1,93 @@
+# Preflight checklist
+
+Run in order. Each step either passes or localises the problem to one contract. Stop at the first
+failure and fix it before continuing, because a failure upstream makes every downstream check
+meaningless.
+
+## Before touching the application
+
+1. **Get the Onboarding Check to appear.** It walks the contracts in order and names the first one
+   that fails. Do not assume its default state: each product stores its own setting under
+   Settings → Visual Experience, and an unset value resolves differently per product, so the toggle
+   can read on while the card never appears. Save the setting explicitly for the product in use.
+2. **Live Preview is enabled on the stack**, with a default preview environment set.
+3. **A Preview Token exists**, generated against the Delivery Token the application already uses.
+   A management token is not a substitute and must never reach client-side configuration.
+4. **The environment has a Base URL**, and one for each locale being previewed. A missing Base URL
+   presents as a greyed-out environment selector or "No environments available".
+5. **The signed-in user's role can read everything the page uses.** Preview runs as that user and
+   applies their full ACL — content types, entries, fields, locales, assets — so anything they
+   cannot read comes back empty. Delivery uses a delivery token and applies none. Expect preview
+   to differ per user, and make the site render missing data gracefully.
+
+## Reachability
+
+6. **The preview host is served over HTTPS** with a trusted certificate.
+7. **`curl -I https://<preview-host>/<a-deep-route>`** returns no `X-Frame-Options`, and a CSP
+   `frame-ancestors` that includes the Contentstack app origin. Test a deep route, not the site
+   root, and confirm it holds after any redirect.
+8. **Nothing sits in front of the site that cannot render in a frame**: platform password
+   protection, an SSO screen setting `X-Frame-Options: DENY`, or basic auth.
+9. **If previewing `http://localhost`**, confirm the browser is not blocking it. Chrome's Local
+    Network Access policy blocks the app origin from framing localhost and only the user can grant
+    the permission.
+
+## Versions
+
+10. **Live Preview Utils v3.0+ and Delivery SDK v3.20.3+** for Visual Editor. **v4.4.4+** if using
+    `setPageContext()`.
+11. **Exactly one copy of the preview SDK is loaded.** An npm install plus an ESM or CDN
+    `<script type="module">` import of a different version produces behaviour differences that look
+    like configuration bugs.
+
+## Contract 1: init runs
+
+12. **A `POST /live-preview/tracker` returns 2xx** when the preview panel loads. If it never fires,
+    init did not run.
+13. **`init()` runs on the client**, not in server-only code.
+14. **The enable flag parses as a boolean in the deployed build.** A string `"false"` is truthy.
+15. **`ssr` is set explicitly.** The automatic default keys off `stackSdk` and gets it wrong in both
+    directions: a CSR app without `stackSdk` silently becomes SSR, and an SSG site with `ssr: true`
+    produces blank screens rather than an error.
+16. **`stackDetails: { apiKey, environment }` is passed explicitly.** Since v2 the SDK no longer
+    derives the API key from the Stack object for edit tags.
+
+## Contract 2: edit tags reach the DOM
+
+17. **A rendered field carries `data-cslp`**, formed as
+    `<content_type_uid>.<entry_uid>.<locale>.<field_path>`.
+18. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called on every fetched entry,
+    including referenced entries. The third argument must be `true` for React and JSX.
+19. **The `$` attributes are spread onto the leaf element** that renders the value, one `data-cslp`
+    per element. Tagging a wrapper selects the wrong field.
+20. **Reference paths mirror the data shape.** References come back as arrays:
+    `post.author[0].$?.name`, not `post.$?.author.name`.
+21. **For GraphQL**, connection wrappers are flattened and `system { uid, content_type_uid }` is
+    requested on every node, before `addEditableTags()` runs.
+
+## Contract 3: the hash reaches the fetch
+
+22. **Content requests hit a `*-preview.contentstack.com` host** during an active preview session.
+    Seeing `cdn.contentstack.io` or `graphql.contentstack.com` here is the single most common setup
+    failure, whatever the reported symptom was.
+23. **Those requests carry `live_preview` and `preview_token` headers** and return 200.
+24. **Every fetch path uses the initialized Stack instance.** A second instance, a hand-rolled
+    wrapper, or a BFF that bypasses it will keep serving published content.
+25. **The hash is never hardcoded or invented.** An unrecognised hash returns
+    `error_code 382, Please create tracker before starting live preview session`.
+26. **If the app proxies Contentstack through its own backend**, the hash is forwarded end to end.
+27. **SSR only: the Stack instance is built per request.** A module-level instance leaks one
+    editor's draft into other users' responses, including public traffic.
+28. **Caching is bypassed for preview requests.** Any cache on the preview path serves published
+    content after the host switch is already correct, and can serve preview output to real visitors.
+
+## Behaviour
+
+29. **Edit a field without saving.** The preview updates.
+30. **Hover a tagged element in Visual Editor.** It highlights, and clicking focuses the matching
+    field in the form panel.
+31. **Open entries from several content types**, including a nested route and one with no `url`
+    field. Each loads its own page.
+32. **Navigate inside the preview pane.** Preview context survives the navigation.
+33. **Load the public site in a normal browser tab.** No edit button, no `#cslp-tooltip` in the DOM,
+    and no preview response served from cache.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
new file mode 100644
index 0000000..a5c552f
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -0,0 +1,126 @@
+# Rendering modes
+
+The Live Preview SDK ships no framework adapters. It declares no framework peer dependencies and
+contains no per-framework code paths. What determines the correct integration is the rendering
+mode of the affected route and the fetch layer underneath it, not the framework's name.
+
+Diagnose against this file. Use `frameworks.md` only for where `init()` is allowed to run.
+
+## The contract per mode
+
+| Mode | `ssr` | How the hash travels | How updates arrive | Hard requirement |
+|---|---|---|---|---|
+| CSR + REST | `false` | postMessage; the SDK injects it into `stackSdk` | `onEntryChange` / `onLiveEdit` refetch, no reload | `stackSdk` is mandatory |
+| SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload | a fresh Delivery SDK instance per request |
+| CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch | manual host swap plus headers |
+| SSR + GraphQL | `true` | `request.query.live_preview` | full iframe reload | manual host swap plus headers |
+| SSG | `false` | postMessage | runs in CSR mode at runtime | `stackSdk`, and `init()` must be browser-only |
+
+## How `ssr` is resolved
+
+Precedence is `stackSdk.live_preview.ssr`, then `init({ ssr })`, then the automatic default.
+
+The automatic default keys off `stackSdk`: present means `ssr: false`, absent means `ssr: true`.
+This is the trap behind several setup failures. A CSR app that omits `stackSdk` silently gets SSR
+behaviour, and an SSG site initialized with `ssr: true` produces blank and black screens rather
+than a clean error.
+
+Set it explicitly. Do not rely on the default.
+
+## Mode-specific failures worth knowing before you prescribe
+
+### SSR: the shared instance
+
+A module-level Stack instance is shared across requests. Applying a preview hash to it mutates
+shared state, so one editor's draft leaks into other users' responses. This reaches public traffic,
+not just the authoring session, and it presents as intermittent wrong content plus tracker-invalid
+and branch-mismatch errors on the production site.
+
+Build the Stack instance inside the request handler. This is the most damaging SSR mistake there is,
+and the least obvious, because it works perfectly with one user.
+
+### SSG: supported, in CSR mode
+
+SSG is documented and supported. Do not tell users it is a dead end.
+
+The confusion comes from the hash. In SSR mode the hash travels as the `live_preview` query
+parameter, and a prerendered page never sees a query parameter, so the fetch is never switched.
+The documented answer is not to fight that, it is to run the preview path in **CSR mode**, where
+the hash arrives by postMessage instead and never needs the URL.
+
+Per [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-static-site-generator-ssg):
+
+- Initialise Live Preview Utils with `ssr: false`
+- Pass `stackSdk`, which is mandatory in CSR mode
+- Configure the Delivery SDK with
+  `live_preview: { preview_token, enable: true, host: "rest-preview.contentstack.com" }`
+- Refresh through `onLiveEdit()`, so the browser refetches on each edit
+
+So an SSG site previews without a rebuild. The static build serves the shell, and the preview
+content is fetched client-side during the session.
+
+The common failure here is not SSG itself, it is an SSG site initialised with `ssr: true`. That
+produces blank and black screens rather than a clean error.
+
+### ISR: the genuinely hard case
+
+ISR is where there is no clean answer, and it should not be lumped in with SSG.
+
+Contentstack's recorded position more broadly is that caching has to be off for Live Preview and
+Visual Editor routes, and that integrating with a framework's own cache-invalidation feature is
+out of scope. Do not send users toward a framework's draft mode expecting Contentstack to meet it
+there.
+
+In Next.js specifically, reading `searchParams` opts a route out of static rendering. Where a team
+insists on a hybrid, the workable pattern is detecting `live_preview` and forcing that request
+dynamic. No official hybrid recipe is published, so treat anything beyond this as unverified.
+
+### Caching at the edge
+
+Any cache on the preview path keeps serving published content after the host
+switch is already correct. This produces "works on localhost, fails on the deployed environment",
+which users reliably misread as a Contentstack outage.
+
+The same misconfiguration has the inverse failure, which is worse: preview output reaching real
+visitors. That is usually the shared-instance problem above rather than the cache itself, with the
+cache widening the blast radius. Treat preview output on a public URL as urgent, and fix the
+per-request instance first.
+
+### GraphQL: edit tags do not survive connection wrappers
+
+`addEditableTags()` bakes each traversed layer into the `data-cslp` path, and a GraphQL response
+nests values under `Connection -> edges -> node`, so those wrapper layers end up in the path and no
+tag resolves. This is by design and needs a response normalizer on the application side. The full
+fix is `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md`.
+
+### App Router soft navigation
+
+SDK module-level singletons persist across client-side route changes, and soft navigation does not
+re-run server-side gating. This is the recorded cause of the edit button appearing on production
+pages after a client-side navigation, on setups where the server-rendered entry point gates it
+correctly.
+
+## Framework and mode coverage
+
+Support here means documented and exercised, not merely possible.
+
+| Framework | CSR | SSR | SSG / ISR | Edge |
+|---|---|---|---|---|
+| Next.js App Router | documented, Visual Editor supported | documented, Visual Editor supported; fragile for empty-block affordances | runs as CSR at runtime; `searchParams` conflicts with fully static routes | no coverage |
+| Next.js Pages Router | supported | supported via `getServerSideProps` | supported via `getStaticProps`, runs in CSR mode | no coverage |
+| React SPA (Vite) | reference implementation | not applicable | not applicable | not applicable |
+| Nuxt | documented | documented | not applicable | no coverage |
+| Angular | documented | Universal not covered | not applicable | no coverage |
+| SvelteKit | not covered | documented | not covered | no coverage |
+| Astro | not covered | documented, Node adapter | static mode untested | environment-variable parsing trap on some hosts |
+| Gatsby | supported without a rebuild | not applicable | the intended mode | not applicable |
+| .NET | documented | documented; Visual Editor via `Contentstack.Utils` edit tags | not covered | no coverage |
+| Other server SDKs (Java, PHP, Python, Ruby) | not covered | Live Preview documented; edit-tag support unverified | not covered | no coverage |
+
+Two honest gaps in this table:
+
+- **Edge runtimes have no coverage anywhere.** Not in the documentation, the SDK source, or the
+  issue tracker. This is absence of evidence rather than a known incompatibility. If a user is on
+  an edge runtime, say that it is untested rather than guessing.
+- **Frameworks with a starter but no support history** cannot be distinguished between "works
+  cleanly" and "nobody uses it". Both produce zero tickets. Do not present them as proven.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
new file mode 100644
index 0000000..60475ab
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -0,0 +1,71 @@
+# Setup: the documentation is the source of truth
+
+For setup, follow the official Contentstack documentation. Do not reconstruct setup steps from
+memory and do not invent a procedure. Identify the framework and rendering mode, open the matching
+page, and follow it.
+
+The rest of this skill exists for when the documented setup has been followed and something still
+does not work. That is a different job, and it is where the mined failure catalogue earns its keep.
+
+## Pick the page
+
+Establish framework and rendering mode first, then route.
+
+### Start here regardless
+
+- [Set Up Live Preview for your Website](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-your-website) — the setup hub
+- [How Live Preview Works](https://www.contentstack.com/docs/developers/set-up-live-preview/how-live-preview-works) — the model to reason from
+- [How Live Preview Works with SDK](https://www.contentstack.com/docs/headless-cms/how-live-preview-works-with-sdk) — how `ssr` is resolved and how the hash travels
+
+### By framework and mode
+
+| Framework and mode | Page |
+|---|---|
+| Next.js App Router, CSR | [Live Preview Implementation for Next.js CSR App Router](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-nextjs-csr-app-router) |
+| Next.js App Router, SSR | [Live Preview Implementation for Next.js SSR App Router](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-nextjs-ssr-app-router) |
+| React, CSR | [Live Preview Implementation for ReactJS CSR Website](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-reactjs-csr-website) |
+| Any framework, SSG | [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-static-site-generator-ssg) — runs in CSR mode, `ssr: false` |
+| Any framework, SSR over REST | [Set Up Live Preview with REST for Server-Side Rendering](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-with-rest-for-server-side-rendering) |
+
+### Visual Editor, on top of a working Live Preview
+
+Visual Editor is not a separate integration. It is Live Preview plus edit tags, so Live Preview
+must work first.
+
+- [Set Up Visual Builder for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-builder/set-up-visual-builder-for-your-website)
+- [Set Up Visual Editor for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-editor/set-up-visual-editor-for-your-website)
+- [Set Up Live Edit Tags for Entries with REST](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-edit-tags-for-entries-with-rest) — the `addEditableTags()` reference
+
+### Starters
+
+[Kickstart Next.js](https://www.contentstack.com/docs/developers/kickstarts/next) and its siblings
+are working references. When a user's setup disagrees with a kickstart, the kickstart is right.
+
+## What the documentation will not settle
+
+These come up constantly and are not answered by any setup page. Say so plainly rather than
+guessing, and reach for `rendering-modes.md` and `faq-setup.md`.
+
+- **Next.js Pages Router.** Supported, but has no dedicated page. Use the SSR-over-REST page for
+  `getServerSideProps` and the SSG page for `getStaticProps`; the contracts are identical.
+- **ISR and framework cache or draft modes.** SSG *is* documented (see the table above). ISR is
+  not. Caching must be off for preview routes, and integrating with a framework's own
+  cache-invalidation or draft feature is out of scope.
+- **Edge runtimes.** No coverage anywhere. Untested rather than unsupported. Say that.
+- **GraphQL with edit tags.** Connection wrappers break `data-cslp` paths and need a
+  customer-side response normalizer. By design; see `graphql-connection-wrappers-break-cslp` in
+  `faq-visual-editor.md`.
+- **Frameworks with a starter but no support history.** A starter existing is not evidence the
+  combination is proven.
+
+## Two things worth stating before a user starts
+
+**Version minimums.** Live Preview Utils v3.0+ and Delivery SDK v3.20.3+ for Visual Editor, and
+Live Preview Utils v4.4.4+ for `setPageContext()`. Load exactly one copy of the preview SDK; mixing
+an npm install with an ESM or CDN import of a different version produces behaviour that looks like
+a configuration bug.
+
+**`addEditableTags()` mutates and returns nothing.** It updates the entry passed as its first
+argument in place. Assigning its result gives you `undefined`, which is a common first-timer
+mistake. For React and JSX, `tagsAsObject` must be `true`; it defaults to `false`, which produces a
+string that React cannot spread.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md b/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
new file mode 100644
index 0000000..29eb687
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
@@ -0,0 +1,69 @@
+# Symptom index
+
+Find the reported symptom, go to the entry. Symptoms are worded the way users report them, not the
+way the underlying cause would be described.
+
+Setup entries come first because an unmet setup contract produces a large share of what gets
+reported as behavioural. If the integration has never fully worked, work the four contracts in
+SKILL.md before reading anything below.
+
+
+## Setup and first integration
+
+| Symptom | Entry |
+|---|---|
+| Live Preview / Visual Editor loads the site fine, but edits made in the entry form or the right-hand panel nev… | [app-fetches-from-delivery-cdn-instead-of-preview-service](faq-setup.md#app-fetches-from-delivery-cdn-instead-of-preview-service) |
+| The Live Preview / Visual Editor pane is blank or shows "`<your-host>` refused to connect" | [iframe-blocked-by-x-frame-options-or-csp-frame-ancestors](faq-setup.md#iframe-blocked-by-x-frame-options-or-csp-frame-ancestors) |
+| Preview API requests fail with `{"error_message":"Please create tracker before starting live preview session",… | [error-382-create-tracker-before-starting-live-preview-session](faq-setup.md#error-382-create-tracker-before-starting-live-preview-session) |
+| Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar | [edit-tags-not-generated-or-not-spread](faq-setup.md#edit-tags-not-generated-or-not-spread) |
+| Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited | [preview-url-does-not-resolve-to-the-app-route](faq-setup.md#preview-url-does-not-resolve-to-the-app-route) |
+| Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump break… | [sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade](faq-setup.md#sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade) |
+| The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wr… | [environment-base-url-misconfigured-or-missing-for-a-locale](faq-setup.md#environment-base-url-misconfigured-or-missing-for-a-locale) |
+| The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or t… | [edit-button-rendered-outside-a-live-preview-session](faq-setup.md#edit-button-rendered-outside-a-live-preview-session) |
+| `Access to fetch at 'https://<region>-rest-preview.contentstack.com/v3/...' from origin '<site origin>' has be… | [cors-blocked-on-preview-api-requests](faq-setup.md#cors-blocked-on-preview-api-requests) |
+| Two opposite failures from the same mistake | [ssr-stack-instance-shared-or-duplicated](faq-setup.md#ssr-stack-instance-shared-or-duplicated) |
+| In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit… | [nextjs-app-router-init-must-run-in-a-client-component](faq-setup.md#nextjs-app-router-init-must-run-in-a-client-component) |
+| "Preview Service Not Enabled" shows in the preview panel on a setup that otherwise works | [legacy-management-token-setup-not-migrated-to-preview-token](faq-setup.md#legacy-management-token-setup-not-migrated-to-preview-token) |
+| Preview opens for pages that already exist on the main branch but never shows updates, and any page that exist… | [branch-or-alias-mismatch-between-app-token-and-entry](faq-setup.md#branch-or-alias-mismatch-between-app-token-and-entry) |
+| Live Preview never activates or the preview panel reports the service is not enabled, even though the stack se… | [wrong-region-hosts-in-sdk-and-preview-config](faq-setup.md#wrong-region-hosts-in-sdk-and-preview-config) |
+| Start Editing / the Edit button opens Visual Editor or the entry editor with `locale=en-us` even though the st… | [locale-defaults-to-en-us-in-init](faq-setup.md#locale-defaults-to-en-us-in-init) |
+| The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `… | [start-editing-button-cannot-be-hidden-in-editor-mode](faq-setup.md#start-editing-button-cannot-be-hidden-in-editor-mode) |
+| A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days… | [onboarding-check-card-not-visible-or-appears-unexpectedly](faq-setup.md#onboarding-check-card-not-visible-or-appears-unexpectedly) |
+| The "Visual Experience" / builder-mode option does not appear in the Contentstack navigation at all, so the te… | [visual-experience-navigation-missing-for-the-stack](faq-setup.md#visual-experience-navigation-missing-for-the-stack) |
+| The site renders in the preview pane but behaves as if logged out, or without personalization, locale or curre… | [third-party-cookies-blocked-inside-the-preview-iframe](faq-setup.md#third-party-cookies-blocked-inside-the-preview-iframe) |
+| A previously working local Live Preview setup breaks with `Access to fetch at 'http://localhost:5173/' from or… | [chrome-local-network-access-blocks-preview-of-localhost](faq-setup.md#chrome-local-network-access-blocks-preview-of-localhost) |
+| `data-cslp` attributes in the DOM contain `undefined` where the entry uid should be | [cslp-tags-contain-the-literal-string-undefined](faq-setup.md#cslp-tags-contain-the-literal-string-undefined) |
+| Live Preview on a statically generated site is unreliable or simply shows build-time content: blank or black s… | [ssg-preview-needs-csr-mode](faq-setup.md#ssg-preview-needs-csr-mode) |
+
+## Preview runtime
+
+| Symptom | Entry |
+|---|---|
+| Selecting a variant (or switching audience in Audience Preview) in Visual Experience keeps rendering the base… | [variant-or-audience-switch-shows-base-entry](faq-preview-runtime.md#variant-or-audience-switch-shows-base-entry) |
+| Preview works on localhost but not on a deployed environment with identical code and config — the setup status… | [cached-response-serves-stale-preview](faq-preview-runtime.md#cached-response-serves-stale-preview) |
+| A page that renders fine in the entry editor and on the live site comes back blank in Visual Experience for a… | [locale-fallback-blank-or-wrong-locale-in-preview](faq-preview-runtime.md#locale-fallback-blank-or-wrong-locale-in-preview) |
+| Edits only appear after manually reloading the preview | [csr-edits-need-manual-refresh](faq-preview-runtime.md#csr-edits-need-manual-refresh) |
+| Preview works on the entry's own URL, but navigating within the site inside the preview panel breaks it — "Pag… | [spa-client-navigation-loses-preview-context](faq-preview-runtime.md#spa-client-navigation-loses-preview-context) |
+| `ContentstackLivePreview.hash` logs as an empty string, so the code that gates on it never switches to the pre… | [hash-empty-outside-the-preview-iframe](faq-preview-runtime.md#hash-empty-outside-the-preview-iframe) |
+| The very first `onEntryChange` fetch after opening the preview returns published data even though the entry wa… | [stale-first-fetch-when-editing-a-referenced-entry](faq-preview-runtime.md#stale-first-fetch-when-editing-a-referenced-entry) |
+| Live Preview works for top-level fields but an edit to an entry that is referenced inside another entry does n… | [legacy-management-token-preview-breaks-on-references](faq-preview-runtime.md#legacy-management-token-preview-breaks-on-references) |
+| One user sees an empty or partly empty page in Live Preview / Visual Editor while colleagues on the same stack… | [preview-renders-empty-for-a-restricted-user](faq-preview-runtime.md#preview-renders-empty-for-a-restricted-user) |
+| Ad slots, consent widgets, or other host-dependent third-party scripts intermittently fail to render inside Li… | [third-party-scripts-misbehave-inside-the-preview-iframe](faq-preview-runtime.md#third-party-scripts-misbehave-inside-the-preview-iframe) |
+
+## Visual Editor
+
+| Symptom | Entry |
+|---|---|
+| Edit tags on fields that come from a referenced entry do nothing when clicked | [cslp-not-rebased-to-referenced-entry](faq-visual-editor.md#cslp-not-rebased-to-referenced-entry) |
+| Visual Editor will not initialize for any non-fallback locale on an older stack, while Live Preview works | [locale-case-mismatch-lowercased-cslp](faq-visual-editor.md#locale-case-mismatch-lowercased-cslp) |
+| An empty rich text field renders with zero height in preview mode, so there is nothing to click and the author… | [empty-fields-are-not-clickable-on-the-canvas](faq-visual-editor.md#empty-fields-are-not-clickable-on-the-canvas) |
+| A page or component with an empty modular-block / multiple field shows no "+ Add Component" affordance, so aut… | [empty-block-add-button-not-appearing-or-failing](faq-visual-editor.md#empty-block-add-button-not-appearing-or-failing) |
+| With GraphQL, edit tags are generated but Visual Editor cannot resolve them | [graphql-connection-wrappers-break-cslp](faq-visual-editor.md#graphql-connection-wrappers-break-cslp) |
+| Interactive components stop working inside the editor canvas: carousel arrows, tab strips, accordions, dropdow… | [canvas-swallows-site-click-events](faq-visual-editor.md#canvas-swallows-site-click-events) |
+
+## Timeline
+
+| Symptom | Entry |
+|---|---|
+| Timeline preview shows the wrong point in time — either the current version regardless of the date picked, or… | [timeline-preview-timestamp-ignored-or-dropped](faq-timeline.md#timeline-preview-timestamp-ignored-or-dropped) |
+| Timeline Compare Website renders both versions but highlights no differences between them. | [timeline-compare-highlights-no-differences](faq-timeline.md#timeline-compare-highlights-no-differences) |
diff --git a/cursor/rules/00-router.mdc b/cursor/rules/00-router.mdc
index bffe8f7..648307d 100644
--- a/cursor/rules/00-router.mdc
+++ b/cursor/rules/00-router.mdc
@@ -13,8 +13,8 @@ Use the table below to route a user request to the right skill. Each row maps a
 | Use when users want to migrate, move, switch, port, or re-platform from Contentful to Contentstack, including content models, content, assets, locales, application integrations, website code, migration prerequisites, migration progress checks, or post-migration validation. | [contentstack-migration-companion](../../skills/migration-companion/SKILL.md) |
 | Use when a user wants to migrate Contentstack Delivery SDK code from JavaScript to TypeScript. | [dx-migrate-js-to-ts-sdk](../../skills/dx-migrate-js-to-ts-sdk/SKILL.md) |
 | Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, Live Preview setup, Visual Builder support, SSR preview handling, or debugging SDK query chains. | [dx-delivery-sdk](../../skills/dx-delivery-sdk/SKILL.md) |
+| Use for any Contentstack Live Preview, Visual Editor or Visual Builder question (Visual Editor and Visual Builder are the same product), whether setting it up or debugging it: first-time integration in any framework, SDK upgrades, the SDK installed but nothing happening, a blank preview pane, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, canvas or edit-tag resolution failures, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](../../skills/cms-live-preview-visual-editor-support-assistant/SKILL.md) |
 | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](../../skills/cms-data-modeling-best-practices/SKILL.md) |
-| Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not. | [Live Preview and Visual Builder Support Assistant](../../skills/cms-live-preview-visual-builder-support-assistant/SKILL.md) |
 | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](../../skills/cms-entries/SKILL.md) |
 | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](../../skills/cms-assets/SKILL.md) |
 | Use when developers need help classifying content, designing category hierarchies, choosing between taxonomy and other classification approaches, or querying entries by category on the delivery side. | [Contentstack Taxonomy](../../skills/cms-taxonomy/SKILL.md) |
diff --git a/cursor/rules/07-cms-live-preview-visual-builder-support-assistant.mdc b/cursor/rules/07-cms-live-preview-visual-builder-support-assistant.mdc
deleted file mode 100644
index d370221..0000000
--- a/cursor/rules/07-cms-live-preview-visual-builder-support-assistant.mdc
+++ /dev/null
@@ -1,269 +0,0 @@
----
-description: "Diagnose and guide Contentstack Live Preview and Visual Builder implementations. Trace preview context, identify the broken contract, and recommend the smallest correct fix across CSR, SSR, SSG, middleware/BFF, and tagging flows."
-alwaysApply: false
----
-
-
-# Live Preview and Visual Builder Support Assistant
-
-## Description
-
-Diagnose and guide Contentstack Live Preview and Visual Builder implementations. Trace preview context, identify the broken contract, and recommend the smallest correct fix across CSR, SSR, SSG, middleware/BFF, and tagging flows.
-
-## When to Use
-
-Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not.
-
-## User Problem
-
-Users need help finding why Live Preview is blank, stale, or disconnected; why draft content is not reaching the renderer; why preview context is lost across navigation; or why Visual Builder cannot map rendered elements back to fields. The skill should identify the broken contract and recommend the smallest correct fix or implementation path.
-
-## Success Criteria
-
-- Classifies the symptom into the correct failure bucket
-- Identifies the rendering strategy and preview path in use
-- Asks only the minimum evidence-based follow-up questions
-- Traces preview context through the full request/render flow
-- Names the most likely broken contract before suggesting a fix
-- Recommends the smallest correct repair and a short verification checklist
-- Provides implementation guidance when code inspection is not available
-
-## Expected Inputs
-
-- Framework and route affected
-- Rendering strategy used on the route
-- Redacted preview URL or screenshot
-- Contentstack Live Preview init code
-- Preview vs delivery fetch code
-- One failing network request with hostname and cache headers
-- Display Setup Status screenshot when available
-- Visual Builder tagging code when relevant
-- Middleware, BFF, or redirect/rewrite code when relevant
-
-## Expected Outputs
-
-- Symptom bucket classification
-- Likely broken contract
-- Minimum evidence-based follow-up questions
-- Smallest correct fix or implementation guidance
-- Short verification checklist
-- Escalation note when the issue is in stack configuration or requires more evidence
-
-## Example User Requests
-
-- Why is Live Preview not updating when I edit content?
-- How do I set up Contentstack Live Preview for SSR?
-- What is the difference between ssr: true and ssr: false?
-- My preview iframe is blank. What should I check?
-- How do preview tokens and live preview hashes work?
-
-## Workflow Summary
-
-1. Classify the symptom.
-2. Classify the rendering strategy.
-3. Request only the minimum evidence needed.
-4. Inspect the preview contract in code or provided snippets.
-5. Name the most likely broken contract.
-6. Recommend the smallest correct fix.
-7. Return a short verification checklist.
-
-## Instructions
-
-### 1. Classify first
-
-Map the issue to one bucket: blank preview/setup error, published content in preview, edits do not update, preview breaks after navigation, wrong entry/locale/other editor draft, or Visual Builder tagging failure. Do not branch until evidence forces it.
-
-### 2. Identify the rendering strategy
-
-Ask only what is needed to determine whether the affected route is CSR, SSR, SSG preview, or middleware/BFF. The ssr setting controls preview behavior, not the whole app.
-
-### 3. Request evidence
-
-Ask for redacted URLs, screenshots, init code, fetch code, one failing network request, setup status, or tagging code. Never ask for secrets, tokens, cookies, or auth headers.
-
-### 4. Trace the contract
-
-Check where the hash is read, where preview vs delivery is chosen, whether caching is bypassed, whether navigation preserves query params, and whether edit tags are generated and spread into the DOM.
-
-### 5. Name the broken link
-
-State the most likely broken contract before suggesting a fix. Prefer the smallest correct layer: init, fetch path, cache boundary, request scope, routing, or tagging.
-
-### 6. Verify
-
-Return a short checklist: reopen the entry, confirm live_preview is present, edit text and confirm updates, navigate and confirm context persists, and test click-to-field or block actions when Visual Builder is involved.
-
-## Output Format
-
-Use short, actionable bullets. Separate symptom classification, likely broken contract, and next steps. Call out when a behavior applies only to preview and not production. Prefer evidence-based conclusions over speculation. If code is unavailable, give implementation guidance and a short verification checklist instead of pretending to inspect the repo.
-
-## Tooling Notes
-
-Read-only guidance first. Use Read, Grep, and Glob when code is available. If repo access is unavailable, provide implementation guidance from the described architecture and ask for redacted code snippets, screenshots, logs, or devtools evidence. Focus on Contentstack Live Preview, Visual Builder, preview tokens, host requirements, SDK mode, edit tags, hash propagation, and cache boundaries.
-
-## Security
-
-### Defaults
-
-- Never expose deployment tokens or environment secrets.
-- Validate preview targets and host URLs before suggesting changes.
-- Never recommend enabling Live Preview in production builds.
-- Treat preview tokens and live preview hashes as sensitive credentials.
-- Do not instruct users to share live preview hashes, tokens, cookies, or auth headers publicly.
-
-### Destructive Actions
-
-Do not make changes automatically. Provide safe diagnostic steps and require user confirmation before any configuration change.
-
-### Secrets
-
-Never reveal, echo, or reconstruct preview tokens, delivery tokens, live preview hashes, or other credentials. If a secret appears in input, instruct the user to rotate it if exposed.
-
-### Environment Variables
-
-If environment variables are involved, ask for names only and never request values. Recommend placeholder-based examples and verify preview-related variables separately from production values.
-
-## Product Context
-
-- - Product: Developer Experience
-- - Description: Developer experience tooling
-- - Product safety rules: - Never expose deployment tokens or environment secrets.
-- Validate deployment targets before triggering.
-- Require confirmation for production deployments.
-- Never auto-deploy to production without review.
-
-## Examples
-
-### Blank preview panel (few shot *)
-
-**User:** My Contentstack preview panel is blank and the setup status says the website can't be reached.
-
-**Assistant:** Likely bucket: blank preview or setup status error.
-
-Check:
-- Does the preview URL open directly in a browser tab?
-- Are X-Frame-Options or frame-ancestors blocking embedding?
-- Is the Live Preview base URL correct for this environment and locale?
-- Does the previewed route call ContentstackLivePreview.init() in browser code?
-
-Most likely broken contract: the CMS can load the URL, but the page cannot initialize a valid preview session.
-
-Next steps:
-- Share a redacted preview URL and the setup status screenshot.
-- Confirm whether the route uses iframe embedding or new-tab preview.
-- Verify the SDK init runs on the actual previewed route.
-
-*Covers blank iframe/setup status failures.*
-
-### Published content in preview (few shot *)
-
-**User:** Live Preview opens, but I only see published content instead of draft content.
-
-**Assistant:** Likely bucket: published content in preview.
-
-Check:
-- Does the URL contain live_preview=...?
-- Are requests hitting the preview host, not the delivery host?
-- Is a preview token configured?
-- Does the fetch layer receive and forward the hash?
-- Is a proxy or middleware dropping the hash?
-
-Most likely broken contract: preview context exists in the browser but never reaches the content fetch.
-
-Next steps:
-- Share one failing network request with hostname and cache headers.
-- Share the code path that chooses preview vs delivery.
-- Confirm whether the page fetches directly or through a BFF/API route.
-
-*Covers missing hash or wrong API path.*
-
-### Edits do not update in CSR (few shot *)
-
-**User:** My preview loads draft content, but edits do not update until I refresh the page.
-
-**Assistant:** Likely bucket: edits do not update.
-
-For CSR, check:
-- Is ssr: false configured?
-- Is onEntryChange() or onLiveEdit() registered?
-- Does the callback refetch content?
-- Is the listener mounted once and early enough?
-- Does state get replaced atomically instead of merged?
-
-Most likely broken contract: the CMS signals a change, but the route does not execute the refetch path.
-
-Next steps:
-- Share the init code and the subscription code.
-- Confirm whether the page uses CSR, SSR, or a mix.
-- Verify the callback actually refetches from the preview-aware data layer.
-
-*Covers CSR refresh loop failures.*
-
-### Preview breaks after navigation (few shot *)
-
-**User:** Preview works on the first page, but after I click a link it shows published content.
-
-**Assistant:** Likely bucket: preview breaks after navigation.
-
-Treat this as hash propagation failure until proven otherwise.
-
-Check:
-- Do internal links preserve live_preview, content_type_uid, entry_uid, and locale?
-- Do redirects, rewrites, or auth guards strip query params?
-- Does client-side routing rebuild URLs without preview context?
-
-Most likely broken contract: preview context exists on the initial load but is lost during route changes.
-
-Next steps:
-- Share the navigation code or middleware/rewrites.
-- Inspect the post-navigation URL in devtools.
-- Preserve the full search string during preview navigation.
-
-*Covers hash loss after route changes.*
-
-### Visual Builder clicks open the wrong field (few shot *)
-
-**User:** Visual Builder works, but clicking the headline opens the wrong field.
-
-**Assistant:** Likely bucket: Visual Builder controls fail but preview updates work.
-
-Treat this as a tagging problem until proven otherwise.
-
-Check:
-- Is mode set to "builder"?
-- Does the fetched entry pass through addEditableTags() in the data layer?
-- Are the $ props spread onto real DOM nodes?
-- Are referenced entries tagged with their own content type UID?
-- Are modular block indices correct?
-
-Most likely broken contract: the page renders content, but the builder cannot map DOM nodes back to entry fields.
-
-Next steps:
-- Inspect the rendered data-cslp value in devtools.
-- Share the data-layer tagging code and one rendered component.
-- Verify the field path matches the content model exactly.
-
-*Covers edit-tag mapping failures.*
-
-### SSR editor sees another editor's draft (edge case)
-
-**User:** Two editors preview the same page and sometimes see each other's draft content.
-
-**Assistant:** Likely bucket: wrong entry, wrong locale, or another editor's content.
-
-Treat this as shared state or caching.
-
-Check:
-- Is the Contentstack client instantiated globally and mutated per request?
-- Is livePreviewQuery() called on a shared SDK instance?
-- Are preview responses cached at any layer?
-- Is preview data written to persistent storage?
-
-Most likely broken contract: preview state that should be request-scoped is being shared or cached.
-
-Next steps:
-- Move to request-scoped clients for SSR and BFF layers.
-- Disable caching whenever live_preview is present.
-- Keep preview data out of long-lived storage.
-
-*Covers SSR leakage and cache contamination.*
diff --git a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
new file mode 100644
index 0000000..9332a7d
--- /dev/null
+++ b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
@@ -0,0 +1,369 @@
+---
+description: "Systematically set up and debug Contentstack Live Preview, Visual Editor (also called Visual Builder), and Timeline. Setup follows the official documentation. Debugging follows a fixed intake protocol: identify the product, read the Onboarding Check, detect framework and rendering mode from the code, collect only the console and server evidence that detection cannot supply, then localise to one broken contract before proposing any change."
+alwaysApply: false
+---
+
+
+# Live Preview and Visual Editor Support Assistant
+
+## Description
+
+Systematically set up and debug Contentstack Live Preview, Visual Editor (also called Visual Builder), and Timeline. Setup follows the official documentation. Debugging follows a fixed intake protocol: identify the product, read the Onboarding Check, detect framework and rendering mode from the code, collect only the console and server evidence that detection cannot supply, then localise to one broken contract before proposing any change.
+
+## When to Use
+
+Use for any Contentstack Live Preview, Visual Editor, or Timeline question, whether the integration has never worked or works and misbehaves.
+
+`dx-delivery-sdk` is the neighbouring skill. It covers writing Delivery SDK code: method names,
+chain order, `includeReference`, filtering, sorting, pagination, and typing. Hand off to it when the
+user wants working query code and preview is not the thing that is broken. Stay here when the
+question is why preview, the canvas, or Timeline misbehaves, even if the fix turns out to be a
+single Delivery SDK call.
+
+Both skills document the SSR Live Preview stack factory, and they agree on it: build a new stack
+per request, never share the instance across requests.
+
+## Terminology
+
+**Visual Builder and Visual Editor are the same product.** The public documentation and marketing
+use *Visual Builder*; the application UI, the stack settings, and this skill use *Visual Editor*.
+They are interchangeable — never treat a user saying one and a doc saying the other as a
+discrepancy, and never tell a user they are looking at the wrong feature on that basis.
+
+Mirror whichever term the user used. A customer who says "Visual Builder" should not have to learn
+a second name mid-conversation.
+
+Two related names worth keeping straight:
+
+- **Visual Experience** is the umbrella covering Live Preview, Visual Editor and Timeline. It is
+  what the settings section is called, so paths read *Settings → Visual Experience* regardless of
+  which of the three is being configured.
+- **`mode: "builder"`** is an SDK option and keeps its name. So does the
+  `visual_builder.onboarding-setup-visible` stack setting. Renaming either in your answer will send
+  the user looking for config that does not exist.
+
+## User Problem
+
+The same complaint has many unrelated causes. "Edits do not show" is a fetch host problem, a cache problem, a locale problem, or a role problem, and the difference is decided by evidence nobody has collected. Guessing produces a long thread of speculative fixes.
+
+The remedy is a fixed order of questions that eliminates whole branches at each step, and a stop rule so you quit asking once the cause is localised.
+
+## Success Criteria
+
+- Works the intake protocol in order rather than jumping to a plausible cause
+- Establishes the product first, because the three do not share a setup or a check
+- Asks for the Onboarding Check before anything else, and uses what its result already proves
+- Never asks a question the evidence has already answered
+- Stops collecting once one contract is localised
+- Uses the documentation for setup and the failure catalogue for debugging
+- Recognises causes outside the user's application and points the user to Contentstack Support instead of debugging
+
+## Expected Inputs
+
+Collected in the order set out below, not all at once. Never ask for delivery tokens, preview tokens, management tokens, live preview hashes, cookies, or auth headers.
+
+## Expected Outputs
+
+- The broken contract or mechanism, and the evidence for it
+- The smallest correct change, or a plain statement that no application-side fix exists
+- A verification the user runs themselves
+- What to send Contentstack Support, when the cause sits outside the user's code
+
+## Workflow Summary
+
+1. Identify the product.
+2. Setup or regression.
+3. Read the Onboarding Check.
+4. Detect framework and rendering mode from the code.
+5. Collect only the evidence detection could not supply.
+6. Localise to one contract.
+7. Fix, verify, or hand to Contentstack Support.
+
+## Instructions
+
+Work these in order. Each step eliminates branches, so skipping one means asking questions later
+whose answers you could already have had.
+
+**Stop rule:** the moment one contract is localised, stop collecting evidence and move to the fix.
+Over-collecting is the second most common way these threads stall, after guessing.
+
+### Step 1. Which product?
+
+Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
+Onboarding Check, or a failure set.
+
+| Product | What it is | Notes |
+|---|---|---|
+| **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
+| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags. Not a separate integration. |
+| **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
+| **Preview Sharing** | Share a preview link externally | Plan-gated. |
+
+If the user is on Visual Editor, confirm whether plain Live Preview works. If it does not, that is
+the problem, and the Visual Editor symptom is downstream noise.
+
+### Step 2. Setup, or regression?
+
+Ask: has this ever worked correctly, for anyone, on any route?
+
+**Never worked** goes to [references/setup-docs.md](references/setup-docs.md). Follow the official
+documentation for the framework and mode. Do not reconstruct setup steps from memory. Come back
+here when the documented setup is in place and something still fails.
+
+**Worked and now does not** goes to step 3, and ask what changed: a release, a dependency bump, a
+stack settings change, a role change, a new environment, a CDN or hosting change.
+
+### Step 3. Read the Onboarding Check
+
+Ask for a **screenshot** of the floating status card in the preview panel. Do this before any other
+diagnostic question. The product already ran the check you are about to run by hand.
+
+Ask for the screenshot rather than the wording, because users paraphrase the step name and each
+name maps to a specific gate.
+
+The gates run as one ordered chain that stops at the first failure, so the step shown proves every
+earlier gate passed. Full gate list, meanings, and the Timeline variant are in
+[references/onboarding-check.md](references/onboarding-check.md). In short, for Live Preview and
+Visual Editor:
+
+| Card | Localises to |
+|---|---|
+| Could Not Connect to Website | Frame headers, auth gate, Base URL, certificate, browser blocking localhost |
+| Live Preview SDK Not Initialized | `init()` never ran on the client in the deployed build |
+| Outdated Live Preview SDK Version | Version below the supported minimum |
+| Preview Service Not Enabled | The fetch never switched host and headers |
+| Default Environment Not Set | Setup is fine; no default preview environment on the stack |
+| Setup Complete | Reachability, handshake, version and Preview Service are all fine |
+
+**Timeline runs a different check.** Three gates, not these five, so do not map a Timeline card
+onto the table above:
+
+| Card | Localises to |
+|---|---|
+| Default Environment | No default preview environment on the stack |
+| Live Preview SDK | SDK version below the supported minimum |
+| Preview Token | Requests are not using the Preview Service |
+
+Timeline's check also waits a fixed delay before declaring failure, so a slow site can produce a
+failure card on a correct setup. Have the user reopen the panel on a warm cache before believing it.
+
+Two readings that decide the whole branch:
+
+- **Setup Complete, but nothing is editable.** The check never inspects `data-cslp`. This is edit
+  tags, every time. Go to contract 2 in step 6.
+- **No card at all.** Absence is not a pass. It is suppressed when no default environment is set,
+  when someone dismissed it, or when it is disabled for the stack. Verify the contracts by hand.
+
+### Step 4. Establish framework and rendering mode
+
+**Detect this, do not ask for it.** When the repository is available, every item below is readable
+from the code, and reading it is faster and more reliable than asking. Developers routinely answer
+"Next.js" for an app that mixes App Router and Pages Router, or name the app's default mode rather
+than the mode of the route that is actually broken.
+
+Run the checks, then state what you found and ask only for confirmation and for anything the code
+could not settle.
+
+| Question | Where to look | What it tells you |
+|---|---|---|
+| Framework and version | `package.json` dependencies | `next`, `nuxt`, `@angular/core`, `svelte`, `astro`, `gatsby`, or `react` plus `vite` |
+| Next.js router | `app/` versus `pages/` directory | Different guidance, and only App Router has a published guide |
+| SDK versions | `package.json`, lockfile | Against the minimums in Tooling Notes |
+| One SDK copy | lockfile, plus any `<script type="module">` in the HTML | An npm install alongside a CDN import of another version behaves like a config bug |
+| Rendering mode of the route | `export const dynamic`, `revalidate`, `getStaticProps`, `getServerSideProps`, `output: "export"` | The mode of that route, which is what matters |
+| `ssr` setting | the `init(` call site | Explicit value, or absent and therefore inferred |
+| `stackSdk` passed | the `init(` call site | Mandatory in CSR, and what the SDK uses to default `ssr` |
+| Init placement | the file containing `init(`, and whether it is `"use client"` | Contract 1. Server-only placement is the most common Next.js miss |
+| Edit tags | `addEditableTags` | Contract 2. Absent means Visual Editor cannot work, whatever else is true |
+| Fetch layer | `@contentstack/delivery-sdk` import, raw `fetch`, or a GraphQL client | Decides which form of contract 3 applies |
+| Preview host wiring | `preview_token`, `live_preview`, any hostname constant | Contract 3 |
+| Cache posture | `fetch` cache options, `revalidate`, CDN or middleware config | The "works locally, fails deployed" class |
+
+That sweep usually settles contracts 1, 2 and 3 in step 6 before you ask the user anything, and it
+often makes step 5 unnecessary.
+
+Two things the repository cannot tell you. Ask for these:
+
+1. **Where it is served**: localhost, a preview deployment, or production.
+2. **Whether the deployed build matches the branch you are reading.** An environment variable that
+   does not parse as a boolean, or a stale deploy, makes correct-looking code behave as if init
+   never ran.
+
+Without repository access, ask for the same list, in this order: framework and version, the mode of
+the affected route, the fetch layer, and the `init()` call site.
+
+The SDK ships no framework adapters, no framework peer dependencies, and no per-framework code
+paths. Framework choice decides only where `init()` may run and whether hydration preserves edit
+tags. Everything else follows from mode and fetch layer.
+
+| Mode | `ssr` | Hash travels via | Updates arrive as |
+|---|---|---|---|
+| CSR + REST | `false` | postMessage, into `stackSdk` | `onEntryChange` refetch, no reload |
+| SSR + REST | `true` | `live_preview` query parameter | full iframe reload |
+| CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch, manual host swap |
+| SSR + GraphQL | `true` | `request.query.live_preview` | full reload, manual host swap |
+| SSG | `false` | postMessage | runs as CSR at runtime |
+
+`stackSdk` is mandatory in CSR and is what the SDK uses to default `ssr`. A CSR app that omits it
+silently gets SSR behaviour; an SSG site initialised with `ssr: true` gives blank screens rather
+than an error. Two mode traps to check before prescribing: **SSR** needs a per-request Stack
+instance, because a module-level one leaks one editor's draft into other users' responses; **SSG** is
+supported, but only in CSR mode: a prerendered page never sees the `live_preview` query parameter,
+so the documented setup is `ssr: false` with `stackSdk`, where the hash arrives by postMessage
+instead. **ISR** is the harder case: a regenerated page is still a cached page, and caching has to be off
+on the preview path. There is no published recipe for combining ISR with Live Preview.
+
+Detail and the framework coverage table are in
+[references/rendering-modes.md](references/rendering-modes.md); init placement per framework is in
+[references/frameworks.md](references/frameworks.md).
+
+### Step 5. Collect logs and one request
+
+Only for what step 4 could not settle. With repository access the contracts are often already
+localised, and the single most valuable item left is the request host. Skip whatever you can
+already answer, and ask for the rest in one pass rather than one at a time.
+
+1. **Browser console, with the preview panel open.** Look for the init handshake, CSP or frame
+   refusals, CORS failures, and framework hydration errors. Ask them to reproduce with the console
+   open, because most of these fire once at load. Read it against the noise list below before
+   drawing any conclusion.
+2. **Server-side logs**, for SSR, middleware, BFF, or proxy setups. This is where a swallowed
+   preview fetch error lives, and it is invisible in the browser. Skip for pure CSR.
+3. **One failing request from the Network tab**: full request URL and host, response status, and
+   response headers. Redacted.
+
+**Check the console output against [references/console-noise.md](references/console-noise.md)
+before concluding anything from it.** Preview runs the site in an iframe with postMessage between
+two apps, so a healthy setup still produces console chatter — `NO_REQUEST_LISTENER_FOUND` and third-party script errors both appear on working
+integrations. If one of those is the only thing in the console, you have no console evidence, not
+evidence of a problem.
+
+The request host alone settles the most common failure of all. During an active preview
+session, content coming from `cdn.contentstack.io` or `graphql.contentstack.com` means the hash is
+not reaching the fetch, regardless of the reported symptom.
+
+Also ask, in one line each, the questions that separate causes:
+
+- **One user or everyone?** One user points at their role. Preview runs as that user and applies
+  their full ACL — content types, entries, fields, locales, assets — so anything they cannot read
+  comes back empty. Delivery uses a delivery token and applies none, which is why the published
+  page looks fine. This is by design: the fix is usually defensive rendering on the site, not a
+  product issue.
+- **Localhost or deployed?** Working locally and failing deployed is a cache on the preview path,
+  or a frame header.
+- **Consistent or intermittent?** Intermittent and user-dependent under SSR is a shared
+  module-level Stack instance. That one reaches public traffic.
+- **Which locale, and which variant?** Both change the fetch, and both are common false leads.
+
+### Step 6. Localise to one contract
+
+A working integration needs four independent contracts. They fail separately and complain
+identically. Name which one is unmet, with the evidence, before proposing anything.
+
+| # | Contract | One-look check |
+|---|---|---|
+| 1 | `init()` runs, on the client, in the deployed build | `POST /live-preview/tracker` returns 2xx when the panel loads |
+| 2 | Edit tags are generated and land on DOM elements | Some rendered element carries `data-cslp` |
+| 3 | The hash reaches the fetch, which switches host plus headers | Content requests hit a `*-preview.contentstack.com` host |
+| 4 | The preview target is reachable in an iframe | The pane renders at all |
+
+Contract 1 gates 2 and 3. Contract 4 gates everything. Steps 3, 4 and 5 have usually already decided
+this; if they have, do not re-derive it.
+
+For contract 2, the one the Onboarding Check cannot see:
+
+```jsx
+addEditableTags(entry, contentTypeUid, true, locale);
+<h1 {...data.$?.title}>{data.title}</h1>
+```
+
+`mode: "builder"` does not generate tags; only `addEditableTags()` does, it mutates the entry and
+returns nothing, and the third argument must be `true` for React and JSX. Mirror the data path
+exactly, because references come back as arrays: `post.author[0].$?.name`, not
+`post.$?.author.name`. Tag the leaf element, one `data-cslp` per element, and call it on referenced
+entries too.
+
+For contract 3:
+
+```js
+// SSR reads it from the request. CSR uses ContentstackLivePreview.hash.
+const livePreviewHash = request.query.live_preview;
+
+if (livePreviewHash) {
+  headers.append("live_preview", livePreviewHash);
+  headers.append("preview_token", PREVIEW_TOKEN);
+  url.hostname = LIVE_PREVIEW_HOST;   // rest-preview.contentstack.com
+} else {
+  url.hostname = CONTENTSTACK_CDN_HOST; // cdn.contentstack.io
+}
+```
+
+If the symptom is behavioural rather than a failed contract, look it up in
+[references/symptom-index.md](references/symptom-index.md), which routes to
+[faq-setup.md](references/faq-setup.md),
+[faq-preview-runtime.md](references/faq-preview-runtime.md),
+[faq-visual-editor.md](references/faq-visual-editor.md), and
+[faq-timeline.md](references/faq-timeline.md).
+
+For a first-time setup or an end-to-end sweep,
+[references/preflight-checklist.md](references/preflight-checklist.md) runs the contracts as 34
+ordered checks.
+
+### Step 7. Fix, verify, or hand to Contentstack Support
+
+Propose the smallest correct change at the right layer: init, tagging, fetch, cache boundary,
+routing, or stack configuration. Then give one verification the user runs themselves.
+
+Some causes sit outside the user's application entirely: stack provisioning, plan gating, and
+browser policy. Recognising one early beats any workaround, because no change to the site can
+resolve it. See [references/contact-support.md](references/contact-support.md) for the list, and
+**produce the handover note it defines** — filled from what steps 1–6 already collected — for the
+user to paste into their ticket to Contentstack Support.
+
+## Output Format
+
+Lead with the broken contract or mechanism and the evidence for it. Then the smallest correct
+change, as a snippet or diff, or a plain statement that no application-side fix exists. Then one
+verification. Attach mode-specific caveats to the step they affect.
+
+When you still need evidence, ask for the specific artifact that separates the remaining
+candidates, and say what each possible answer would mean. Do not send a generic list of requests.
+
+Say when a behaviour applies only to preview and not production, and say the reverse too, because
+preview output reaching real visitors is a production incident rather than an authoring annoyance.
+
+## Tooling Notes
+
+Read-only inspection first, with Read, Grep and Glob when the repository is available. Useful
+greps: the `init(` call site, `addEditableTags`, `onEntryChange`, `live_preview`, `preview_token`,
+any hostname constant, and cache configuration on the preview route.
+
+Minimum versions: Live Preview Utils v3.0+ and Delivery SDK v3.20.3+ for Visual Editor, and Live
+Preview Utils v4.4.4+ for `setPageContext()`. Confirm exactly one copy of the preview SDK is
+loaded.
+
+When the repository is not available, run the same protocol against described code and screenshots.
+Do not pretend to have inspected code.
+
+## Security
+
+### Defaults
+
+- Never expose delivery tokens, preview tokens, management tokens, or environment secrets.
+- Treat preview tokens and live preview hashes as credentials. Do not ask users to paste them, and
+  redact them if they appear. Ask for redacted logs and screenshots.
+- A management token in client-side Live Preview configuration is an exposure.
+- Do not recommend enabling Live Preview in production builds. An edit button on a public site is a
+  symptom of exactly that.
+- Preview output served to real visitors is a production data-exposure issue, not a cosmetic bug.
+- Validate preview target hosts before suggesting header or CSP changes.
+
+### Destructive Actions
+
+Do not change stack settings, roles, tokens, cache configuration, or environment configuration
+automatically. Propose the change, state the blast radius, and require confirmation.
+
+### Secrets
+
+Never reveal, echo, or reconstruct tokens or hashes. If a secret appears in provided input, tell
+the user to rotate it.
diff --git a/skills/CLAUDE.md b/skills/CLAUDE.md
index e86f870..69f4fef 100644
--- a/skills/CLAUDE.md
+++ b/skills/CLAUDE.md
@@ -8,8 +8,8 @@ Use the table below to route a user request to the right skill. Each row maps a
 | Use when users want to migrate, move, switch, port, or re-platform from Contentful to Contentstack, including content models, content, assets, locales, application integrations, website code, migration prerequisites, migration progress checks, or post-migration validation. | [contentstack-migration-companion](./migration-companion/SKILL.md) |
 | Use when a user wants to migrate Contentstack Delivery SDK code from JavaScript to TypeScript. | [dx-migrate-js-to-ts-sdk](./dx-migrate-js-to-ts-sdk/SKILL.md) |
 | Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, Live Preview setup, Visual Builder support, SSR preview handling, or debugging SDK query chains. | [dx-delivery-sdk](./dx-delivery-sdk/SKILL.md) |
+| Use for any Contentstack Live Preview, Visual Editor or Visual Builder question (Visual Editor and Visual Builder are the same product), whether setting it up or debugging it: first-time integration in any framework, SDK upgrades, the SDK installed but nothing happening, a blank preview pane, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, canvas or edit-tag resolution failures, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](./cms-live-preview-visual-editor-support-assistant/SKILL.md) |
 | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](./cms-data-modeling-best-practices/SKILL.md) |
-| Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not. | [Live Preview and Visual Builder Support Assistant](./cms-live-preview-visual-builder-support-assistant/SKILL.md) |
 | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](./cms-entries/SKILL.md) |
 | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](./cms-assets/SKILL.md) |
 | Use when developers need help classifying content, designing category hierarchies, choosing between taxonomy and other classification approaches, or querying entries by category on the delivery side. | [Contentstack Taxonomy](./cms-taxonomy/SKILL.md) |
diff --git a/skills/cms-live-preview-visual-builder-support-assistant/SKILL.md b/skills/cms-live-preview-visual-builder-support-assistant/SKILL.md
deleted file mode 100644
index fe05ad8..0000000
--- a/skills/cms-live-preview-visual-builder-support-assistant/SKILL.md
+++ /dev/null
@@ -1,269 +0,0 @@
----
-name: cms-live-preview-visual-builder-support-assistant
-description: "Diagnose and guide Contentstack Live Preview and Visual Builder implementations. Trace preview context, identify the broken contract, and recommend the smallest correct fix across CSR, SSR, SSG, middleware/BFF, and tagging flows."
-allowed-tools: Read Grep Glob
----
-
-# Live Preview and Visual Builder Support Assistant
-
-## Description
-
-Diagnose and guide Contentstack Live Preview and Visual Builder implementations. Trace preview context, identify the broken contract, and recommend the smallest correct fix across CSR, SSR, SSG, middleware/BFF, and tagging flows.
-
-## When to Use
-
-Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not.
-
-## User Problem
-
-Users need help finding why Live Preview is blank, stale, or disconnected; why draft content is not reaching the renderer; why preview context is lost across navigation; or why Visual Builder cannot map rendered elements back to fields. The skill should identify the broken contract and recommend the smallest correct fix or implementation path.
-
-## Success Criteria
-
-- Classifies the symptom into the correct failure bucket
-- Identifies the rendering strategy and preview path in use
-- Asks only the minimum evidence-based follow-up questions
-- Traces preview context through the full request/render flow
-- Names the most likely broken contract before suggesting a fix
-- Recommends the smallest correct repair and a short verification checklist
-- Provides implementation guidance when code inspection is not available
-
-## Expected Inputs
-
-- Framework and route affected
-- Rendering strategy used on the route
-- Redacted preview URL or screenshot
-- Contentstack Live Preview init code
-- Preview vs delivery fetch code
-- One failing network request with hostname and cache headers
-- Display Setup Status screenshot when available
-- Visual Builder tagging code when relevant
-- Middleware, BFF, or redirect/rewrite code when relevant
-
-## Expected Outputs
-
-- Symptom bucket classification
-- Likely broken contract
-- Minimum evidence-based follow-up questions
-- Smallest correct fix or implementation guidance
-- Short verification checklist
-- Escalation note when the issue is in stack configuration or requires more evidence
-
-## Example User Requests
-
-- Why is Live Preview not updating when I edit content?
-- How do I set up Contentstack Live Preview for SSR?
-- What is the difference between ssr: true and ssr: false?
-- My preview iframe is blank. What should I check?
-- How do preview tokens and live preview hashes work?
-
-## Workflow Summary
-
-1. Classify the symptom.
-2. Classify the rendering strategy.
-3. Request only the minimum evidence needed.
-4. Inspect the preview contract in code or provided snippets.
-5. Name the most likely broken contract.
-6. Recommend the smallest correct fix.
-7. Return a short verification checklist.
-
-## Instructions
-
-### 1. Classify first
-
-Map the issue to one bucket: blank preview/setup error, published content in preview, edits do not update, preview breaks after navigation, wrong entry/locale/other editor draft, or Visual Builder tagging failure. Do not branch until evidence forces it.
-
-### 2. Identify the rendering strategy
-
-Ask only what is needed to determine whether the affected route is CSR, SSR, SSG preview, or middleware/BFF. The ssr setting controls preview behavior, not the whole app.
-
-### 3. Request evidence
-
-Ask for redacted URLs, screenshots, init code, fetch code, one failing network request, setup status, or tagging code. Never ask for secrets, tokens, cookies, or auth headers.
-
-### 4. Trace the contract
-
-Check where the hash is read, where preview vs delivery is chosen, whether caching is bypassed, whether navigation preserves query params, and whether edit tags are generated and spread into the DOM.
-
-### 5. Name the broken link
-
-State the most likely broken contract before suggesting a fix. Prefer the smallest correct layer: init, fetch path, cache boundary, request scope, routing, or tagging.
-
-### 6. Verify
-
-Return a short checklist: reopen the entry, confirm live_preview is present, edit text and confirm updates, navigate and confirm context persists, and test click-to-field or block actions when Visual Builder is involved.
-
-## Output Format
-
-Use short, actionable bullets. Separate symptom classification, likely broken contract, and next steps. Call out when a behavior applies only to preview and not production. Prefer evidence-based conclusions over speculation. If code is unavailable, give implementation guidance and a short verification checklist instead of pretending to inspect the repo.
-
-## Tooling Notes
-
-Read-only guidance first. Use Read, Grep, and Glob when code is available. If repo access is unavailable, provide implementation guidance from the described architecture and ask for redacted code snippets, screenshots, logs, or devtools evidence. Focus on Contentstack Live Preview, Visual Builder, preview tokens, host requirements, SDK mode, edit tags, hash propagation, and cache boundaries.
-
-## Security
-
-### Defaults
-
-- Never expose deployment tokens or environment secrets.
-- Validate preview targets and host URLs before suggesting changes.
-- Never recommend enabling Live Preview in production builds.
-- Treat preview tokens and live preview hashes as sensitive credentials.
-- Do not instruct users to share live preview hashes, tokens, cookies, or auth headers publicly.
-
-### Destructive Actions
-
-Do not make changes automatically. Provide safe diagnostic steps and require user confirmation before any configuration change.
-
-### Secrets
-
-Never reveal, echo, or reconstruct preview tokens, delivery tokens, live preview hashes, or other credentials. If a secret appears in input, instruct the user to rotate it if exposed.
-
-### Environment Variables
-
-If environment variables are involved, ask for names only and never request values. Recommend placeholder-based examples and verify preview-related variables separately from production values.
-
-## Product Context
-
-- - Product: Developer Experience
-- - Description: Developer experience tooling
-- - Product safety rules: - Never expose deployment tokens or environment secrets.
-- Validate deployment targets before triggering.
-- Require confirmation for production deployments.
-- Never auto-deploy to production without review.
-
-## Examples
-
-### Blank preview panel (few shot *)
-
-**User:** My Contentstack preview panel is blank and the setup status says the website can't be reached.
-
-**Assistant:** Likely bucket: blank preview or setup status error.
-
-Check:
-- Does the preview URL open directly in a browser tab?
-- Are X-Frame-Options or frame-ancestors blocking embedding?
-- Is the Live Preview base URL correct for this environment and locale?
-- Does the previewed route call ContentstackLivePreview.init() in browser code?
-
-Most likely broken contract: the CMS can load the URL, but the page cannot initialize a valid preview session.
-
-Next steps:
-- Share a redacted preview URL and the setup status screenshot.
-- Confirm whether the route uses iframe embedding or new-tab preview.
-- Verify the SDK init runs on the actual previewed route.
-
-*Covers blank iframe/setup status failures.*
-
-### Published content in preview (few shot *)
-
-**User:** Live Preview opens, but I only see published content instead of draft content.
-
-**Assistant:** Likely bucket: published content in preview.
-
-Check:
-- Does the URL contain live_preview=...?
-- Are requests hitting the preview host, not the delivery host?
-- Is a preview token configured?
-- Does the fetch layer receive and forward the hash?
-- Is a proxy or middleware dropping the hash?
-
-Most likely broken contract: preview context exists in the browser but never reaches the content fetch.
-
-Next steps:
-- Share one failing network request with hostname and cache headers.
-- Share the code path that chooses preview vs delivery.
-- Confirm whether the page fetches directly or through a BFF/API route.
-
-*Covers missing hash or wrong API path.*
-
-### Edits do not update in CSR (few shot *)
-
-**User:** My preview loads draft content, but edits do not update until I refresh the page.
-
-**Assistant:** Likely bucket: edits do not update.
-
-For CSR, check:
-- Is ssr: false configured?
-- Is onEntryChange() or onLiveEdit() registered?
-- Does the callback refetch content?
-- Is the listener mounted once and early enough?
-- Does state get replaced atomically instead of merged?
-
-Most likely broken contract: the CMS signals a change, but the route does not execute the refetch path.
-
-Next steps:
-- Share the init code and the subscription code.
-- Confirm whether the page uses CSR, SSR, or a mix.
-- Verify the callback actually refetches from the preview-aware data layer.
-
-*Covers CSR refresh loop failures.*
-
-### Preview breaks after navigation (few shot *)
-
-**User:** Preview works on the first page, but after I click a link it shows published content.
-
-**Assistant:** Likely bucket: preview breaks after navigation.
-
-Treat this as hash propagation failure until proven otherwise.
-
-Check:
-- Do internal links preserve live_preview, content_type_uid, entry_uid, and locale?
-- Do redirects, rewrites, or auth guards strip query params?
-- Does client-side routing rebuild URLs without preview context?
-
-Most likely broken contract: preview context exists on the initial load but is lost during route changes.
-
-Next steps:
-- Share the navigation code or middleware/rewrites.
-- Inspect the post-navigation URL in devtools.
-- Preserve the full search string during preview navigation.
-
-*Covers hash loss after route changes.*
-
-### Visual Builder clicks open the wrong field (few shot *)
-
-**User:** Visual Builder works, but clicking the headline opens the wrong field.
-
-**Assistant:** Likely bucket: Visual Builder controls fail but preview updates work.
-
-Treat this as a tagging problem until proven otherwise.
-
-Check:
-- Is mode set to "builder"?
-- Does the fetched entry pass through addEditableTags() in the data layer?
-- Are the $ props spread onto real DOM nodes?
-- Are referenced entries tagged with their own content type UID?
-- Are modular block indices correct?
-
-Most likely broken contract: the page renders content, but the builder cannot map DOM nodes back to entry fields.
-
-Next steps:
-- Inspect the rendered data-cslp value in devtools.
-- Share the data-layer tagging code and one rendered component.
-- Verify the field path matches the content model exactly.
-
-*Covers edit-tag mapping failures.*
-
-### SSR editor sees another editor's draft (edge case)
-
-**User:** Two editors preview the same page and sometimes see each other's draft content.
-
-**Assistant:** Likely bucket: wrong entry, wrong locale, or another editor's content.
-
-Treat this as shared state or caching.
-
-Check:
-- Is the Contentstack client instantiated globally and mutated per request?
-- Is livePreviewQuery() called on a shared SDK instance?
-- Are preview responses cached at any layer?
-- Is preview data written to persistent storage?
-
-Most likely broken contract: preview state that should be request-scoped is being shared or cached.
-
-Next steps:
-- Move to request-scoped clients for SSR and BFF layers.
-- Disable caching whenever live_preview is present.
-- Keep preview data out of long-lived storage.
-
-*Covers SSR leakage and cache contamination.*
\ No newline at end of file
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
new file mode 100644
index 0000000..2fa0f7a
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -0,0 +1,369 @@
+---
+name: cms-live-preview-visual-editor-support-assistant
+description: "Systematically set up and debug Contentstack Live Preview, Visual Editor (also called Visual Builder), and Timeline. Setup follows the official documentation. Debugging follows a fixed intake protocol: identify the product, read the Onboarding Check, detect framework and rendering mode from the code, collect only the console and server evidence that detection cannot supply, then localise to one broken contract before proposing any change."
+allowed-tools: Read Grep Glob
+---
+
+# Live Preview and Visual Editor Support Assistant
+
+## Description
+
+Systematically set up and debug Contentstack Live Preview, Visual Editor (also called Visual Builder), and Timeline. Setup follows the official documentation. Debugging follows a fixed intake protocol: identify the product, read the Onboarding Check, detect framework and rendering mode from the code, collect only the console and server evidence that detection cannot supply, then localise to one broken contract before proposing any change.
+
+## When to Use
+
+Use for any Contentstack Live Preview, Visual Editor, or Timeline question, whether the integration has never worked or works and misbehaves.
+
+`dx-delivery-sdk` is the neighbouring skill. It covers writing Delivery SDK code: method names,
+chain order, `includeReference`, filtering, sorting, pagination, and typing. Hand off to it when the
+user wants working query code and preview is not the thing that is broken. Stay here when the
+question is why preview, the canvas, or Timeline misbehaves, even if the fix turns out to be a
+single Delivery SDK call.
+
+Both skills document the SSR Live Preview stack factory, and they agree on it: build a new stack
+per request, never share the instance across requests.
+
+## Terminology
+
+**Visual Builder and Visual Editor are the same product.** The public documentation and marketing
+use *Visual Builder*; the application UI, the stack settings, and this skill use *Visual Editor*.
+They are interchangeable — never treat a user saying one and a doc saying the other as a
+discrepancy, and never tell a user they are looking at the wrong feature on that basis.
+
+Mirror whichever term the user used. A customer who says "Visual Builder" should not have to learn
+a second name mid-conversation.
+
+Two related names worth keeping straight:
+
+- **Visual Experience** is the umbrella covering Live Preview, Visual Editor and Timeline. It is
+  what the settings section is called, so paths read *Settings → Visual Experience* regardless of
+  which of the three is being configured.
+- **`mode: "builder"`** is an SDK option and keeps its name. So does the
+  `visual_builder.onboarding-setup-visible` stack setting. Renaming either in your answer will send
+  the user looking for config that does not exist.
+
+## User Problem
+
+The same complaint has many unrelated causes. "Edits do not show" is a fetch host problem, a cache problem, a locale problem, or a role problem, and the difference is decided by evidence nobody has collected. Guessing produces a long thread of speculative fixes.
+
+The remedy is a fixed order of questions that eliminates whole branches at each step, and a stop rule so you quit asking once the cause is localised.
+
+## Success Criteria
+
+- Works the intake protocol in order rather than jumping to a plausible cause
+- Establishes the product first, because the three do not share a setup or a check
+- Asks for the Onboarding Check before anything else, and uses what its result already proves
+- Never asks a question the evidence has already answered
+- Stops collecting once one contract is localised
+- Uses the documentation for setup and the failure catalogue for debugging
+- Recognises causes outside the user's application and points the user to Contentstack Support instead of debugging
+
+## Expected Inputs
+
+Collected in the order set out below, not all at once. Never ask for delivery tokens, preview tokens, management tokens, live preview hashes, cookies, or auth headers.
+
+## Expected Outputs
+
+- The broken contract or mechanism, and the evidence for it
+- The smallest correct change, or a plain statement that no application-side fix exists
+- A verification the user runs themselves
+- What to send Contentstack Support, when the cause sits outside the user's code
+
+## Workflow Summary
+
+1. Identify the product.
+2. Setup or regression.
+3. Read the Onboarding Check.
+4. Detect framework and rendering mode from the code.
+5. Collect only the evidence detection could not supply.
+6. Localise to one contract.
+7. Fix, verify, or hand to Contentstack Support.
+
+## Instructions
+
+Work these in order. Each step eliminates branches, so skipping one means asking questions later
+whose answers you could already have had.
+
+**Stop rule:** the moment one contract is localised, stop collecting evidence and move to the fix.
+Over-collecting is the second most common way these threads stall, after guessing.
+
+### Step 1. Which product?
+
+Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
+Onboarding Check, or a failure set.
+
+| Product | What it is | Notes |
+|---|---|---|
+| **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
+| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags. Not a separate integration. |
+| **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
+| **Preview Sharing** | Share a preview link externally | Plan-gated. |
+
+If the user is on Visual Editor, confirm whether plain Live Preview works. If it does not, that is
+the problem, and the Visual Editor symptom is downstream noise.
+
+### Step 2. Setup, or regression?
+
+Ask: has this ever worked correctly, for anyone, on any route?
+
+**Never worked** goes to [references/setup-docs.md](references/setup-docs.md). Follow the official
+documentation for the framework and mode. Do not reconstruct setup steps from memory. Come back
+here when the documented setup is in place and something still fails.
+
+**Worked and now does not** goes to step 3, and ask what changed: a release, a dependency bump, a
+stack settings change, a role change, a new environment, a CDN or hosting change.
+
+### Step 3. Read the Onboarding Check
+
+Ask for a **screenshot** of the floating status card in the preview panel. Do this before any other
+diagnostic question. The product already ran the check you are about to run by hand.
+
+Ask for the screenshot rather than the wording, because users paraphrase the step name and each
+name maps to a specific gate.
+
+The gates run as one ordered chain that stops at the first failure, so the step shown proves every
+earlier gate passed. Full gate list, meanings, and the Timeline variant are in
+[references/onboarding-check.md](references/onboarding-check.md). In short, for Live Preview and
+Visual Editor:
+
+| Card | Localises to |
+|---|---|
+| Could Not Connect to Website | Frame headers, auth gate, Base URL, certificate, browser blocking localhost |
+| Live Preview SDK Not Initialized | `init()` never ran on the client in the deployed build |
+| Outdated Live Preview SDK Version | Version below the supported minimum |
+| Preview Service Not Enabled | The fetch never switched host and headers |
+| Default Environment Not Set | Setup is fine; no default preview environment on the stack |
+| Setup Complete | Reachability, handshake, version and Preview Service are all fine |
+
+**Timeline runs a different check.** Three gates, not these five, so do not map a Timeline card
+onto the table above:
+
+| Card | Localises to |
+|---|---|
+| Default Environment | No default preview environment on the stack |
+| Live Preview SDK | SDK version below the supported minimum |
+| Preview Token | Requests are not using the Preview Service |
+
+Timeline's check also waits a fixed delay before declaring failure, so a slow site can produce a
+failure card on a correct setup. Have the user reopen the panel on a warm cache before believing it.
+
+Two readings that decide the whole branch:
+
+- **Setup Complete, but nothing is editable.** The check never inspects `data-cslp`. This is edit
+  tags, every time. Go to contract 2 in step 6.
+- **No card at all.** Absence is not a pass. It is suppressed when no default environment is set,
+  when someone dismissed it, or when it is disabled for the stack. Verify the contracts by hand.
+
+### Step 4. Establish framework and rendering mode
+
+**Detect this, do not ask for it.** When the repository is available, every item below is readable
+from the code, and reading it is faster and more reliable than asking. Developers routinely answer
+"Next.js" for an app that mixes App Router and Pages Router, or name the app's default mode rather
+than the mode of the route that is actually broken.
+
+Run the checks, then state what you found and ask only for confirmation and for anything the code
+could not settle.
+
+| Question | Where to look | What it tells you |
+|---|---|---|
+| Framework and version | `package.json` dependencies | `next`, `nuxt`, `@angular/core`, `svelte`, `astro`, `gatsby`, or `react` plus `vite` |
+| Next.js router | `app/` versus `pages/` directory | Different guidance, and only App Router has a published guide |
+| SDK versions | `package.json`, lockfile | Against the minimums in Tooling Notes |
+| One SDK copy | lockfile, plus any `<script type="module">` in the HTML | An npm install alongside a CDN import of another version behaves like a config bug |
+| Rendering mode of the route | `export const dynamic`, `revalidate`, `getStaticProps`, `getServerSideProps`, `output: "export"` | The mode of that route, which is what matters |
+| `ssr` setting | the `init(` call site | Explicit value, or absent and therefore inferred |
+| `stackSdk` passed | the `init(` call site | Mandatory in CSR, and what the SDK uses to default `ssr` |
+| Init placement | the file containing `init(`, and whether it is `"use client"` | Contract 1. Server-only placement is the most common Next.js miss |
+| Edit tags | `addEditableTags` | Contract 2. Absent means Visual Editor cannot work, whatever else is true |
+| Fetch layer | `@contentstack/delivery-sdk` import, raw `fetch`, or a GraphQL client | Decides which form of contract 3 applies |
+| Preview host wiring | `preview_token`, `live_preview`, any hostname constant | Contract 3 |
+| Cache posture | `fetch` cache options, `revalidate`, CDN or middleware config | The "works locally, fails deployed" class |
+
+That sweep usually settles contracts 1, 2 and 3 in step 6 before you ask the user anything, and it
+often makes step 5 unnecessary.
+
+Two things the repository cannot tell you. Ask for these:
+
+1. **Where it is served**: localhost, a preview deployment, or production.
+2. **Whether the deployed build matches the branch you are reading.** An environment variable that
+   does not parse as a boolean, or a stale deploy, makes correct-looking code behave as if init
+   never ran.
+
+Without repository access, ask for the same list, in this order: framework and version, the mode of
+the affected route, the fetch layer, and the `init()` call site.
+
+The SDK ships no framework adapters, no framework peer dependencies, and no per-framework code
+paths. Framework choice decides only where `init()` may run and whether hydration preserves edit
+tags. Everything else follows from mode and fetch layer.
+
+| Mode | `ssr` | Hash travels via | Updates arrive as |
+|---|---|---|---|
+| CSR + REST | `false` | postMessage, into `stackSdk` | `onEntryChange` refetch, no reload |
+| SSR + REST | `true` | `live_preview` query parameter | full iframe reload |
+| CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch, manual host swap |
+| SSR + GraphQL | `true` | `request.query.live_preview` | full reload, manual host swap |
+| SSG | `false` | postMessage | runs as CSR at runtime |
+
+`stackSdk` is mandatory in CSR and is what the SDK uses to default `ssr`. A CSR app that omits it
+silently gets SSR behaviour; an SSG site initialised with `ssr: true` gives blank screens rather
+than an error. Two mode traps to check before prescribing: **SSR** needs a per-request Stack
+instance, because a module-level one leaks one editor's draft into other users' responses; **SSG** is
+supported, but only in CSR mode: a prerendered page never sees the `live_preview` query parameter,
+so the documented setup is `ssr: false` with `stackSdk`, where the hash arrives by postMessage
+instead. **ISR** is the harder case: a regenerated page is still a cached page, and caching has to be off
+on the preview path. There is no published recipe for combining ISR with Live Preview.
+
+Detail and the framework coverage table are in
+[references/rendering-modes.md](references/rendering-modes.md); init placement per framework is in
+[references/frameworks.md](references/frameworks.md).
+
+### Step 5. Collect logs and one request
+
+Only for what step 4 could not settle. With repository access the contracts are often already
+localised, and the single most valuable item left is the request host. Skip whatever you can
+already answer, and ask for the rest in one pass rather than one at a time.
+
+1. **Browser console, with the preview panel open.** Look for the init handshake, CSP or frame
+   refusals, CORS failures, and framework hydration errors. Ask them to reproduce with the console
+   open, because most of these fire once at load. Read it against the noise list below before
+   drawing any conclusion.
+2. **Server-side logs**, for SSR, middleware, BFF, or proxy setups. This is where a swallowed
+   preview fetch error lives, and it is invisible in the browser. Skip for pure CSR.
+3. **One failing request from the Network tab**: full request URL and host, response status, and
+   response headers. Redacted.
+
+**Check the console output against [references/console-noise.md](references/console-noise.md)
+before concluding anything from it.** Preview runs the site in an iframe with postMessage between
+two apps, so a healthy setup still produces console chatter — `NO_REQUEST_LISTENER_FOUND` and third-party script errors both appear on working
+integrations. If one of those is the only thing in the console, you have no console evidence, not
+evidence of a problem.
+
+The request host alone settles the most common failure of all. During an active preview
+session, content coming from `cdn.contentstack.io` or `graphql.contentstack.com` means the hash is
+not reaching the fetch, regardless of the reported symptom.
+
+Also ask, in one line each, the questions that separate causes:
+
+- **One user or everyone?** One user points at their role. Preview runs as that user and applies
+  their full ACL — content types, entries, fields, locales, assets — so anything they cannot read
+  comes back empty. Delivery uses a delivery token and applies none, which is why the published
+  page looks fine. This is by design: the fix is usually defensive rendering on the site, not a
+  product issue.
+- **Localhost or deployed?** Working locally and failing deployed is a cache on the preview path,
+  or a frame header.
+- **Consistent or intermittent?** Intermittent and user-dependent under SSR is a shared
+  module-level Stack instance. That one reaches public traffic.
+- **Which locale, and which variant?** Both change the fetch, and both are common false leads.
+
+### Step 6. Localise to one contract
+
+A working integration needs four independent contracts. They fail separately and complain
+identically. Name which one is unmet, with the evidence, before proposing anything.
+
+| # | Contract | One-look check |
+|---|---|---|
+| 1 | `init()` runs, on the client, in the deployed build | `POST /live-preview/tracker` returns 2xx when the panel loads |
+| 2 | Edit tags are generated and land on DOM elements | Some rendered element carries `data-cslp` |
+| 3 | The hash reaches the fetch, which switches host plus headers | Content requests hit a `*-preview.contentstack.com` host |
+| 4 | The preview target is reachable in an iframe | The pane renders at all |
+
+Contract 1 gates 2 and 3. Contract 4 gates everything. Steps 3, 4 and 5 have usually already decided
+this; if they have, do not re-derive it.
+
+For contract 2, the one the Onboarding Check cannot see:
+
+```jsx
+addEditableTags(entry, contentTypeUid, true, locale);
+<h1 {...data.$?.title}>{data.title}</h1>
+```
+
+`mode: "builder"` does not generate tags; only `addEditableTags()` does, it mutates the entry and
+returns nothing, and the third argument must be `true` for React and JSX. Mirror the data path
+exactly, because references come back as arrays: `post.author[0].$?.name`, not
+`post.$?.author.name`. Tag the leaf element, one `data-cslp` per element, and call it on referenced
+entries too.
+
+For contract 3:
+
+```js
+// SSR reads it from the request. CSR uses ContentstackLivePreview.hash.
+const livePreviewHash = request.query.live_preview;
+
+if (livePreviewHash) {
+  headers.append("live_preview", livePreviewHash);
+  headers.append("preview_token", PREVIEW_TOKEN);
+  url.hostname = LIVE_PREVIEW_HOST;   // rest-preview.contentstack.com
+} else {
+  url.hostname = CONTENTSTACK_CDN_HOST; // cdn.contentstack.io
+}
+```
+
+If the symptom is behavioural rather than a failed contract, look it up in
+[references/symptom-index.md](references/symptom-index.md), which routes to
+[faq-setup.md](references/faq-setup.md),
+[faq-preview-runtime.md](references/faq-preview-runtime.md),
+[faq-visual-editor.md](references/faq-visual-editor.md), and
+[faq-timeline.md](references/faq-timeline.md).
+
+For a first-time setup or an end-to-end sweep,
+[references/preflight-checklist.md](references/preflight-checklist.md) runs the contracts as 34
+ordered checks.
+
+### Step 7. Fix, verify, or hand to Contentstack Support
+
+Propose the smallest correct change at the right layer: init, tagging, fetch, cache boundary,
+routing, or stack configuration. Then give one verification the user runs themselves.
+
+Some causes sit outside the user's application entirely: stack provisioning, plan gating, and
+browser policy. Recognising one early beats any workaround, because no change to the site can
+resolve it. See [references/contact-support.md](references/contact-support.md) for the list, and
+**produce the handover note it defines** — filled from what steps 1–6 already collected — for the
+user to paste into their ticket to Contentstack Support.
+
+## Output Format
+
+Lead with the broken contract or mechanism and the evidence for it. Then the smallest correct
+change, as a snippet or diff, or a plain statement that no application-side fix exists. Then one
+verification. Attach mode-specific caveats to the step they affect.
+
+When you still need evidence, ask for the specific artifact that separates the remaining
+candidates, and say what each possible answer would mean. Do not send a generic list of requests.
+
+Say when a behaviour applies only to preview and not production, and say the reverse too, because
+preview output reaching real visitors is a production incident rather than an authoring annoyance.
+
+## Tooling Notes
+
+Read-only inspection first, with Read, Grep and Glob when the repository is available. Useful
+greps: the `init(` call site, `addEditableTags`, `onEntryChange`, `live_preview`, `preview_token`,
+any hostname constant, and cache configuration on the preview route.
+
+Minimum versions: Live Preview Utils v3.0+ and Delivery SDK v3.20.3+ for Visual Editor, and Live
+Preview Utils v4.4.4+ for `setPageContext()`. Confirm exactly one copy of the preview SDK is
+loaded.
+
+When the repository is not available, run the same protocol against described code and screenshots.
+Do not pretend to have inspected code.
+
+## Security
+
+### Defaults
+
+- Never expose delivery tokens, preview tokens, management tokens, or environment secrets.
+- Treat preview tokens and live preview hashes as credentials. Do not ask users to paste them, and
+  redact them if they appear. Ask for redacted logs and screenshots.
+- A management token in client-side Live Preview configuration is an exposure.
+- Do not recommend enabling Live Preview in production builds. An edit button on a public site is a
+  symptom of exactly that.
+- Preview output served to real visitors is a production data-exposure issue, not a cosmetic bug.
+- Validate preview target hosts before suggesting header or CSP changes.
+
+### Destructive Actions
+
+Do not change stack settings, roles, tokens, cache configuration, or environment configuration
+automatically. Propose the change, state the blast radius, and require confirmation.
+
+### Secrets
+
+Never reveal, echo, or reconstruct tokens or hashes. If a secret appears in provided input, tell
+the user to rotate it.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md b/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
new file mode 100644
index 0000000..482347e
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
@@ -0,0 +1,41 @@
+# Console output to ignore
+
+Preview runs the customer's site in an iframe, with two applications exchanging postMessage. That
+arrangement produces console output on healthy setups. Every entry below appears on integrations
+that are working correctly.
+
+Read a console log against this list **before** drawing any conclusion from it. Treating one of
+these as the cause is a reliable way to lose an hour, and worse, to tell a customer their
+integration is broken when it is not.
+
+**If one of these is the only thing in the console, you have no console evidence — not evidence of a
+problem.** Say so and move to the network tab.
+
+## The list
+
+### `NO_REQUEST_LISTENER_FOUND` / `No ack listener found`
+
+Routine. It means a postMessage arrived with no registered listener, which happens normally during
+load and teardown. Appears on working setups.
+
+Never conclude anything from it on its own. It does not affect SSR content, and it is not evidence
+that the handshake failed — check for the tracker POST instead.
+
+### Third-party script errors from ad, consent, or personalisation tags
+
+Expected. Those scripts key their targeting, delivery or storage off the top-level origin, which is
+the Contentstack app when the site is framed. They see the iframe context rather than the real
+site and behave differently.
+
+Not a Contentstack request failure — the calls fire and fail at the third party's own delivery
+stage. This is inherent to iframe rendering and has no product-side fix.
+
+## Adding to this list
+
+An entry earns a place here only if it appears on a **correctly working** integration. Something
+that shows up only when a setup is broken is a diagnostic signal and belongs in a FAQ entry, not
+here.
+
+Each entry should say what the message actually means, so a reader can tell it apart from a
+genuinely similar-looking error, and name the wrong conclusion people draw from it where there is a
+common one.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md b/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
new file mode 100644
index 0000000..f361144
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
@@ -0,0 +1,61 @@
+# When to contact Contentstack Support
+
+Symptoms whose cause sits outside the user's application. Recognising one of these early is worth
+more than any fix, because the alternative is a long debugging session in code that was never the
+problem.
+
+For each, the job is to confirm the identifying evidence, say plainly that this is not something
+they can fix in their own code, give the workaround if one exists, and tell them to open a ticket
+with Contentstack Support.
+
+## Provisioning and configuration, needs a support action
+
+| Symptom | What it actually is |
+|---|---|
+| The Visual Experience or builder-mode option is absent from navigation | The plan or org flag was never enabled for that stack. |
+| Custom Preview URLs or Open in New Tab are unavailable | Both are plan-gated. |
+
+## Not Contentstack at all
+
+| Symptom | What it actually is |
+|---|---|
+| A previously working `localhost` preview stops working, console shows a local network access error | Chrome's Local Network Access policy now blocks the app origin from framing localhost. Only the user can grant the permission, in the browser. |
+| Preview pane blank, and the site sits behind platform password protection or third-party SSO | Those screens set `X-Frame-Options: DENY` on themselves. Contentstack cannot inject headers into a browser-originated iframe request. Workarounds, cheapest first: enable **Open in New Tab**, which renders the site outside the iframe so frame headers stop applying; otherwise disable protection on the preview deployment, put a bypass token in the Base URL, or front it with a server-side proxy that strips the header. |
+| Ad slots, consent widgets, or other host-dependent third-party scripts misbehave in the pane | Those scripts key off the top-level origin, which is the Contentstack app inside an iframe. Expected, not a preview defect. |
+
+## How to hand it over
+
+State which category it falls into, quote the evidence that identifies it, and give the workaround
+if there is one. Then tell the user to raise it with Contentstack Support — as a next step for them,
+not as something happening behind the scenes. Nothing is routed anywhere on their behalf.
+
+
+### Produce a handover note
+
+Write the note below for the user to paste into the ticket. Fill it from what the protocol already
+collected in steps 1–6; do not start a new round of questions to complete it. Leave a field as
+"not checked" rather than guessing — an honest gap is more useful to the engineer than a filled-in
+assumption. Keep it to the fields; a Support or Product Engineer wants the facts, not the narrative.
+
+| Field | Value |
+|---|---|
+| Product | Live Preview / Visual Editor / Timeline |
+| Stack API key | `<api_key>` |
+| Environment / locale | `<environment>` / `<locale>` |
+| Branch or alias | only if not `main` |
+| Onboarding Check | exact card text shown, or "Setup Complete", or "card does not appear" |
+| Framework | name and major version; App Router or Pages Router where relevant |
+| Rendering mode | CSR / SSR / SSG / ISR / edge — for the affected route |
+| Fetch layer | Delivery SDK / REST / GraphQL / BFF, middleware or proxy |
+| SDK versions | `live-preview-utils x.y.z`, `delivery-sdk x.y.z` |
+| Scope | one user or everyone; localhost, deployed or both; consistent or intermittent |
+| Started after | new setup (never worked) / release / dependency bump / settings change / role change / nothing known |
+| Failing request | `METHOD host/path → status` — URL redacted, no tokens |
+| Console or server log | one-line excerpt, redacted |
+| Ruled out | contracts verified and how, e.g. "tracker POST 200; `data-cslp` present; requests hit the preview host" |
+| Suspected category | provisioning / plan gating / browser policy / other |
+| Workaround applied | what, or "none" |
+
+**Redact before sending.** Never include delivery tokens, preview tokens, management tokens, live
+preview hashes, cookies, or auth headers. The stack API key and environment name are fine and are
+what Support needs to find the stack.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
new file mode 100644
index 0000000..8109e83
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -0,0 +1,161 @@
+# Preview runtime FAQ
+
+Content correctness once the integration is confirmed wired up: staleness, lost preview context,
+caching, locale, variants, and Timeline.
+
+If the integration itself is not confirmed, work the four setup contracts in SKILL.md first. A
+fetch that never switched to the Preview Service produces most of the symptoms below and none of
+the fixes here will help.
+
+### variant-or-audience-switch-shows-base-entry
+- **bucket**: preview-runtime
+- **symptom**: Selecting a variant (or switching audience in Audience Preview) in Visual Experience keeps rendering the base entry. The side form shows the correct variant content, but the canvas does not. A manual browser refresh sometimes fixes it. Clicking into the element shows the correct variant value while the rendered page does not.
+- **frameworks**: Next.js, React, framework-agnostic
+- **rendering_modes**: CSR | SSR
+- **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-setup.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the parent Contentstack UI fetches the entry separately over the Management service. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
+- **fix**:
+  1. First confirm the preview path works at all: change a plain text field and check the canvas updates. If it does not, fix that first — the variant symptom is downstream of it.
+  2. Do **not** try to pass the variant yourself. The Preview Service resolves the variant from the UI selection; no extra `variant` query param is needed. `include_applied_variants=true` only adds metadata to the response body.
+  3. Confirm the Preview Service is actually configured: a preview token on the Stack's `live_preview` config, and content requests going to a `*-preview.contentstack.com` host during the session. This is the most common cause.
+  4. Register `ContentstackLivePreview.onEntryChange(fetchFn)` and make `fetchFn` re-query through the preview-configured Stack. This is the second most common cause. Confirm `ssr` matches the route's actual rendering mode while you are there.
+  5. Check the cache layer. If preview responses are cached under a key that ignores the `live_preview` hash, the base content is served no matter what. Bypass caching entirely for preview requests.
+  6. Variants on referenced entries: the referenced content type must be linked to the variant group for its variant content to resolve in preview, and that reference field must be in the `includeReference()` / `referenceFieldPath` list used for the page.
+  7. If a cache sits in front, it must not serve one variant's response for another. Do not key it by variant — bypass it for preview requests entirely.
+- **verification**: Switch variants; the network tab should show a fresh request to the preview host, and the rendered canvas should change without a manual refresh.
+
+---
+
+### cached-response-serves-stale-preview
+- **bucket**: preview-runtime
+- **symptom**: Preview works on localhost but not on a deployed environment with identical code and config — the setup status can even show "Setup Completed" and every edit return `{"notice":"Live Preview entry updated successfully."}` while the rendered page never changes. Or preview stops updating and only recovers in an incognito window or after a hard reload.
+- **frameworks**: Next.js, framework-agnostic
+- **rendering_modes**: SSR | SSG/ISR | edge
+- **root_cause**: A cache sits between the browser and the preview service. Whether or not its key includes the `live_preview` hash, preview requests get a stored payload instead of a live one. Seen with a customer CDN in front of the deployed environment, with an app-level fetch cache, and (on the Contentstack side) with stale JS bundles cached in the browser or CDN after a release. The Contentstack SDKs' own cache policies (`IGNORE_CACHE`, `CACHE_THEN_NETWORK`, `CACHE_ELSE_NETWORK`, `NETWORK_ELSE_CACHE`) do **not** switch themselves off for Live Preview — they cache regardless of the preview config.
+- **fix**:
+  1. Bypass every cache layer when a `live_preview` hash is present: no CDN caching of the preview host or the preview route, `cache: 'no-store'` on the fetch. If the app opted into SDK-level caching, also set `Policy.IGNORE_CACHE` in `cacheOptions` — but `cacheOptions` is optional and unset by default, so most apps have no SDK cache to disable and can skip this.
+  2. Do not cache preview responses at all, under any key. The `live_preview` hash identifies the preview **session**, not the content version, so it stays the same across every edit in that session. Keying a cache on it means the first response is served for the rest of the session and the canvas silently stops updating. There is no cache key that makes preview responses safe to cache — use the preview parameters to *bypass* the cache, never to key it.
+  3. Exclude the preview environment's base URL from the CDN entirely — the preview service cannot be cached at origin either, which is also why preview responses are measurably slower than CDN delivery (roughly 1s vs 100ms in one measured case). That gap is expected.
+- **verification**: Compare response headers on the preview request for cache hits. Reproduce in a private window; if the private window works and the normal one does not, it is a cache.
+
+---
+
+### locale-fallback-blank-or-wrong-locale-in-preview
+- **bucket**: preview-runtime
+- **symptom**: A page that renders fine in the entry editor and on the live site comes back blank in Visual Experience for a non-master locale. Or preview opens with a locale that does not exist in the stack (e.g. `en-us` on a stack that only has `fr-fr`) and 404s. Or one modular block referencing another entry renders empty in an unlocalized locale.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: CSR | SSR | SSG/ISR
+- **root_cause**: The Delivery API falls back to the master locale automatically; the Preview service does not. If the request to the preview service omits `include_fallback=true` (REST) or `fallback_locale: true` (GraphQL), an unlocalized entry — including an unlocalized *referenced* entry inside a modular block — returns nothing and the page renders empty. Separately, Visual Experience needs a base URL configured per locale in the environment; a locale with no base URL cannot load an iframe, and the preview URL falls back to a default locale that may not exist in the stack.
+- **fix**:
+  1. Add `include_fallback=true` (REST) / `fallback_locale: true` (GraphQL) to every preview fetch, and to nested reference includes.
+  2. Configure a base URL for every locale you want to author in, under the environment's Live Preview settings. A missing URL for one locale can disable the whole environment selector for that locale.
+  3. If a shared/common locale has no public market URL, create a preview-only route for it — it does not need to be publicly reachable, only loadable in the iframe.
+  4. If you need 404s for unlocalized entries outside preview but fallback inside preview, branch on the presence of the `live_preview` hash rather than turning fallback on globally.
+- **verification**: Open the locale in Visual Experience; the entry renders with master-locale content. Check the preview request URL contains the fallback parameter.
+
+---
+
+### csr-edits-need-manual-refresh
+- **bucket**: preview-runtime
+- **symptom**: Edits only appear after manually reloading the preview. Or the preview flashes/reloads but keeps the old values. Or after navigating to a second page inside the preview, editing an entry refetches and re-renders the *first* page instead.
+- **frameworks**: React, Next.js, Angular, Nuxt, Express
+- **rendering_modes**: CSR | SSR
+- **root_cause**: Three variants. (a) `onEntryChange` is never registered, or is registered but its callback fetches from the delivery path. (b) `ssr` does not match the route. With `ssr: true` the page is reloaded on change, so the fresh hash arrives on a new server request; with `ssr: false` the SDK calls `onChange()` instead and expects the app to refetch. Set the wrong one and neither path runs: an SSR route with `ssr: false` waits for a refetch the app never does, and a CSR route with `ssr: true` waits for a reload that does not repopulate client state. (c) Stale closure: `onEntryChange` is registered once in an effect with `[]` dependencies, but the fetch callback closed over the pathname captured at mount, so after a client-side route change it refetches the original path.
+- **fix**:
+  1. CSR: `ContentstackLivePreview.onEntryChange(fetchContent)` where `fetchContent` re-queries through the preview-configured Stack. Use `onEntryChange(fn, { skipInitialRender: true })` — equivalent to the older `onLiveEdit` — if you do not want the initial call.
+  2. Read the current route inside the callback (from a ref or `window.location.pathname`), never from a value captured at mount.
+  3. SSR: set `ssr: true`. The page is then reloaded on change and picks up the new hash on the server request. You do not need to add a `router.refresh()` or any manual re-render.
+  4. Do not call `stack.livePreviewQuery()` on the client in CSR mode. The SDK owns the hash there; a manual call that resets `live_preview: ""` when the browser URL lacks the params will clobber it and the refetch silently returns published content.
+- **verification**: Type into a field; the canvas updates without touching the browser. Navigate to a second page inside the preview and edit again — the second page should update, not the first.
+
+---
+
+### spa-client-navigation-loses-preview-context
+- **bucket**: preview-runtime
+- **symptom**: Preview works on the entry's own URL, but navigating within the site inside the preview panel breaks it — "Page Not Found", "You are currently previewing a different webpage", or edits silently stop applying. The address bar in the preview panel briefly shows an internal route that does not match the entry's `url` before settling back. Back button and refresh behave inconsistently.
+- **frameworks**: React (react-router), Next.js App Router, framework-agnostic
+- **rendering_modes**: CSR | SSR
+- **root_cause**: The SDK keeps the preview params on the URL by one mechanism only: a click listener that finds the clicked `<a>` and rewrites its `href` to include `live_preview` before the browser follows it. It does not patch the History API, so any navigation that does not go through a real anchor href — `router.push()`, `useNavigate()`, `history.pushState` — carries no params and the preview context is lost. Framework `<Link>` components are the common trap: they render an `<a>`, so the href is rewritten, but the router calls `preventDefault()` and pushes its own URL, so the rewrite is never used. Separately, if the app's routing does not map 1:1 to the entry's `url` field, the preview URL that Contentstack constructs (environment base URL + entry `url`) points at a route that does not exist. App Router soft navigation also does not re-run server-side hash gating.
+- **fix**:
+  1. Preserve `live_preview`, `content_type_uid`, `entry_uid`, and `preview_timestamp` in the URL across programmatic navigations, or trigger a hard navigation inside the preview.
+  2. For routes that cannot be derived from the entry `url` field, enable **Custom Preview URLs** and then call `setPageContext({ entryUid, contentTypeUid })` on each page (Live Preview Utils v4.4.4+). The call only takes effect when Custom Preview URLs is configured and enabled on the plan; otherwise it is silently ignored and the editor keeps resolving by URL.
+  3. For non-trivial URL structures, configure **Custom Preview URLs** in Settings → Visual Experience → Preview URL with placeholders (e.g. `/blog/{{entry.category}}/{{entry.slug}}`) and base URL aliases.
+  4. Confirm every route allows iframe embedding, not just the root — an `X-Frame-Options` or CSP `frame-ancestors` header, or a hard redirect to a different host, on a deep route will break navigation inside the panel.
+- **verification**: Click through the site's own nav inside the preview panel; the URL keeps its preview params and edits still apply on the new page.
+
+---
+
+### hash-empty-outside-the-preview-iframe
+- **bucket**: preview-runtime
+- **symptom**: `ContentstackLivePreview.hash` logs as an empty string, so the code that gates on it never switches to the preview host. Or an external tool calling the preview API directly gets `Please provide live preview hash in request` (error_code 382).
+- **frameworks**: framework-agnostic
+- **rendering_modes**: CSR | SSR
+- **root_cause**: The hash identifies a temporary preview session created by the Contentstack application. It only exists when the page is loaded inside the Live Preview / Visual Experience context (via the URL param the parent injects, or via the postMessage handshake). Outside that context there is no session and the hash is legitimately empty. There is no public way to mint one from your own code.
+- **fix**:
+  1. Treat an empty hash as "not in preview" and fall back to the delivery host. This is the correct branch, not a bug.
+  2. If the hash is empty *while inside* the preview panel, the postMessage handshake did not complete: check that the page is actually in the iframe, that `clientUrlParams.host` points at the right region's application host, that `init()` runs client-side (in a `"use client"` component for App Router), and that the SDK version is current.
+  3. SSR: do not rely on `ContentstackLivePreview.hash` on the server. Read `live_preview` from the request query string instead.
+  4. For an internal tool that needs draft data outside a browser preview session, the hash cannot be generated externally — that use case is not supported over the public preview API.
+- **verification**: Log the hash from inside the preview panel and from a normal tab. It should be populated in the first and empty in the second.
+
+---
+
+### stale-first-fetch-when-editing-a-referenced-entry
+- **bucket**: preview-runtime
+- **symptom**: The very first `onEntryChange` fetch after opening the preview returns published data even though the entry was already modified. Every subsequent keystroke-triggered fetch returns the correct draft data.
+- **frameworks**: Next.js (Pages Router), GraphQL
+- **rendering_modes**: CSR (on an SSG/ISR site)
+- **root_cause**: Service-side. It reproduced only when the entry being edited is a **referenced** entry and the site fetches the **parent** entry through a reference connection — the first preview response did not yet include the referenced entry's draft state.
+- **fix**:
+  1. Confirm the shape: are you editing a child/referenced entry while the page queries the parent through a reference connection? If so this is the known case and was fixed service-side.
+  2. Confirm the first request really is going to the preview host (the Onboarding Check reports this too) before assuming this issue — a first request to the delivery host looks identical from the outside.
+  3. Update to a current Live Preview Utils version.
+- **verification**: Modify a referenced entry, open the preview fresh, and confirm the draft value is present on the first render with no keystroke.
+
+---
+
+### legacy-management-token-preview-breaks-on-references
+- **bucket**: preview-runtime
+- **symptom**: Live Preview works for top-level fields but an edit to an entry that is referenced inside another entry does not update. Setup status reports "Preview Service Not Enabled" even though Live Preview is on for the stack. Migrating to preview tokens returns `401 Unauthorized` on the first attempt.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: The older Live Preview implementation authenticated with a read-only Management Token against the CMA host. On that path the reference-resolution optimizations of the Preview service are not available, so edits inside references do not propagate. "Preview Service Not Enabled" is exactly this: the site is still fetching draft data over CMA rather than the Preview service.
+- **fix**:
+  1. Migrate to the Preview Service: generate a Preview Token tied to your Delivery Token and replace `management_token` with `preview_token` in `live_preview`, and point `host` at the region's preview host.
+  2. Remove the CMA host override and any `setHost` calls left over from the old setup.
+  3. If preview requests 401 after the swap, confirm the Preview Token is tied to the Delivery Token you are actually using and that the token is sent as the `preview_token` header (not `authorization`).
+  4. Minimum versions for Visual Editor: Live Preview Utils v3.0+, Delivery SDK v3.20.3+ (v4.4.4+ of Live Preview Utils if you use `setPageContext`).
+- **verification**: Setup status stops reporting "Preview Service Not Enabled"; edits to a referenced entry appear in the parent page's preview.
+
+---
+
+### preview-renders-empty-for-a-restricted-user
+- **bucket**: preview-runtime
+- **symptom**: One user sees an empty or partly empty page in Live Preview / Visual Editor while colleagues on the same stack see it fully, and the published site is fine for everybody. Missing pieces can be a region, a single field, an image, or a referenced entry. Related shapes: the environment dropdown reads "No environments available" for that user alone (the role has no read permission on any environment, so there is nothing to preview against), or preview logs show `422 "The Content Type '<uid>' was not found."` for their request only.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: **By design.** Preview runs as the signed-in user and applies that user's full ACL — content types, entries, fields, locales and assets alike. Anything the user cannot read comes back empty rather than as an error the site can see. Delivery behaves differently because it uses a delivery token and applies no ACL at all, which is why the published page looks fine. So the same page legitimately renders differently for two users, and that is not a defect. A role granting read on *entries* but not on the *content type* produces the confusing case where the entry opens in the editor but preview returns 422 for it.
+- **fix**:
+  1. **Handle missing data in the site's rendering.** This is the durable fix. Preview can return an absent field, an empty reference array, a null asset or an unresolved locale for a perfectly valid reason, so components must degrade instead of throwing or rendering a blank region. A site that assumes every field is present will look broken for every restricted user.
+  2. Reproduce as the reporting user. This never shows up on an admin session, so testing as an admin proves nothing.
+  3. If the user *should* have had access, pull the role with `GET /v3/stacks/roles/{role_uid}` and compare it against what the page actually reads: content types (including referenced ones), the specific fields, the locale, the asset folders, and read access to the preview environment.
+  4. Grant read on the content type itself, not only on its entries. Granting entry access alone leaves the 422 in place.
+  5. Do not work around it by granting broader edit rights. Read access on the environment and the content types is the correct fix.
+  6. After changing the role, have the user sign out and back in before retesting. Role changes do not always apply to an existing session.
+  7. **Everyone** seeing "No environments available", not just one user, is a different problem: a missing Base URL — see `environment-base-url-misconfigured-or-missing-for-a-locale` in `faq-setup.md`.
+- **verification**: The restricted user's preview renders without gaps or errors, showing graceful fallbacks where access is limited; no `422 Content Type ... not found` in their preview requests. The environment dropdown lists the preview environment for their role.
+
+---
+
+### third-party-scripts-misbehave-inside-the-preview-iframe
+- **bucket**: preview-runtime
+- **symptom**: Ad slots, consent widgets, or other host-dependent third-party scripts intermittently fail to render inside Live Preview while working on the live site. Preview pages become unusable for pre-flight QA of those integrations.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: The preview renders inside a cross-origin iframe. Third-party scripts whose targeting or delivery logic depends on the top-level host, referrer, or first-party storage see the iframe context instead of the real site and behave differently. Not a Contentstack request failure: the calls fire and fail at the third party's delivery stage. This is inherent to rendering the site in an iframe and there is no product-side fix for it.
+- **fix**:
+  1. Where the third party allows it, add the Contentstack app origin to its allowed-referrer or allowed-domain configuration.
+  2. Use **Open in New Tab**, which renders the preview outside the iframe so the third party sees the real host. This is an existing feature, not something to request.
+  3. Where neither is possible, exclude those third-party scripts when the preview parameters are present, so authors preview content without them rather than with a broken version of them.
+- **verification**: Use Open in New Tab rather than the preview panel and confirm the third-party content renders. That difference confirms the iframe context is the trigger.
+
+---
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
new file mode 100644
index 0000000..6886b7f
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
@@ -0,0 +1,377 @@
+# Setup FAQ
+
+Setup and first-integration failures, ordered by how often they come up in practice. Each entry
+gives the symptom as users actually report it, the mechanism behind it, the fix, and a
+verification step.
+
+Read this after localising the problem to one of the four contracts in the parent skill. The
+contract tells you which section to read; this file tells you what to do.
+
+### app-fetches-from-delivery-cdn-instead-of-preview-service
+- **bucket**: setup
+- **symptom**: Live Preview / Visual Editor loads the site fine, but edits made in the entry form or the right-hand panel never appear in the preview. Content only changes after the entry is published. The Onboarding Check gets past the site-loading and SDK gates and then stops on **Preview Service Not Enabled**. Variant selection in Visual Editor also shows the base entry.
+- **frameworks**: Next.js (Pages + App Router), React, Angular, Gatsby, Vue/Nuxt, Java/Spring, framework-agnostic REST/GraphQL clients
+- **rendering_modes**: any
+- **root_cause**: The site is still calling the Content Delivery host (`cdn.contentstack.io` / `graphql.contentstack.com`) for its content. The `live_preview` hash reaches the page in the URL, but nothing in the fetch layer switches host + headers to the Preview Service, so the API returns published content. Most common with hand-rolled fetch wrappers, a BFF/middleware layer, GraphQL clients, or a separate fetch helper that bypasses the initialized Delivery SDK instance.
+- **fix**:
+  1. Generate a Preview Token against the Delivery Token you already use (Settings → Tokens → your Delivery Token → Preview Token), and enable Live Preview on the stack with a default preview environment.
+  2. If you use the Contentstack Delivery SDK: pass the same initialized Stack instance to every content fetch, and give it `live_preview: { enable: true, preview_token: <TOKEN>, host: <region preview host> }`. Do not create a second Stack instance just for `ContentstackLivePreview.init()`.
+  3. If you fetch over raw REST/GraphQL: branch on the hash before every request.
+     ```js
+     // SSR: read it off the request. CSR: use ContentstackLivePreview.hash
+     const livePreviewHash = request.query.live_preview;
+     if (livePreviewHash) {
+       headers.append("live_preview", livePreviewHash);
+       headers.append("preview_token", CONTENTSTACK_PREVIEW_TOKEN);
+       url.hostname = LIVE_PREVIEW_HOST; // e.g. rest-preview.contentstack.com
+     } else {
+       url.hostname = CONTENTSTACK_CDN_HOST; // e.g. cdn.contentstack.io
+     }
+     ```
+     For GraphQL the equivalent is swapping `graphql.contentstack.com` → `graphql-preview.contentstack.com` and adding the same two headers.
+  4. Bypass any cache layer for preview requests. Do not try to fix it with a smarter cache key: the hash is stable for the whole preview session, so any cache on this path serves the first response for the rest of it.
+- **verification**: Open the entry in Live Preview, then in DevTools → Network confirm requests go to the `*-preview.contentstack.com` host, carry `preview_token` and `live_preview` headers, and return 200. Edit a field without saving; the preview must update. The Onboarding Check should reach **Setup Complete**.
+
+---
+
+### iframe-blocked-by-x-frame-options-or-csp-frame-ancestors
+- **bucket**: setup
+- **symptom**: The Live Preview / Visual Editor pane is blank or shows "`<your-host>` refused to connect". Console shows `Refused to display '<url>' in a frame because it set 'X-Frame-Options' to 'sameorigin'` (or `deny`), or a `frame-ancestors` CSP violation. Frequently paired with a `401` on a `HEAD`/`GET` of the site root. Works on localhost, fails on the deployed dev/QA/staging host.
+- **frameworks**: framework-agnostic (server / CDN / hosting-platform header config)
+- **rendering_modes**: any
+- **root_cause**: Contentstack renders the site inside an iframe on the app origin. Any `X-Frame-Options: SAMEORIGIN|DENY` or a CSP `frame-ancestors` directive that does not include the Contentstack app origin makes the browser refuse the frame before the page can run. Platform-level deployment protection (for example a hosting provider's password protection) adds `X-Frame-Options: DENY` to the password screen itself, so even the auth prompt cannot render.
+- **fix**:
+  1. Remove `X-Frame-Options` for the preview host and use CSP instead: `Content-Security-Policy: frame-ancestors 'self' https://*.contentstack.com https://*.contentstack.io;` (`X-Frame-Options` has no allowlist syntax; a bare `SAMEORIGIN` always wins).
+  2. Apply the header on every route, not just the site root. A route that redirects to a different hostname than the configured Base URL will also fail.
+  3. If the deployment sits behind platform password protection, note that no header or query parameter can be injected into a browser-originated iframe request from Contentstack. Options: disable protection on the preview deployment, use a bypass token embedded in the Base URL, put a server-side proxy in front that injects the header, or use Live Preview → Open in New Tab (a plan-gated feature that renders outside the iframe).
+  4. Third-party SSO screens that themselves set `X-Frame-Options: DENY` cannot render in the iframe at all. Use Open in New Tab, which renders the preview outside the iframe so those screens can load.
+- **verification**: `curl -I https://<preview-host>/<some-deep-route>` and confirm no `X-Frame-Options` and a `frame-ancestors` value that includes the Contentstack app origin. Reload Live Preview; the pane should render.
+
+---
+
+### error-382-create-tracker-before-starting-live-preview-session
+- **bucket**: setup
+- **symptom**: Preview API requests fail with
+  `{"error_message":"Please create tracker before starting live preview session","error_code":382,"status":400}`
+  (a sibling variant is `{"error_message":"Please provide live preview hash in request","error_code":382}`). Often appears the moment `mode: "builder"` is set, or when the site is opened directly rather than from inside the Contentstack preview pane. Sometimes reproduces for one developer and not another on "identical" setups.
+- **frameworks**: Next.js, React, framework-agnostic REST/GraphQL clients
+- **rendering_modes**: CSR, SSR
+- **root_cause**: The `live_preview` hash sent on the request has no matching tracker document. Contentstack creates that tracker with a `POST /live-preview/tracker` when the preview session starts inside the CMS. The error means either (a) the app sent a hardcoded, stale, or hand-invented hash, (b) the app sent `live_preview=true` or an empty value instead of the real hash, or (c) the request was made outside any preview session (the site opened directly, or a custom preview tool that has no way to obtain a hash).
+- **fix**:
+  1. Never hardcode or invent a hash. Read it from `?live_preview=` on the request (SSR) or from `ContentstackLivePreview.hash` (CSR), and skip the preview host entirely when it is absent.
+  2. Confirm the tracker call fires: in DevTools → Network, look for `POST /live-preview/tracker` returning 2xx when the preview pane loads. If it never fires, the SDK did not initialize (check `enable`, the `.env` value actually parsing as `true`, and that `init()` runs on the client).
+  3. If the app proxies Contentstack through its own backend, forward the hash end to end. The front end must pass the hash it received to the backend, and the backend must put it in the `live_preview` header.
+  4. Building a preview tool entirely outside Contentstack is not supported with a Preview Token alone; the hash originates in the CMS session. Use a dedicated publishing environment for an internal preview tool instead.
+- **verification**: With the entry open in Live Preview, the network log shows a successful tracker POST followed by preview reads returning 200 with the same hash value.
+
+---
+
+### edit-tags-not-generated-or-not-spread
+- **bucket**: setup
+- **symptom**: Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar. Clicking the canvas does nothing, or selects the wrong (parent) element. `entry.$` / `post.$` is `undefined` in the app, or `data-cslp` renders as literal text instead of an attribute. Live Preview auto-refresh often still works, which makes it look like a Visual Editor bug.
+- **frameworks**: React, Next.js, Vue, Angular, Gatsby, Blazor/.NET, jQuery
+- **rendering_modes**: any
+- **root_cause**: Tags need two independent things and teams usually do only one: `addEditableTags()` must run on every fetched entry, **and** the generated `$` attributes must be spread onto the DOM elements that render each field. `mode: "builder"` does not generate tags — it only controls where **Start Editing** redirects. Four ways this goes wrong: the call is missing entirely (commonly commented out during a migration); `tagsAsObject` is `false` or omitted, producing a `data-cslp` string React cannot spread; the content type **title** is passed instead of its **uid**; or the call is correct but nothing spreads the result into the markup.
+- **fix**:
+  1. Call it on every entry right after fetching, including referenced entries: `addEditableTags(entry, contentTypeUid, true, locale)`. The third argument must be `true` for React and JSX.
+  2. Pass the content type **uid**, not its display title.
+  3. Spread onto the element that renders the value: `<h1 {...post.$?.title}>{post.title}</h1>`.
+  4. Mirror the data path exactly. References come back as arrays, so it is `post.author[0].$?.name`, not `post.$?.author.name`.
+  5. Tag the leaf element that holds the value, one `data-cslp` per element. Tagging a wrapper group instead of the field makes Visual Editor select the wrong field.
+  6. Check nothing strips them at build time: `cleanCslpOnProduction: true` removes `data-cslp` from the DOM, and `PURGE_PREVIEW_SDK=true` no-ops the whole SDK.
+  7. For GraphQL, the response shape itself breaks tag paths — see `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md` for the normalizer that has to run before `addEditableTags()`.
+  8. If you only want auto-refresh and not in-context editing, use `mode: "preview"` rather than `mode: "builder"` with no tags.
+- **verification**: In DevTools on the previewed page, `document.querySelectorAll('[data-cslp]').length` must be greater than 0, and a rendered field must carry `data-cslp="<content_type_uid>.<entry_uid>.<locale>.<field_path>"`. Hovering it in the canvas should highlight it, and clicking should focus the matching field in the form panel.
+
+---
+
+### preview-url-does-not-resolve-to-the-app-route
+- **bucket**: setup
+- **symptom**: Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited. Navigating inside the preview 404s. Sometimes the pane says "You are currently previewing a different webpage". Affects entries whose real URL is nested, taxonomy-driven, multi-tenant, or has no `url` field at all.
+- **frameworks**: Next.js, React, framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: By default the preview URL is `environment Base URL` + the entry's `url` field. That only works when app routing maps 1:1 to the `url` field. Nested paths, custom route prefixes, several content types with different URL shapes, multiple sites served from one stack, or a URL stored in a custom text field instead of the built-in `url` field all break the concatenation.
+- **fix**:
+  1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL) with pattern placeholders such as `/blog/{{entry.category}}/{{entry.slug}}`, plus Base URL aliases when several hostnames map to one stack. This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated and has to be enabled on the account.
+  2. With Custom Preview URLs enabled, tell the editor which entry each page is by calling `setPageContext({ entryUid, contentTypeUid })` on every page (Live Preview Utils v4.4.4+). Fallbacks: the `window.__CS_PAGE_CONTEXT__` global, or `<meta name="contentstack:entry-uid">` and `<meta name="contentstack:content-type-uid">`. **This only has an effect when Custom Preview URLs is configured and enabled on the plan.** Without it the editor resolves by URL alone and the call is silently ignored — it does not error, so a missing feature flag looks like `setPageContext` not working.
+  3. Do not narrow the environment Base URL to one content type's prefix (for example `.../inspiration/articles/`) — that fixes one content type and breaks all others.
+  4. Verify the entry's `url` field actually corresponds to a route the app serves, and that the route renders the content type you expect.
+- **verification**: Open entries from several content types (root page, nested page, no-URL page). Each should load its own page in the preview pane, and the URL bar in the pane should show the real route.
+
+---
+
+### sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade
+- **bucket**: setup
+- **symptom**: Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump breaks a previously working integration — `setConfigFromParams` disappears, `ReferenceError: window is not defined` in server code, the Edit button suddenly renders in production, or `Live_Preview_SDK: To use edit tags, you must provide the stack API key`.
+- **frameworks**: Next.js, React, Gatsby, Angular
+- **rendering_modes**: any
+- **root_cause**: Feature availability is version-gated and majors carry breaking changes that were not always documented. Pinned-old dependency policies (auto-update disabled) leave teams on v1.x where the required callbacks do not exist. The v2 → v3 jump removed `setConfigFromParams` (its replacement reads `window`, which throws in SSR) and made `stackDetails.apiKey` mandatory for edit tags.
+- **fix**:
+  1. Meet the minimums: Live Preview Utils **v3.0+** and Delivery SDK **v3.20.3+** for Visual Editor; **v4.4.4+** if you use `setPageContext()`.
+  2. Pass `stackDetails: { apiKey, environment }` explicitly in `init()` — v2+ no longer derives the API key from the Stack object for edit tags.
+  3. In SSR, stop calling `setConfigFromParams`. Read the query parameters from the request and apply them with `livePreviewQuery()` instead of relying on any SDK helper that touches `window`.
+  4. Pin one delivery method for the SDK. Mixing an npm install with an ESM/CDN `<script type="module">` import of a different version produces version-specific behaviour differences (for example the Edit button appearing after a CDN bump).
+  5. Read the SDK release notes before a major bump rather than the setup docs alone.
+- **verification**: `npm ls @contentstack/live-preview-utils @contentstack/delivery-sdk` (or `contentstack`) shows versions at or above the minimums, and only one copy of the preview SDK is loaded in the page.
+
+---
+
+### environment-base-url-misconfigured-or-missing-for-a-locale
+- **bucket**: setup
+- **symptom**: The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wrong path or the site root; a specific locale cannot be previewed at all while others work; the preview pane keeps showing the previous environment's URL after switching.
+- **frameworks**: framework-agnostic (stack configuration)
+- **rendering_modes**: any
+- **root_cause**: Live Preview builds the iframe URL from the environment's Base URL for the entry's locale. If any environment is missing a Base URL for that locale, the whole selector can be disabled for the locale. A Base URL missing its locale segment (for example `https://host` instead of `https://host/en`) resolves to the wrong page. A Base URL without a scheme (`localhost:3001` instead of `http://localhost:3001`) silently fails. Locales with no configured Base URL are not supported in Visual Editor at all.
+- **fix**:
+  1. Settings → Environments: set a Base URL for **every** environment/locale pair you intend to preview, including the locale path segment where the app uses one.
+  2. Always include the scheme (`http://` or `https://`).
+  3. For a locale that only exists via fallback, either add a Base URL that resolves fallback content (and add `include_fallback=true` on your queries) or accept that Visual Editor cannot render it.
+  4. Environment publish permissions affect which Base URLs a role can select; a restricted user can still preview by typing the correct Base URL into the Live Preview URL bar.
+  5. If **only one user** sees "No environments available" while colleagues do not, it is not the Base URL — that user's role has no read permission on any environment. See `preview-renders-empty-for-a-restricted-user` in `faq-preview-runtime.md`.
+- **verification**: For each locale, open the Live Preview environment dropdown — every environment should be selectable and the resolved URL should load the correct localized page.
+
+---
+
+### edit-button-rendered-outside-a-live-preview-session
+- **bucket**: setup
+- **symptom**: The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or the `#cslp-tooltip` button element is injected into `document.body` on production even when not visible (usually caught in an accessibility audit). Sometimes intermittent, correlating with client-side route changes rather than fresh page loads.
+- **frameworks**: Next.js (App Router especially), React
+- **rendering_modes**: CSR, SSR
+- **root_cause**: With `editButton.enable: true`, the SDK gates the button on `enable` + `inIframe()` + the `cslp-buttons` query parameter. It never checks the `live_preview` hash or any active-session signal, so a normally loaded page with the SDK initialized renders the button by design. Teams that gate `init()` on a server-read hash also get bitten by App Router soft navigation, which does not re-run that server-side gate while the SDK's button instance persists across route changes.
+- **fix**:
+  1. Add `editButton: { enable: true, exclude: ['outsideLivePreviewPortal'] }`. Outside the iframe `inIframe()` is false, so the button will not render, while Live Preview inside the pane keeps working.
+  2. If Live Preview is not used on production at all, strip it from the production build: `cleanCslpOnProduction: true` removes `data-cslp` from the DOM, and the `PURGE_PREVIEW_SDK=true` build flag no-ops the SDK entirely.
+  3. Do not rely on a server-side hash check alone in an App Router app; soft navigation will not re-evaluate it.
+- **verification**: Load the production URL in a normal tab with DevTools open. `document.getElementById('cslp-tooltip')` should be absent, and no `data-cslp` attributes should be present if `cleanCslpOnProduction` is set.
+
+---
+
+### cors-blocked-on-preview-api-requests
+- **bucket**: setup
+- **symptom**: `Access to fetch at 'https://<region>-rest-preview.contentstack.com/v3/...' from origin '<site origin>' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource`, frequently alongside a `401 (Unauthorized)` on the same request. Works on localhost, fails on the deployed dev/staging host.
+- **frameworks**: Gatsby, Angular, Next.js, React
+- **rendering_modes**: CSR mainly
+- **root_cause**: Two distinct problems that surface as one console message. (1) The site's own Content Security Policy (`connect-src` / `default-src`) does not allow calls to Contentstack hosts, which most frameworks restrict by default in production but not in local dev. (2) The preview request is genuinely rejected (bad or wrong-type token), and the error response carries no CORS headers, so the browser reports it as a CORS failure instead of a 401. There is no per-stack "CORS allowlist" on the Contentstack side to add origins to.
+- **fix**:
+  1. Widen the site's CSP to the whole Contentstack domain rather than individual hosts. Listing only `app.contentstack.com` and `rest-preview.contentstack.com` has repeatedly been insufficient; `https://*.contentstack.com` (and `https://*.contentstack.io` where delivery/asset hosts are used) is what worked.
+  2. Fix the 401 separately: confirm you are sending a valid **Preview Token** (not a Delivery Token, not a Management Token) in the `preview_token` header, and regenerate it if in doubt. Resolve the CSP first, or the server error stays masked.
+  3. Recheck env vars after a stack migration or API key change — a stale API key produces the same 401-behind-CORS shape.
+- **verification**: `curl` the same preview URL with the same headers from a terminal. A 200 proves the token is valid and the remaining problem is browser-side CSP. In the browser, the request should complete with `Access-Control-Allow-Origin` present.
+
+---
+
+### ssr-stack-instance-shared-or-duplicated
+- **bucket**: setup
+- **symptom**: Two opposite failures from the same mistake. **(A) Hash never arrives:** `init()` succeeds and `ContentstackLivePreview.hash` is populated on the client, but server-rendered pages still return published content. Deterministic, and only the author notices. **(B) Preview state leaks out:** intermittent, user-dependent wrong content, and the **production** site failing with `The Live Preview tracker is invalid or no longer exists. Create a new tracker to continue.` (error_code 382) or `The requested tracker was created for the 'dev' branch. Access using the 'main' branch is not allowed.`; preview stalling after a while; `TypeError: Cannot read properties of undefined (reading 'uid')` after idle hours in production; two editors seeing each other's content; personalization on the public site stopping resolving per visitor because a cached preview render is being served instead. This one reaches real visitors.
+- **frameworks**: Next.js (App Router and Pages Router), Express/Node, Nuxt
+- **rendering_modes**: SSR | edge
+- **root_cause**: In SSR the SDK does not fetch content. It puts `?live_preview=<hash>&content_type_uid=...&entry_uid=...` on the URL and reloads, and preview state lives **on the Stack instance**. Failure (A) is having two instances: a long-lived "default" Stack for page queries plus a second Stack passed only to `init()`, so the hash never lands on the instance that queries. Failure (B) is having one module-level instance shared across requests: once any request puts it into preview mode, unrelated requests inherit it, and ordinary delivery traffic starts hitting the preview service with a hash that has expired (the tracker lasts about a day; the session hash rotates roughly every 30 minutes) or belongs to another branch. Under concurrency requests can also overwrite each other's config mid-flight.
+- **fix**:
+  1. Create a fresh Delivery SDK instance **per request**. Do not share a module-level Stack, and pass the instance down through request-scoped context rather than importing a singleton. This one change fixes both failures.
+  2. Read the hash off the incoming request each time and apply it to that instance: `stack.livePreviewQuery({ live_preview: hash, contentTypeUid, entryUid })`.
+  3. Call `livePreviewQuery(...)` **unconditionally** per request, with empty values when there is no hash. Calling it only when a hash exists leaves the previous request's hash in place.
+  4. Run every query that should show drafts on that instance. A query on an un-hashed instance returns published content.
+  5. Drop any separate "live preview only" Stack. `init()` does not need a Stack in SSR.
+  6. Never reuse a hash captured in a preview session on a normal page load, and never hardcode or persist one. Keep the branch consistent: a tracker created against one branch cannot be used against another.
+  7. Ignore `No ack listener found` / `NO_REQUEST_LISTENER_FOUND` here. Routine postMessage chatter that appears on working setups; it does not affect SSR content.
+- **verification**: Log the hash on the server per request and confirm it is non-empty and changes per session, and that preview requests hit the preview host. Editing a field without saving should change the SSR output on reload. Then load the production URL directly on a cold server and confirm requests go to the CDN host with no `live_preview` header, and that mixed preview / non-preview traffic does not contaminate either side.
+
+---
+
+### nextjs-app-router-init-must-run-in-a-client-component
+- **bucket**: setup
+- **symptom**: In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit tags render but do nothing, or nothing at all happens when the entry is edited. The same code works in a Pages Router project.
+- **frameworks**: Next.js App Router
+- **rendering_modes**: SSR, CSR
+- **root_cause**: `ContentstackLivePreview.init()` has to run in the browser. In App Router, code placed in a server component or in the root layout module body never executes client-side, so the SDK never installs its postMessage listeners and never advertises SSR mode.
+- **fix**:
+  1. Create a dedicated client component and call `init()` from an effect:
+     ```tsx
+     "use client";
+     import ContentstackLivePreview from "@contentstack/live-preview-utils";
+     import { useEffect } from "react";
+     export default function LivePreviewClient() {
+       useEffect(() => { ContentstackLivePreview.init({ /* ... */ }); }, []);
+       return null;
+     }
+     ```
+  2. Render that component from the root layout.
+  3. On the server side, read `live_preview`, `content_type_uid`, and `entry_uid` from `searchParams` (or from request headers set in middleware) and apply them with `livePreviewQuery()` per request. Do not expect the client SDK to hand the hash to server code.
+  4. Keep the SDK init code in its own module so re-renders do not reset the configuration.
+- **verification**: With the entry open in Live Preview, the iframe URL contains `?live_preview=...`, the console reports SSR mode where applicable, and the server sees the hash on each request.
+
+---
+
+### legacy-management-token-setup-not-migrated-to-preview-token
+- **bucket**: setup
+- **symptom**: "Preview Service Not Enabled" shows in the preview panel on a setup that otherwise works. Or a setup copied from older docs / an older starter app passes a `management_token` to `live_preview` and fails with 401/422 after tokens were rotated.
+- **frameworks**: Next.js, Gatsby, React, framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: The original Live Preview implementation read drafts through the CMA using a read-only Management Token. That was replaced by the Preview Service and a read-only Preview Token issued against a Delivery Token. Applications left on the legacy path still work but are flagged, and older starter apps / source plugins shipped `management_token` in the `live_preview` config long after the docs switched to `preview_token`.
+- **fix**:
+  1. Generate a Preview Token on the Delivery Token you already use.
+  2. Replace `live_preview.management_token` with `live_preview.preview_token` and point `live_preview.host` at the region's `*-rest-preview.contentstack.com`.
+  3. Update any framework source plugin to a version whose build output actually reads `preview_token` (some releases had source and build output disagreeing).
+  4. Remove the Management Token from client-side code entirely. Stack API Key, Delivery Token, and Preview Token are read-only and safe to ship to the browser; a Management Token has write access and is not.
+- **verification**: No Management Token appears in any client bundle or preview request; the "Preview Service Not Enabled" card is gone and the Onboarding Check reaches Setup Complete.
+
+---
+
+### branch-or-alias-mismatch-between-app-token-and-entry
+- **bucket**: setup
+- **symptom**: Preview opens for pages that already exist on the main branch but never shows updates, and any page that exists only on the working branch 404s. Or: `error_code: 901, "Access denied. You have insufficient permissions to perform operation on this branch"`.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: Two misalignments. The deployed preview site is pinned to one branch (often a production replica on `main`) while the author edits on another. Or the Delivery/Preview Token scope does not include the branch or alias being previewed, which surfaces as the 901. Aliases themselves resolve to their target branch correctly, so an alias in the URL is not a cause.
+- **fix**:
+  1. Make the branch the app queries match the branch the entry is edited on — either configure a per-branch preview deployment or read the branch from the preview request and pass it as the `branch` header.
+  2. Extend the Delivery Token scope to include every branch **and** alias you preview against. Adding a branch to the scope after the fact is what cleared the 901.
+  3. Aliases are fine to use in preview URLs. If you scope a token to an alias, confirm the alias points at the branch you think it does, since repointing an alias silently changes what preview reads.
+- **verification**: Edit an entry that exists only on the non-main branch; it should load and update in the preview. Preview requests should carry the expected `branch` header and return 200.
+
+---
+
+### wrong-region-hosts-in-sdk-and-preview-config
+- **bucket**: setup
+- **symptom**: Live Preview never activates or the preview panel reports the service is not enabled, even though the stack settings look correct. Requests in the network tab go to the default North America hosts while the stack lives in another region.
+- **frameworks**: Next.js, Angular, React
+- **rendering_modes**: any
+- **root_cause**: Region is not inferred. Each of the delivery host, preview host, API host, and app host has a region-specific name, and the SDK defaults to the AWS NA set. A stack in EU / Azure / GCP that is left on the defaults gets rejected or served from the wrong region.
+- **fix**:
+  1. Set every host explicitly and consistently for the stack's region. All four move together:
+     - delivery: `cdn.contentstack.io` → e.g. `eu-cdn.contentstack.com`, `azure-na-cdn.contentstack.com`, `gcp-eu-cdn.contentstack.com`
+     - preview: `rest-preview.contentstack.com` → e.g. `eu-rest-preview.contentstack.com`, `azure-na-rest-preview.contentstack.com`, `gcp-eu-rest-preview.contentstack.com`
+     - GraphQL preview: `graphql-preview.contentstack.com` → the region-prefixed equivalent
+     - app host (`clientUrlParams.host`): `app.contentstack.com` → e.g. `eu-app.contentstack.com`, `gcp-na-app.contentstack.com`
+  2. Use the SDK's `region` option where available rather than hand-writing hosts, and make sure a hardcoded `host` does not override it.
+  3. Re-check every host after a stack migration; the API key changes too.
+- **verification**: In DevTools → Network, every Contentstack request goes to a host carrying the correct region prefix, and returns 200.
+
+---
+
+### locale-defaults-to-en-us-in-init
+- **bucket**: setup
+- **symptom**: Start Editing / the Edit button opens Visual Editor or the entry editor with `locale=en-us` even though the stack has no `en-us` language, producing a 404 or a "Language not found" toast. Works on one deployment and not another with identical code.
+- **frameworks**: React, Angular, framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: When `stackDetails.locale` is not set in `init()`, the SDK tries to infer the locale by finding an element with `data-cslp` in the DOM and reading the locale out of it. If no tagged element is present at that moment, it falls back to `en-us`. That fallback is invalid on stacks whose master language is something else, and it explains why the same code behaves differently on two deployments (one happens to have tagged content in the DOM, the other does not).
+- **fix**:
+  1. Set the locale explicitly:
+     `ContentstackLivePreview.init({ stackDetails: { apiKey, environment, locale: '<your-locale>' } })`.
+  2. Also pass the locale to `addEditableTags(entry, contentTypeUid, true, locale)` so the generated `data-cslp` carries the right locale.
+  3. Do not add a dummy `en-us` language to the stack as a workaround.
+- **verification**: Click an edit tag; the URL that opens should carry your real locale, and the entry should load without a "Language not found" error.
+
+---
+
+### start-editing-button-cannot-be-hidden-in-editor-mode
+- **bucket**: setup
+- **symptom**: The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `mode: "builder"` is set, including production. Setting `editButton.enable: false` removes the per-field edit tags but not this button.
+- **frameworks**: React, Next.js, Gatsby
+- **rendering_modes**: any
+- **root_cause**: "Start Editing" is a separate control from the per-field edit tags. It is enabled implicitly by `mode: "builder"` and has its own config key, which was not obvious from the setup docs. `editButton` governs only the field-level tags.
+- **fix**:
+  1. Disable it explicitly:
+     ```js
+     ContentstackLivePreview.init({
+       mode: "builder",
+       editInVisualBuilderButton: { enable: false },
+     });
+     ```
+  2. Better for production builds: do not initialize the SDK there at all, or use `PURGE_PREVIEW_SDK=true` / `cleanCslpOnProduction: true`.
+- **verification**: Load the production URL; no floating Start Editing button. Load the preview environment; the button is present when you want it.
+
+---
+
+### onboarding-check-card-not-visible-or-appears-unexpectedly
+- **bucket**: setup
+- **symptom**: A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days later on its own. Conversely, other teams never see the status card at all when they want to diagnose a failing integration.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: Each product keeps its own stack setting, and they do not agree on what "unset" means. Timeline treats an unset value as visible. Live Preview treats an unset value as hidden. Visual Editor depends on whether its settings object exists at all. Meanwhile the Visual Experience settings screen renders the toggle as on whenever the value is unset, so a stack that never explicitly saved the setting can show the toggle on while Live Preview behaves as though it is off. Separately, the checks run asynchronously with a timeout, so the card can appear briefly on a correctly configured site whose first preview fetch is slow, then clear itself once the request lands.
+- **fix**:
+  1. Open Settings → Visual Experience and click Save without changing anything. The form always submits all three products' visibility keys, and an unset value arrives in the form as on, so a single save writes an explicit `true` for Live Preview, Visual Editor and Timeline at once. That removes the unset ambiguity and makes all three agree.
+  2. Check the setting for the product actually being used. Live Preview, Visual Editor and Timeline each have their own, under Settings → Visual Experience.
+  3. Read the one step the card shows. The gates run as an ordered chain that stops at the first failure, so the card names a single gate — that is the configuration gap, and every gate before it has already passed.
+  4. If it still does not appear for one user but does for others, that user dismissed it. The suppression is stored per stack in their browser, and no stack-level save clears it — they need to clear site data for the app origin, or use another browser profile.
+  5. If the card flashes then clears on a working site, no action is needed — the first preview request simply arrived after the check timeout.
+- **verification**: Open an entry in the product in question and confirm the status card appears. If it does not appear after saving the setting explicitly, it is being suppressed locally rather than by the stack setting.
+
+---
+
+### visual-experience-navigation-missing-for-the-stack
+- **bucket**: setup
+- **symptom**: The "Visual Experience" / builder-mode option does not appear in the Contentstack navigation at all, so the team cannot open the builder and assumes their integration is wrong.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: Entirely CMS-side. Three things gate the navigation entry: plan entitlement, organization-level enablement, and the stack's own Live Preview setting. **Nothing in the application affects it.** If the nav entry is absent, stop looking at the site: no SDK version, `init()` option, edit tag or fetch change can make it appear. Only the third of those is visible to the customer — plan entitlement and org enablement cannot be checked from the CMS UI.
+- **fix**:
+  1. Have the user check the one thing they can see: Live Preview enabled on the stack, under Settings → Visual Experience.
+  2. If that is on and the navigation entry is still missing, stop there and contact Contentstack Support. Whether the plan includes Visual Editor, and whether it is enabled for the organization, are not things the user can verify or change, so do not send them looking.
+- **verification**: The Visual Experience option appears in the entry's navigation. Only once it opens is there any point looking at the integration itself.
+
+---
+
+### third-party-cookies-blocked-inside-the-preview-iframe
+- **bucket**: setup
+- **symptom**: The site renders in the preview pane but behaves as if logged out, or without personalization, locale or currency preferences. Anything driven by the site's own cookies is lost.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: Inside the preview iframe the site is a third-party context relative to the Contentstack app origin, and browsers block third-party cookies by default. Only cookies set with `SameSite=None; Secure` survive, and that attribute deliberately weakens the protection that stops a cookie being sent from other sites.
+- **fix**:
+  1. **Start by asking whether the cookie matters here at all.** Preview is for reviewing content, not for exercising session state. Most sites do not need their cookies to render the page an author is checking, and the right outcome is usually that the site degrades gracefully in the iframe rather than that the cookie policy changes.
+  2. If the content genuinely cannot render without it, prefer an alternative to loosening cookies: drive the preference from a query parameter or header the preview URL can carry, or give preview a dedicated path that does not depend on the cookie.
+  3. Only if neither works, set `SameSite=None; Secure` — **and only on the preview deployment, never on production**. Scope it to the preview host so the production site keeps its stricter policy. Do not apply it site-wide to make preview convenient.
+  4. Cookie-gated content needs a preview-specific auth path regardless. The iframe cannot inherit the parent's session.
+- **verification**: The page renders in the intended state inside the preview iframe, and the production site's cookies still carry their original `SameSite` policy. Confirm the second part explicitly — this is the step most likely to be applied too broadly.
+
+---
+
+### chrome-local-network-access-blocks-preview-of-localhost
+- **bucket**: setup
+- **symptom**: A previously working local Live Preview setup breaks with
+  `Access to fetch at 'http://localhost:5173/' from origin 'https://<region>-app.contentstack.com' has been blocked by CORS policy: Permission was denied for this request to access the 'unknown' address space`.
+  Chrome only; Safari unaffected. Downgrading the SDK does not help.
+- **frameworks**: framework-agnostic (Vite, Next.js dev servers)
+- **rendering_modes**: any
+- **root_cause**: Chrome's Local Network Access / Private Network Access restriction. A public HTTPS origin (the Contentstack app) reaching a private or loopback address (`localhost`) now requires an explicit browser permission. Nothing changed in the SDK or in Contentstack.
+- **fix**:
+  1. Accept the Chrome "Local network access" permission prompt for the Contentstack app origin, or enable it manually in Chrome → Site settings for that origin.
+  2. If you would rather not ask every author to grant it, preview against a deployed HTTPS host instead of `localhost`.
+- **verification**: Reload Live Preview in Chrome; the `OPTIONS`/`GET` to the local dev server succeeds and the iframe renders.
+
+---
+
+### cslp-tags-contain-the-literal-string-undefined
+- **bucket**: setup
+- **symptom**: `data-cslp` attributes in the DOM contain `undefined` where the entry uid should be. Inline editing does not work and edit mapping silently fails on those elements.
+- **frameworks**: Next.js
+- **rendering_modes**: SSR
+- **root_cause**: `addEditableTags()` was called once with an array or collection of entries rather than with a single entry object. It reads `uid` off the object it is handed; an array has no `uid`, so every generated tag interpolates `undefined`.
+- **fix**:
+  1. Loop the result set and call the helper per entry:
+     ```
+     for (const entry of result) {
+       addEditableTags(entry, contentTypeUid, true, entry.locale);
+     }
+     ```
+  2. Pass each entry's own content type uid, not the page's, when the collection mixes content types.
+  3. Confirm the object you pass actually has a `uid` property; if your fetch layer strips system fields, restore them first.
+- **verification**: Search the rendered HTML for `cslp` and confirm no attribute value contains `undefined`.
+
+---
+
+### ssg-preview-needs-csr-mode
+- **bucket**: setup
+- **symptom**: Live Preview on a statically generated site is unreliable or simply shows build-time content: blank or black screens, flicker, an auth prompt on reload, or edits that never appear no matter what. The hash is on the URL and never reaches the fetch.
+- **frameworks**: Next.js, Gatsby, Astro, framework-agnostic
+- **rendering_modes**: SSG/ISR
+- **root_cause**: Two halves of the same mistake. A prerendered page cannot read query parameters at request time, so the `live_preview` hash can never reach a build-time data fetch — static output is published-only content by definition. And in SSR mode the SDK reloads the page after every edit, which on a static site just re-serves the same prerendered HTML. SSG is supported, but only in CSR mode.
+- **fix**:
+  1. Initialize with `ssr: false`. Edits then fire an `onEntryChange` callback instead of a page reload.
+  2. Pass `stackSdk` in the init config. It is mandatory in CSR mode, and it is also what the SDK uses to default `ssr`, so omitting it silently selects SSR behaviour.
+  3. Implement `onEntryChange`: subscribe on the client, refetch the entry, update the UI. No rebuild is needed.
+  4. Remove any `Stack.livePreviewQuery()` call from middleware. It is SSR-only and must not run on a static route.
+  5. If the site mixes static and server-rendered routes, make the mode conditional per route rather than per app.
+  6. If a route must stay server-rendered, make only the preview path dynamic: detect `live_preview` in `searchParams` and force that request dynamic. Do not combine a whole-route cache directive with a page that needs `searchParams` — split the condition at the fetch, not the route.
+- **verification**: Edit a field. The preview updates in place with no page reload, no flicker and no auth prompt, and the network tab shows a request to the preview host carrying the unsaved value.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
new file mode 100644
index 0000000..52e93ba
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
@@ -0,0 +1,39 @@
+# Timeline FAQ
+
+Timeline previews an entry at a point in time. It shares the Live Preview SDK and the same preview
+host, but it is a distinct product: it has its own Onboarding Check with three gates rather than
+five (see [onboarding-check.md](onboarding-check.md)), and it carries a `preview_timestamp` alongside the usual
+`live_preview` hash.
+
+If plain Live Preview does not work, fix that first — everything here assumes the preview path is
+already good.
+
+### timeline-preview-timestamp-ignored-or-dropped
+- **bucket**: preview-runtime
+- **symptom**: Timeline preview shows the wrong point in time — either the current version regardless of the date picked, or version 1 of the entry for every timestamp. Reference-field changes that render correctly on the live site, in Live Preview, and in Visual Editor do not show in Timeline. Clicking an internal link inside Timeline preview loses the timestamp and the page reloads twice.
+- **frameworks**: Next.js, React, framework-agnostic
+- **rendering_modes**: CSR | SSR
+- **root_cause**: Timeline adds `preview_timestamp` to the iframe URL alongside the `live_preview` hash, and the site must forward **both** to the preview service. Common failures: (a) the app only forwards the hash; (b) the app calls `stack.livePreviewQuery()` manually on the client and passes the hash without `preview_timestamp`, overwriting what the SDK had; (c) client-side internal navigation rewrites the iframe URL and drops the query params, so the next render has no timestamp (the double reload is Timeline re-injecting it); (d) a Timeline tracker is a different tracker type than a Visual Editor tracker, so a hash captured from one context does not work in the other.
+- **fix**:
+  1. On the server, read `preview_timestamp` from the request URL on every request and pass it with the hash: `stack.livePreviewQuery({ live_preview: hash, preview_timestamp: ts, content_type_uid, entry_uid })`.
+  2. On the client, prefer letting the SDK read the params from `document.location` — do not call `livePreviewQuery()` yourself. If you must, always include `preview_timestamp` next to the hash.
+  3. Preserve `live_preview` and `preview_timestamp` across client-side route changes, or force a full navigation inside preview. Use Timeline's URL navigation box rather than in-page link clicks when demoing.
+  4. Do not reuse a hash across contexts. A Timeline hash comes from the Timeline preview page's tracker call; a Visual Editor hash comes from Visual Editor.
+  5. Append the params correctly when the base URL already carries a query string, rather than overwriting the existing one.
+- **verification**: Pick a future scheduled-publish marker; the request to the preview host should carry both headers and the response `_version` should match the version expected at that timestamp.
+
+---
+
+### timeline-compare-highlights-no-differences
+- **bucket**: visual-editor
+- **symptom**: Timeline **Compare Website** renders both versions but highlights no differences between them.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: Highlight Differences works by matching changed fields to DOM elements through their `data-cslp` attributes. It needs live edit tags enabled on the site **and** a `data-cslp` physically present on the element that renders the changed field. Where the tag coverage is thin, or the specific field that changed carries no tag, the diff has nothing to attach the highlight to and the comparison looks empty even though both versions rendered.
+- **fix**:
+  1. Confirm live edit tags are enabled and rendered — see `edit-tags-not-generated-or-not-spread` in `faq-setup.md`.
+  2. In the Timeline iframe, run
+     `[...document.querySelectorAll('[data-cslp]')].map(el => ({tag: el.tagName, cslp: el.getAttribute('data-cslp')}))`
+     and confirm the **specific field you changed** appears in that list.
+  3. If the changed field has no tag, add it and retest.
+- **verification**: Change one plain text field in a release, open Timeline → Compare Website, and confirm that element is highlighted.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
new file mode 100644
index 0000000..bc50f2c
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -0,0 +1,100 @@
+# Visual Editor FAQ
+
+In-canvas behaviour once Live Preview itself is confirmed working: edit-tag resolution, the empty-block
+affordance, and what the canvas does with the site's own clicks. Live Preview refreshing correctly while
+the canvas misbehaves points here.
+
+If nothing on the canvas is editable at all, start with `edit-tags-not-generated-or-not-spread` in
+`faq-setup.md` — that is setup contract 2, and everything here assumes it is met.
+
+### cslp-not-rebased-to-referenced-entry
+- **bucket**: visual-editor
+- **symptom**: Edit tags on fields that come from a **referenced** entry do nothing when clicked. Tags on the page's own fields work. Console may show `{code: 'NO_REQUEST_LISTENER_FOUND', message: 'contentstack-adv-post-message: No request listener found for event "scroll"'}`, but that message is routine and appears on healthy setups too — treat it as incidental, not as the identifying evidence. Diagnose from the tags themselves.
+- **frameworks**: React, Next.js, framework-agnostic
+- **rendering_modes**: CSR, SSR
+- **root_cause**: `addEditableTags()` rebases a tag onto the referenced entry only when the resolved reference object carries both `uid` and `_content_type_uid`. Without them the tag stays anchored to the parent entry (`product.<parent_entry_uid>.<locale>.<reference_field>.<index>.<field>`), so there is no entry to navigate to. Common causes: references fetched separately and merged by hand (which drops those keys), or a GraphQL query that omits `system`. Hardcoding `data-cslp` by hand is a related failure — the referenced entry's uid and content type uid are not the ones being edited.
+- **fix**:
+  1. Inspect the referenced field in DevTools. Working shape is `<referenced_ct_uid>.<referenced_entry_uid>.<locale>.<field>`. If you see the parent entry's uid, this is the bug.
+  2. REST / Delivery SDK: resolve references with `includeReference()` / `include[]` so resolved objects keep `uid` and `_content_type_uid`.
+  3. GraphQL: request `system { uid, content_type_uid, locale }` on every reference.
+  4. If references are fetched separately, either preserve those two keys when merging, or call `addEditableTags()` on each referenced entry with its own content type uid.
+  5. Never hardcode `data-cslp` — always read the value the SDK put on the entry object.
+- **verification**: Click the edit tag on a referenced field; the CMS should open the referenced entry's editor and scroll to that field.
+
+---
+
+### locale-case-mismatch-lowercased-cslp
+- **bucket**: visual-editor
+- **symptom**: Visual Editor will not initialize for any non-fallback locale on an older stack, while Live Preview works. Locales defined with mixed case (for example `en-GB`) never match; only the fallback locale partially works, and updates still fail.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: `addEditableTags()` lowercases the locale segment when it builds `data-cslp`, and it does so **by default** — `useLowerCaseLocale` defaults to `true`. The generated tags therefore never match a stack whose locale codes were created with uppercase characters. Newer stacks create locales lowercase by default, which is why this is specific to older stacks. The fix is an opt-out flag, not a change in default behaviour.
+- **fix**:
+  1. Pass the opt-out as the fifth argument:
+     `addEditableTags(entry, "<content_type_uid>", true, locale, { useLowerCaseLocale: false });`
+     `addEditableTags` is an alias of `addTags` in `@contentstack/utils`; the option is typed as `options?: { useLowerCaseLocale?: boolean }`.
+  2. Confirm your `@contentstack/utils` version accepts a fifth argument. If your installed `addEditableTags` signature stops at `locale`, upgrade — 1.9.1 has it. Do not rely on the flag silently working on an older version; an extra argument is ignored without error.
+  3. Alternatively, normalise the stack's locale codes to lowercase — but only if nothing else depends on the existing casing.
+- **verification**: `data-cslp` values carry the locale in the stack's own casing (for example `...en-GB...`, not `...en-gb...`), and the editor opens for a non-fallback locale.
+
+---
+
+### empty-fields-are-not-clickable-on-the-canvas
+- **bucket**: visual-editor
+- **symptom**: An empty rich text field renders with zero height in preview mode, so there is nothing to click and the author cannot start editing it from the canvas. Same class of problem for any field that renders nothing when empty.
+- **frameworks**: React (reported); applies to any frontend
+- **rendering_modes**: any
+- **root_cause**: The canvas can only target what the page renders. A field whose empty state produces no DOM box has no hit area for the click-to-edit overlay.
+- **fix**:
+  1. Render a placeholder element for empty fields when the page is in preview or builder mode, so the field has a clickable box.
+  2. Detect preview/builder mode through the SDK rather than threading a prop through every nested component.
+  3. Give the placeholder a minimum height and keep the `data-cslp` attributes on it so the overlay targets it correctly.
+  4. This is about a **scalar field whose empty state renders no box**. An empty modular-block or multiple field is handled differently — the SDK draws its own "+ Add Component" affordance if the wrapper is marked correctly; see `empty-block-add-button-not-appearing-or-failing`.
+- **verification**: Clear a rich text field, reload the canvas, and confirm the empty field is still clickable and opens the correct field in the form.
+
+---
+
+---
+
+### empty-block-add-button-not-appearing-or-failing
+- **bucket**: visual-editor
+- **symptom**: A page or component with an empty modular-block / multiple field shows no "+ Add Component" affordance, so authors have to go to the form panel to add the first block.
+- **frameworks**: React, Next.js
+- **rendering_modes**: CSR, SSR
+- **root_cause**: The empty-block placeholder only renders when the wrapper carries **both** the `VB_EmptyBlockParentClass` class (exported by the SDK; its literal value is `visual-builder__empty-block-parent`) and a `data-cslp` pointing at the block field itself. Miss either and there is nothing for the canvas to attach the affordance to.
+- **fix**:
+  1. Confirm the wrapper renders both the class and a `data-cslp` pointing at the block field (for example `<page_ct>.<entry_uid>.<locale>.components`), and that it is rendered conditionally when the array is empty.
+  2. Confirm the wrapper is visible and has height. A zero-height container gives nothing to hover.
+  3. For nested blocks, put the same class and `data-cslp` on the inner block container, not only at page level.
+  4. This is specifically about a **block or multiple field with zero items**, where the SDK draws the affordance for you. A scalar field that renders nothing when empty is a different problem — see `empty-fields-are-not-clickable-on-the-canvas`.
+- **verification**: Open a page whose block field is empty. The "+ Add Component" placeholder appears on hover, and adding a block inserts it into both the canvas and the form.
+
+---
+
+### graphql-connection-wrappers-break-cslp
+- **bucket**: visual-editor
+- **symptom**: With GraphQL, edit tags are generated but Visual Editor cannot resolve them. The `data-cslp` values contain connection plumbing — for example `...edges.0.node.hero.heading` — and clicking a tagged element does nothing, or edit buttons on referenced fields are inert. The same integration over REST works.
+- **frameworks**: Next.js, React, any GraphQL client
+- **rendering_modes**: any
+- **root_cause**: `addEditableTags()` walks the response object and bakes every traversed layer into the `data-cslp` path. A GraphQL response nests values under `Connection -> edges -> node`, so those wrapper layers end up in the path and no field path resolves against the entry. This is by design — the SDK has no knowledge of GraphQL response shapes — so it needs a normalizer on the application side.
+- **fix**:
+  1. Request `system { uid, content_type_uid }` on every node the page renders, including referenced entries. Without those the tags cannot be attributed to an entry at all.
+  2. Flatten the response before tagging: collapse each `Connection -> edges -> node` into the plain object or array the REST shape would have produced, so a reference is an array of entries and a field is a direct property.
+  3. Call `addEditableTags()` on the flattened object, never on the raw GraphQL response.
+  4. Confirm the resulting `data-cslp` values contain no `edges` or `node` segments.
+- **verification**: Inspect a tagged element. Its `data-cslp` reads `<content_type_uid>.<entry_uid>.<locale>.<field_path>` with no connection segments, and clicking it focuses the field in the form panel.
+
+---
+
+### canvas-swallows-site-click-events
+- **bucket**: visual-editor
+- **symptom**: Interactive components stop working inside the editor canvas: carousel arrows, tab strips, accordions, dropdowns and links do nothing when clicked, while the same page works normally outside the editor. Often noticed as soon as a parent container gets a `data-cslp`.
+- **frameworks**: framework-agnostic
+- **rendering_modes**: any
+- **root_cause**: By design. In builder mode the SDK intercepts clicks so the canvas can capture them for editing: a click on any anchor, or on any element that is or sits inside a `data-cslp` element, gets `preventDefault()` and `stopPropagation()` before the site's own handler sees it. Anything interactive inside a tagged container is therefore inert in the canvas. This is what makes click-to-edit possible, so it cannot be switched off per element.
+- **fix**:
+  1. Recognise it as expected editor behaviour and say so. Authors are editing content, not exercising the site; interactivity is suspended in the canvas the same way it is in most visual editors.
+  2. Alt+click a link to follow it. The SDK navigates explicitly on alt+click, which is the supported way to move through the site inside the canvas.
+  3. Where a control must stay usable while editing, keep it outside any `data-cslp` container. Tag the content that is editable, not the interactive chrome around it.
+  4. Do not try to re-enable the site's handlers by stopping the SDK's interception. That breaks click-to-edit for every field under that element.
+- **verification**: The same control works on the public site and via alt+click in the canvas; tagged content around it still opens the field on click.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md b/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
new file mode 100644
index 0000000..555a2e5
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -0,0 +1,172 @@
+# Init placement by framework
+
+The SDK has no framework adapters. Framework choice decides exactly two things: where `init()` is
+allowed to run, and whether the framework's hydration preserves the edit-tag attributes you spread
+into the markup. Everything else follows from the rendering mode, covered in `rendering-modes.md`.
+
+`init()` touches `window`. It must run in the browser, once, before the first content render that
+needs to be previewable.
+
+## Next.js, App Router
+
+The most common setup mistake in this framework, and the one that produces "the SDK is installed
+and nothing happens" with no error anywhere.
+
+`init()` cannot run in a server component. Put it in a client component and import that into the
+layout so it runs once per app load:
+
+```tsx
+"use client";
+
+import { useEffect } from "react";
+import ContentstackLivePreview from "@contentstack/live-preview-utils";
+
+export function LivePreviewInit() {
+  useEffect(() => {
+    ContentstackLivePreview.init({
+      ssr: false,
+      mode: "builder",
+      stackSdk: stack.config,
+      stackDetails: { apiKey: API_KEY, environment: ENVIRONMENT },
+    });
+  }, []);
+
+  return null;
+}
+```
+
+Watch for three things here:
+
+- Soft navigation does not re-run server-side gating, and the SDK's module-level state persists
+  across route changes. Gate the edit button on something that is re-evaluated client-side, or it
+  will appear on production pages after a client-side navigation.
+- App Router metadata is produced by `generateMetadata()`, which has no hook for injecting window
+  globals. If you are using the `window.__CS_PAGE_CONTEXT__` route for page context, set it from a
+  client component, or use the `<meta>` tag form instead. Page context is only honoured when
+  **Custom Preview URLs** is configured and enabled on the plan; without that it is silently ignored.
+- Reading `searchParams` opts the route out of static rendering. Expect that when you add the SSR
+  hash path.
+
+For SSR, build the Stack instance inside the request rather than at module scope. See
+`rendering-modes.md`.
+
+## Next.js, Pages Router
+
+Works, in both of its data-fetching modes. Which contract applies depends on the method the route
+uses, not on the router:
+
+- **`getServerSideProps`** is SSR. Apply the SSR contract from `rendering-modes.md`: build the Stack
+  inside the function so it is per request, read the hash from `context.query.live_preview`, apply it
+  with `livePreviewQuery()`, and initialise with `ssr: true`.
+- **`getStaticProps`** is SSG. The page is prerendered and never sees the query string, so run
+  Live Preview in CSR mode: `ssr: false`, `stackSdk` passed, content refetched in `onEntryChange`.
+  No rebuild is needed for preview.
+
+Initialise once in `_app`, guarded to the client, since `init()` touches `window`.
+
+There is no page dedicated to the Pages Router in the Contentstack docs. Use the general pages for
+the mode in play — Set Up Live Preview with REST for SSR for `getServerSideProps`, and the SSG page
+for `getStaticProps` — and the same contracts hold. Contentstack's own Live Preview sanity fixture
+runs on the Pages Router.
+
+## React SPA with Vite
+
+The simplest case and the reference implementation. Init at the app entry point, before the first
+render:
+
+```ts
+ContentstackLivePreview.init({
+  ssr: false,
+  mode: "builder",
+  stackSdk: stack.config,
+  stackDetails: { apiKey: API_KEY, environment: ENVIRONMENT },
+});
+```
+
+`stackSdk` is mandatory in CSR mode. Omitting it also flips the automatic `ssr` default to `true`,
+which is a silent misconfiguration rather than an error.
+
+Refresh content through `onEntryChange`. If edits only appear after a manual reload, the callback
+was never registered, or it closed over a pathname captured at mount and is refetching the previous
+route.
+
+## Nuxt
+
+Init in a client-only plugin. For page context, `useHead()` is the natural place to emit the
+`<meta>` tags, since Nuxt produces head tags natively and has no built-in hook for injecting window
+globals. As everywhere, page context only takes effect with **Custom Preview URLs** configured and
+enabled on the plan.
+
+The Nuxt CSR and SSR stories differ on whether Visual Editor overlays appear, and Contentstack's
+own material is inconsistent on this point. Verify against the actual app before promising overlay
+support.
+
+## Angular
+
+Init in `APP_INITIALIZER` or the root component. By contract this is the same as the React SPA
+case: CSR, `stackSdk` mandatory, `onEntryChange` for refresh. Only the placement idiom differs.
+
+Angular Universal (SSR) is not covered by documentation. Apply the SSR contract from
+`rendering-modes.md` and verify.
+
+## SvelteKit and Astro
+
+Both are SSR with a Node adapter in their documented form, so the SSR contract applies unchanged:
+hash from the request, fresh Stack instance per request, full reload on update.
+
+Astro on some hosting platforms has an environment-variable parsing trap where the enable flag does
+not arrive as a boolean in the deployed build. If init appears not to run there, check the parsed
+value before checking anything else.
+
+Neither has support history. Do not present either as proven.
+
+## Gatsby
+
+Gatsby uses its own path via `ContentstackGatsby`, which previews without a rebuild. It needs
+`__typename` and `uid` in the GraphQL query, plus `addContentTypeUidFromTypename`.
+
+Two cautions. The published Gatsby starter is pinned to a Live Preview Utils v1.x release that
+predates Visual Editor, so it is not a valid Visual Editor reference. And whether Visual Editor
+works on a Gatsby static architecture is an open question internally, not a settled yes. Scope
+Gatsby answers to Live Preview unless the user has verified Visual Editor themselves.
+
+Note that `getGatsbyDataFormat` still appears in the SDK's README and configuration docs but has no
+implementation in the current source. It was removed in v3. Do not recommend it.
+
+## No SDK, or a non-JavaScript backend
+
+A first-class population, not a fallback. This shape covers every BFF, middleware, proxy, and
+non-JavaScript server.
+
+There is no `init()` to place on the server. The whole server-side integration is the fetch branch
+from contract 3 in the parent skill: read the hash from the request, switch host, add the
+`live_preview` and `preview_token` headers, and bypass cache for that request. If the application
+proxies Contentstack through its own backend, the hash has to be forwarded end to end, from the
+browser through the backend and into the outbound header. The JavaScript Live Preview Utils SDK is
+still required in the rendered page, whatever the backend is — it is what talks to the editor.
+
+### .NET
+
+The best-covered non-JavaScript stack. Verified against the SDK sources, not inferred:
+
+- **Live Preview** is documented for both SSR and CSR in
+  [Get Started with .Net SDK and Live Preview](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/dot-net/get-started-with-dot-net-sdk-and-live-preview).
+  The hash is applied with `await contentstackClient.LivePreviewQueryAsync(dict)`, where `dict`
+  carries the request's query parameters. The same per-request-instance rule as every SSR stack
+  applies. Timeline is supported by the same SDK.
+- **Edit tags, and therefore Visual Editor,** are supported through the `Contentstack.Utils` package:
+  `Contentstack.Utils.addEditableTags(entry, contentTypeUid, tagsAsObject, locale, options)`, with an
+  `addTags` alias and an `AddEditableTagsOptions.UseLowerCaseLocale` flag. It is written for parity
+  with the JavaScript `addEditableTags` and emits the same `data-cslp` and `data-cslp-parent-field`
+  attributes, so everything in the edit-tag entries applies unchanged.
+- **Two gaps to be honest about.** The .NET Live Preview docs page does not mention edit tags or
+  Visual Editor at all, and none of the public .NET example apps (Blazor starter, Razor Pages,
+  GraphQL) wire up Live Preview. So a user setting up Visual Editor on .NET is working from the
+  utils SDK rather than from a walkthrough. Point them at `Contentstack.Utils` and the edit-tag
+  entries, and do not promise a reference app.
+
+### Other server SDKs
+
+Java, PHP, Python and Ruby have Live Preview get-started pages in the same SSR shape. Whether their
+utils packages implement edit tags has not been verified here — check the package before promising
+Visual Editor on those stacks, and say so if it is absent.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
new file mode 100644
index 0000000..89566f9
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -0,0 +1,110 @@
+# The Onboarding Check
+
+Every visual experience product ships a setup check that runs automatically when the preview panel
+opens and reports its result in a small floating status card. It is the highest-yield thing to ask
+about, because it has already run the diagnosis the user is asking you to do.
+
+**Always ask for a screenshot of this card before asking anything else.** The step name on it
+localises the problem to one gate, and because of how the check is structured, it also tells you
+everything that already passed.
+
+## The property that makes it powerful
+
+The gates are evaluated as a single ordered chain, and it stops at the first failure. Only one
+step is ever shown.
+
+So a card reading "Preview Service Not Enabled" is not just one fact. It proves the website loaded
+in the frame, the SDK initialised, and the SDK version is supported. Three contracts are already
+ruled out. Do not re-ask about them.
+
+The inverse also holds. A card stuck on the first gate tells you nothing about any later gate,
+because none of them ran. Do not theorise about the SDK when the site never loaded.
+
+## Live Preview and Visual Editor
+
+Five gates, in this order.
+
+| # | Card while checking | Card on failure | What the failure means |
+|---|---|---|---|
+| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, HTTP or an untrusted certificate, or the browser blocking localhost. Nothing after this ran. |
+| 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | The frame loaded but no init handshake arrived. `init()` is in server-only code, the enable flag did not parse as a boolean in the deployed build, the init module was tree-shaken out, or init runs after the check window. |
+| 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake arrived from a version below the supported minimum. Upgrade Live Preview Utils. |
+| 4 | Verifying Preview Service | **Preview Service Not Enabled** | The SDK is fine and the site is fine, but content is not coming from the Preview Service. This is the fetch layer never switching host and headers, which is the most common failure of all. |
+| 5 | — | **Default Environment Not Set** | Everything works. Setup is recorded as complete. The stack simply has no default preview environment, set in stack settings. |
+| — | — | **Setup Complete** | All gates passed. |
+
+The exact body text is worth quoting back to users, because they often paraphrase it into
+something ambiguous. Gate 1 reads "Ensure the website is live and accessible via Contentstack
+origins." Gate 4 reads "Please enable the Preview Service for a seamless live preview experience."
+
+## Timeline
+
+Timeline runs its own check with three gates, not the five above. Do not map one onto the other.
+
+| # | Card | On failure | Meaning |
+|---|---|---|---|
+| 1 | Default Environment | Set default environment | No default environment configured |
+| 2 | Live Preview SDK | Use updated SDK | SDK version below the supported minimum |
+| 3 | Preview Token | Use preview token | Requests are not using the Preview Service |
+
+**Timeline's check has a fixed delay before it declares failure.** A site slower than that window
+produces a failure card even though the setup is correct. If a Timeline user reports a failing gate
+on a site you know is slow, have them re-open the panel on a warm cache before believing the card.
+
+## What the check does not cover
+
+This is where the check earns its keep as a diagnostic, and where people over-trust it. "Setup
+Complete" and a broken experience is a real and informative combination.
+
+The check verifies reachability, the SDK handshake, SDK version, and that the Preview Service is in
+use. It does not look at any of the following:
+
+- **Edit tags.** Nothing in the chain inspects `data-cslp`. If the card says Setup Complete and
+  nothing on the canvas is editable, the answer is edit-tag generation, every time. This is the
+  single most useful inference the check supports.
+- **Preview URL resolution.** The site loading is not the same as the correct entry loading. A card
+  reading Setup Complete on the wrong page is a routing problem.
+- **Locale, variants, and Timeline timestamps.**
+- **Caching.** Any cache on the preview path can serve published content while every gate passes.
+- **Roles.** The check runs as the signed-in user but does not report permission gaps, which is why
+  a role problem looks like "works for everyone except one person" rather than a failed gate.
+
+## When the card does not appear at all
+
+Absence is not a pass. Before treating a missing card as "the check succeeded", rule out:
+
+- No default environment is set and none is remembered locally for that locale, in which case the
+  overlay is deliberately not shown.
+- The user, or someone on their team, dismissed it. The preference persists per stack.
+- The stack setting suppresses it.
+
+**Do not reason about the default.** Each product keeps its own stack setting, and they disagree on
+what an unset value means:
+
+| Product | Setting | Unset resolves to |
+|---|---|---|
+| Timeline | `timeline.onboarding-setup-visible` | visible |
+| Live Preview | `live_preview.lp-onboarding-setup-visible` | hidden |
+| Visual Editor | `visual_builder.onboarding-setup-visible` | depends on whether the settings object exists |
+
+The Visual Experience settings screen renders every one of these as **on** when unset, so a stack
+that never explicitly saved the setting can show the toggle on while the card never appears.
+
+The fix is one action: open Settings → Visual Experience and Save, without changing anything. That
+form submits all three products' keys together and an unset value arrives as on, so one save writes
+an explicit value for all three and they stop disagreeing.
+
+If it then appears for colleagues but not for the reporter, they dismissed it. That suppression
+lives per stack in their own browser storage and no stack-level save clears it.
+
+If the user cannot produce the card, fall back to the four contracts in SKILL.md and verify them by
+hand.
+
+## How to ask for it
+
+Ask for the screenshot rather than the wording. Users paraphrase the step name into a different
+one, and since each name maps to a specific gate, a paraphrase can send you down the wrong branch.
+
+If they cannot screenshot it, ask for the exact step name and body text as displayed, and confirm
+which product they are in, because Live Preview and Timeline share a visual style but not a set of
+gates.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
new file mode 100644
index 0000000..2bcb6ff
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -0,0 +1,93 @@
+# Preflight checklist
+
+Run in order. Each step either passes or localises the problem to one contract. Stop at the first
+failure and fix it before continuing, because a failure upstream makes every downstream check
+meaningless.
+
+## Before touching the application
+
+1. **Get the Onboarding Check to appear.** It walks the contracts in order and names the first one
+   that fails. Do not assume its default state: each product stores its own setting under
+   Settings → Visual Experience, and an unset value resolves differently per product, so the toggle
+   can read on while the card never appears. Save the setting explicitly for the product in use.
+2. **Live Preview is enabled on the stack**, with a default preview environment set.
+3. **A Preview Token exists**, generated against the Delivery Token the application already uses.
+   A management token is not a substitute and must never reach client-side configuration.
+4. **The environment has a Base URL**, and one for each locale being previewed. A missing Base URL
+   presents as a greyed-out environment selector or "No environments available".
+5. **The signed-in user's role can read everything the page uses.** Preview runs as that user and
+   applies their full ACL — content types, entries, fields, locales, assets — so anything they
+   cannot read comes back empty. Delivery uses a delivery token and applies none. Expect preview
+   to differ per user, and make the site render missing data gracefully.
+
+## Reachability
+
+6. **The preview host is served over HTTPS** with a trusted certificate.
+7. **`curl -I https://<preview-host>/<a-deep-route>`** returns no `X-Frame-Options`, and a CSP
+   `frame-ancestors` that includes the Contentstack app origin. Test a deep route, not the site
+   root, and confirm it holds after any redirect.
+8. **Nothing sits in front of the site that cannot render in a frame**: platform password
+   protection, an SSO screen setting `X-Frame-Options: DENY`, or basic auth.
+9. **If previewing `http://localhost`**, confirm the browser is not blocking it. Chrome's Local
+    Network Access policy blocks the app origin from framing localhost and only the user can grant
+    the permission.
+
+## Versions
+
+10. **Live Preview Utils v3.0+ and Delivery SDK v3.20.3+** for Visual Editor. **v4.4.4+** if using
+    `setPageContext()`.
+11. **Exactly one copy of the preview SDK is loaded.** An npm install plus an ESM or CDN
+    `<script type="module">` import of a different version produces behaviour differences that look
+    like configuration bugs.
+
+## Contract 1: init runs
+
+12. **A `POST /live-preview/tracker` returns 2xx** when the preview panel loads. If it never fires,
+    init did not run.
+13. **`init()` runs on the client**, not in server-only code.
+14. **The enable flag parses as a boolean in the deployed build.** A string `"false"` is truthy.
+15. **`ssr` is set explicitly.** The automatic default keys off `stackSdk` and gets it wrong in both
+    directions: a CSR app without `stackSdk` silently becomes SSR, and an SSG site with `ssr: true`
+    produces blank screens rather than an error.
+16. **`stackDetails: { apiKey, environment }` is passed explicitly.** Since v2 the SDK no longer
+    derives the API key from the Stack object for edit tags.
+
+## Contract 2: edit tags reach the DOM
+
+17. **A rendered field carries `data-cslp`**, formed as
+    `<content_type_uid>.<entry_uid>.<locale>.<field_path>`.
+18. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called on every fetched entry,
+    including referenced entries. The third argument must be `true` for React and JSX.
+19. **The `$` attributes are spread onto the leaf element** that renders the value, one `data-cslp`
+    per element. Tagging a wrapper selects the wrong field.
+20. **Reference paths mirror the data shape.** References come back as arrays:
+    `post.author[0].$?.name`, not `post.$?.author.name`.
+21. **For GraphQL**, connection wrappers are flattened and `system { uid, content_type_uid }` is
+    requested on every node, before `addEditableTags()` runs.
+
+## Contract 3: the hash reaches the fetch
+
+22. **Content requests hit a `*-preview.contentstack.com` host** during an active preview session.
+    Seeing `cdn.contentstack.io` or `graphql.contentstack.com` here is the single most common setup
+    failure, whatever the reported symptom was.
+23. **Those requests carry `live_preview` and `preview_token` headers** and return 200.
+24. **Every fetch path uses the initialized Stack instance.** A second instance, a hand-rolled
+    wrapper, or a BFF that bypasses it will keep serving published content.
+25. **The hash is never hardcoded or invented.** An unrecognised hash returns
+    `error_code 382, Please create tracker before starting live preview session`.
+26. **If the app proxies Contentstack through its own backend**, the hash is forwarded end to end.
+27. **SSR only: the Stack instance is built per request.** A module-level instance leaks one
+    editor's draft into other users' responses, including public traffic.
+28. **Caching is bypassed for preview requests.** Any cache on the preview path serves published
+    content after the host switch is already correct, and can serve preview output to real visitors.
+
+## Behaviour
+
+29. **Edit a field without saving.** The preview updates.
+30. **Hover a tagged element in Visual Editor.** It highlights, and clicking focuses the matching
+    field in the form panel.
+31. **Open entries from several content types**, including a nested route and one with no `url`
+    field. Each loads its own page.
+32. **Navigate inside the preview pane.** Preview context survives the navigation.
+33. **Load the public site in a normal browser tab.** No edit button, no `#cslp-tooltip` in the DOM,
+    and no preview response served from cache.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
new file mode 100644
index 0000000..a5c552f
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -0,0 +1,126 @@
+# Rendering modes
+
+The Live Preview SDK ships no framework adapters. It declares no framework peer dependencies and
+contains no per-framework code paths. What determines the correct integration is the rendering
+mode of the affected route and the fetch layer underneath it, not the framework's name.
+
+Diagnose against this file. Use `frameworks.md` only for where `init()` is allowed to run.
+
+## The contract per mode
+
+| Mode | `ssr` | How the hash travels | How updates arrive | Hard requirement |
+|---|---|---|---|---|
+| CSR + REST | `false` | postMessage; the SDK injects it into `stackSdk` | `onEntryChange` / `onLiveEdit` refetch, no reload | `stackSdk` is mandatory |
+| SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload | a fresh Delivery SDK instance per request |
+| CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch | manual host swap plus headers |
+| SSR + GraphQL | `true` | `request.query.live_preview` | full iframe reload | manual host swap plus headers |
+| SSG | `false` | postMessage | runs in CSR mode at runtime | `stackSdk`, and `init()` must be browser-only |
+
+## How `ssr` is resolved
+
+Precedence is `stackSdk.live_preview.ssr`, then `init({ ssr })`, then the automatic default.
+
+The automatic default keys off `stackSdk`: present means `ssr: false`, absent means `ssr: true`.
+This is the trap behind several setup failures. A CSR app that omits `stackSdk` silently gets SSR
+behaviour, and an SSG site initialized with `ssr: true` produces blank and black screens rather
+than a clean error.
+
+Set it explicitly. Do not rely on the default.
+
+## Mode-specific failures worth knowing before you prescribe
+
+### SSR: the shared instance
+
+A module-level Stack instance is shared across requests. Applying a preview hash to it mutates
+shared state, so one editor's draft leaks into other users' responses. This reaches public traffic,
+not just the authoring session, and it presents as intermittent wrong content plus tracker-invalid
+and branch-mismatch errors on the production site.
+
+Build the Stack instance inside the request handler. This is the most damaging SSR mistake there is,
+and the least obvious, because it works perfectly with one user.
+
+### SSG: supported, in CSR mode
+
+SSG is documented and supported. Do not tell users it is a dead end.
+
+The confusion comes from the hash. In SSR mode the hash travels as the `live_preview` query
+parameter, and a prerendered page never sees a query parameter, so the fetch is never switched.
+The documented answer is not to fight that, it is to run the preview path in **CSR mode**, where
+the hash arrives by postMessage instead and never needs the URL.
+
+Per [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-static-site-generator-ssg):
+
+- Initialise Live Preview Utils with `ssr: false`
+- Pass `stackSdk`, which is mandatory in CSR mode
+- Configure the Delivery SDK with
+  `live_preview: { preview_token, enable: true, host: "rest-preview.contentstack.com" }`
+- Refresh through `onLiveEdit()`, so the browser refetches on each edit
+
+So an SSG site previews without a rebuild. The static build serves the shell, and the preview
+content is fetched client-side during the session.
+
+The common failure here is not SSG itself, it is an SSG site initialised with `ssr: true`. That
+produces blank and black screens rather than a clean error.
+
+### ISR: the genuinely hard case
+
+ISR is where there is no clean answer, and it should not be lumped in with SSG.
+
+Contentstack's recorded position more broadly is that caching has to be off for Live Preview and
+Visual Editor routes, and that integrating with a framework's own cache-invalidation feature is
+out of scope. Do not send users toward a framework's draft mode expecting Contentstack to meet it
+there.
+
+In Next.js specifically, reading `searchParams` opts a route out of static rendering. Where a team
+insists on a hybrid, the workable pattern is detecting `live_preview` and forcing that request
+dynamic. No official hybrid recipe is published, so treat anything beyond this as unverified.
+
+### Caching at the edge
+
+Any cache on the preview path keeps serving published content after the host
+switch is already correct. This produces "works on localhost, fails on the deployed environment",
+which users reliably misread as a Contentstack outage.
+
+The same misconfiguration has the inverse failure, which is worse: preview output reaching real
+visitors. That is usually the shared-instance problem above rather than the cache itself, with the
+cache widening the blast radius. Treat preview output on a public URL as urgent, and fix the
+per-request instance first.
+
+### GraphQL: edit tags do not survive connection wrappers
+
+`addEditableTags()` bakes each traversed layer into the `data-cslp` path, and a GraphQL response
+nests values under `Connection -> edges -> node`, so those wrapper layers end up in the path and no
+tag resolves. This is by design and needs a response normalizer on the application side. The full
+fix is `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md`.
+
+### App Router soft navigation
+
+SDK module-level singletons persist across client-side route changes, and soft navigation does not
+re-run server-side gating. This is the recorded cause of the edit button appearing on production
+pages after a client-side navigation, on setups where the server-rendered entry point gates it
+correctly.
+
+## Framework and mode coverage
+
+Support here means documented and exercised, not merely possible.
+
+| Framework | CSR | SSR | SSG / ISR | Edge |
+|---|---|---|---|---|
+| Next.js App Router | documented, Visual Editor supported | documented, Visual Editor supported; fragile for empty-block affordances | runs as CSR at runtime; `searchParams` conflicts with fully static routes | no coverage |
+| Next.js Pages Router | supported | supported via `getServerSideProps` | supported via `getStaticProps`, runs in CSR mode | no coverage |
+| React SPA (Vite) | reference implementation | not applicable | not applicable | not applicable |
+| Nuxt | documented | documented | not applicable | no coverage |
+| Angular | documented | Universal not covered | not applicable | no coverage |
+| SvelteKit | not covered | documented | not covered | no coverage |
+| Astro | not covered | documented, Node adapter | static mode untested | environment-variable parsing trap on some hosts |
+| Gatsby | supported without a rebuild | not applicable | the intended mode | not applicable |
+| .NET | documented | documented; Visual Editor via `Contentstack.Utils` edit tags | not covered | no coverage |
+| Other server SDKs (Java, PHP, Python, Ruby) | not covered | Live Preview documented; edit-tag support unverified | not covered | no coverage |
+
+Two honest gaps in this table:
+
+- **Edge runtimes have no coverage anywhere.** Not in the documentation, the SDK source, or the
+  issue tracker. This is absence of evidence rather than a known incompatibility. If a user is on
+  an edge runtime, say that it is untested rather than guessing.
+- **Frameworks with a starter but no support history** cannot be distinguished between "works
+  cleanly" and "nobody uses it". Both produce zero tickets. Do not present them as proven.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
new file mode 100644
index 0000000..60475ab
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -0,0 +1,71 @@
+# Setup: the documentation is the source of truth
+
+For setup, follow the official Contentstack documentation. Do not reconstruct setup steps from
+memory and do not invent a procedure. Identify the framework and rendering mode, open the matching
+page, and follow it.
+
+The rest of this skill exists for when the documented setup has been followed and something still
+does not work. That is a different job, and it is where the mined failure catalogue earns its keep.
+
+## Pick the page
+
+Establish framework and rendering mode first, then route.
+
+### Start here regardless
+
+- [Set Up Live Preview for your Website](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-your-website) — the setup hub
+- [How Live Preview Works](https://www.contentstack.com/docs/developers/set-up-live-preview/how-live-preview-works) — the model to reason from
+- [How Live Preview Works with SDK](https://www.contentstack.com/docs/headless-cms/how-live-preview-works-with-sdk) — how `ssr` is resolved and how the hash travels
+
+### By framework and mode
+
+| Framework and mode | Page |
+|---|---|
+| Next.js App Router, CSR | [Live Preview Implementation for Next.js CSR App Router](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-nextjs-csr-app-router) |
+| Next.js App Router, SSR | [Live Preview Implementation for Next.js SSR App Router](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-nextjs-ssr-app-router) |
+| React, CSR | [Live Preview Implementation for ReactJS CSR Website](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-reactjs-csr-website) |
+| Any framework, SSG | [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-static-site-generator-ssg) — runs in CSR mode, `ssr: false` |
+| Any framework, SSR over REST | [Set Up Live Preview with REST for Server-Side Rendering](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-with-rest-for-server-side-rendering) |
+
+### Visual Editor, on top of a working Live Preview
+
+Visual Editor is not a separate integration. It is Live Preview plus edit tags, so Live Preview
+must work first.
+
+- [Set Up Visual Builder for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-builder/set-up-visual-builder-for-your-website)
+- [Set Up Visual Editor for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-editor/set-up-visual-editor-for-your-website)
+- [Set Up Live Edit Tags for Entries with REST](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-edit-tags-for-entries-with-rest) — the `addEditableTags()` reference
+
+### Starters
+
+[Kickstart Next.js](https://www.contentstack.com/docs/developers/kickstarts/next) and its siblings
+are working references. When a user's setup disagrees with a kickstart, the kickstart is right.
+
+## What the documentation will not settle
+
+These come up constantly and are not answered by any setup page. Say so plainly rather than
+guessing, and reach for `rendering-modes.md` and `faq-setup.md`.
+
+- **Next.js Pages Router.** Supported, but has no dedicated page. Use the SSR-over-REST page for
+  `getServerSideProps` and the SSG page for `getStaticProps`; the contracts are identical.
+- **ISR and framework cache or draft modes.** SSG *is* documented (see the table above). ISR is
+  not. Caching must be off for preview routes, and integrating with a framework's own
+  cache-invalidation or draft feature is out of scope.
+- **Edge runtimes.** No coverage anywhere. Untested rather than unsupported. Say that.
+- **GraphQL with edit tags.** Connection wrappers break `data-cslp` paths and need a
+  customer-side response normalizer. By design; see `graphql-connection-wrappers-break-cslp` in
+  `faq-visual-editor.md`.
+- **Frameworks with a starter but no support history.** A starter existing is not evidence the
+  combination is proven.
+
+## Two things worth stating before a user starts
+
+**Version minimums.** Live Preview Utils v3.0+ and Delivery SDK v3.20.3+ for Visual Editor, and
+Live Preview Utils v4.4.4+ for `setPageContext()`. Load exactly one copy of the preview SDK; mixing
+an npm install with an ESM or CDN import of a different version produces behaviour that looks like
+a configuration bug.
+
+**`addEditableTags()` mutates and returns nothing.** It updates the entry passed as its first
+argument in place. Assigning its result gives you `undefined`, which is a common first-timer
+mistake. For React and JSX, `tagsAsObject` must be `true`; it defaults to `false`, which produces a
+string that React cannot spread.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md b/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
new file mode 100644
index 0000000..29eb687
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
@@ -0,0 +1,69 @@
+# Symptom index
+
+Find the reported symptom, go to the entry. Symptoms are worded the way users report them, not the
+way the underlying cause would be described.
+
+Setup entries come first because an unmet setup contract produces a large share of what gets
+reported as behavioural. If the integration has never fully worked, work the four contracts in
+SKILL.md before reading anything below.
+
+
+## Setup and first integration
+
+| Symptom | Entry |
+|---|---|
+| Live Preview / Visual Editor loads the site fine, but edits made in the entry form or the right-hand panel nev… | [app-fetches-from-delivery-cdn-instead-of-preview-service](faq-setup.md#app-fetches-from-delivery-cdn-instead-of-preview-service) |
+| The Live Preview / Visual Editor pane is blank or shows "`<your-host>` refused to connect" | [iframe-blocked-by-x-frame-options-or-csp-frame-ancestors](faq-setup.md#iframe-blocked-by-x-frame-options-or-csp-frame-ancestors) |
+| Preview API requests fail with `{"error_message":"Please create tracker before starting live preview session",… | [error-382-create-tracker-before-starting-live-preview-session](faq-setup.md#error-382-create-tracker-before-starting-live-preview-session) |
+| Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar | [edit-tags-not-generated-or-not-spread](faq-setup.md#edit-tags-not-generated-or-not-spread) |
+| Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited | [preview-url-does-not-resolve-to-the-app-route](faq-setup.md#preview-url-does-not-resolve-to-the-app-route) |
+| Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump break… | [sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade](faq-setup.md#sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade) |
+| The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wr… | [environment-base-url-misconfigured-or-missing-for-a-locale](faq-setup.md#environment-base-url-misconfigured-or-missing-for-a-locale) |
+| The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or t… | [edit-button-rendered-outside-a-live-preview-session](faq-setup.md#edit-button-rendered-outside-a-live-preview-session) |
+| `Access to fetch at 'https://<region>-rest-preview.contentstack.com/v3/...' from origin '<site origin>' has be… | [cors-blocked-on-preview-api-requests](faq-setup.md#cors-blocked-on-preview-api-requests) |
+| Two opposite failures from the same mistake | [ssr-stack-instance-shared-or-duplicated](faq-setup.md#ssr-stack-instance-shared-or-duplicated) |
+| In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit… | [nextjs-app-router-init-must-run-in-a-client-component](faq-setup.md#nextjs-app-router-init-must-run-in-a-client-component) |
+| "Preview Service Not Enabled" shows in the preview panel on a setup that otherwise works | [legacy-management-token-setup-not-migrated-to-preview-token](faq-setup.md#legacy-management-token-setup-not-migrated-to-preview-token) |
+| Preview opens for pages that already exist on the main branch but never shows updates, and any page that exist… | [branch-or-alias-mismatch-between-app-token-and-entry](faq-setup.md#branch-or-alias-mismatch-between-app-token-and-entry) |
+| Live Preview never activates or the preview panel reports the service is not enabled, even though the stack se… | [wrong-region-hosts-in-sdk-and-preview-config](faq-setup.md#wrong-region-hosts-in-sdk-and-preview-config) |
+| Start Editing / the Edit button opens Visual Editor or the entry editor with `locale=en-us` even though the st… | [locale-defaults-to-en-us-in-init](faq-setup.md#locale-defaults-to-en-us-in-init) |
+| The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `… | [start-editing-button-cannot-be-hidden-in-editor-mode](faq-setup.md#start-editing-button-cannot-be-hidden-in-editor-mode) |
+| A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days… | [onboarding-check-card-not-visible-or-appears-unexpectedly](faq-setup.md#onboarding-check-card-not-visible-or-appears-unexpectedly) |
+| The "Visual Experience" / builder-mode option does not appear in the Contentstack navigation at all, so the te… | [visual-experience-navigation-missing-for-the-stack](faq-setup.md#visual-experience-navigation-missing-for-the-stack) |
+| The site renders in the preview pane but behaves as if logged out, or without personalization, locale or curre… | [third-party-cookies-blocked-inside-the-preview-iframe](faq-setup.md#third-party-cookies-blocked-inside-the-preview-iframe) |
+| A previously working local Live Preview setup breaks with `Access to fetch at 'http://localhost:5173/' from or… | [chrome-local-network-access-blocks-preview-of-localhost](faq-setup.md#chrome-local-network-access-blocks-preview-of-localhost) |
+| `data-cslp` attributes in the DOM contain `undefined` where the entry uid should be | [cslp-tags-contain-the-literal-string-undefined](faq-setup.md#cslp-tags-contain-the-literal-string-undefined) |
+| Live Preview on a statically generated site is unreliable or simply shows build-time content: blank or black s… | [ssg-preview-needs-csr-mode](faq-setup.md#ssg-preview-needs-csr-mode) |
+
+## Preview runtime
+
+| Symptom | Entry |
+|---|---|
+| Selecting a variant (or switching audience in Audience Preview) in Visual Experience keeps rendering the base… | [variant-or-audience-switch-shows-base-entry](faq-preview-runtime.md#variant-or-audience-switch-shows-base-entry) |
+| Preview works on localhost but not on a deployed environment with identical code and config — the setup status… | [cached-response-serves-stale-preview](faq-preview-runtime.md#cached-response-serves-stale-preview) |
+| A page that renders fine in the entry editor and on the live site comes back blank in Visual Experience for a… | [locale-fallback-blank-or-wrong-locale-in-preview](faq-preview-runtime.md#locale-fallback-blank-or-wrong-locale-in-preview) |
+| Edits only appear after manually reloading the preview | [csr-edits-need-manual-refresh](faq-preview-runtime.md#csr-edits-need-manual-refresh) |
+| Preview works on the entry's own URL, but navigating within the site inside the preview panel breaks it — "Pag… | [spa-client-navigation-loses-preview-context](faq-preview-runtime.md#spa-client-navigation-loses-preview-context) |
+| `ContentstackLivePreview.hash` logs as an empty string, so the code that gates on it never switches to the pre… | [hash-empty-outside-the-preview-iframe](faq-preview-runtime.md#hash-empty-outside-the-preview-iframe) |
+| The very first `onEntryChange` fetch after opening the preview returns published data even though the entry wa… | [stale-first-fetch-when-editing-a-referenced-entry](faq-preview-runtime.md#stale-first-fetch-when-editing-a-referenced-entry) |
+| Live Preview works for top-level fields but an edit to an entry that is referenced inside another entry does n… | [legacy-management-token-preview-breaks-on-references](faq-preview-runtime.md#legacy-management-token-preview-breaks-on-references) |
+| One user sees an empty or partly empty page in Live Preview / Visual Editor while colleagues on the same stack… | [preview-renders-empty-for-a-restricted-user](faq-preview-runtime.md#preview-renders-empty-for-a-restricted-user) |
+| Ad slots, consent widgets, or other host-dependent third-party scripts intermittently fail to render inside Li… | [third-party-scripts-misbehave-inside-the-preview-iframe](faq-preview-runtime.md#third-party-scripts-misbehave-inside-the-preview-iframe) |
+
+## Visual Editor
+
+| Symptom | Entry |
+|---|---|
+| Edit tags on fields that come from a referenced entry do nothing when clicked | [cslp-not-rebased-to-referenced-entry](faq-visual-editor.md#cslp-not-rebased-to-referenced-entry) |
+| Visual Editor will not initialize for any non-fallback locale on an older stack, while Live Preview works | [locale-case-mismatch-lowercased-cslp](faq-visual-editor.md#locale-case-mismatch-lowercased-cslp) |
+| An empty rich text field renders with zero height in preview mode, so there is nothing to click and the author… | [empty-fields-are-not-clickable-on-the-canvas](faq-visual-editor.md#empty-fields-are-not-clickable-on-the-canvas) |
+| A page or component with an empty modular-block / multiple field shows no "+ Add Component" affordance, so aut… | [empty-block-add-button-not-appearing-or-failing](faq-visual-editor.md#empty-block-add-button-not-appearing-or-failing) |
+| With GraphQL, edit tags are generated but Visual Editor cannot resolve them | [graphql-connection-wrappers-break-cslp](faq-visual-editor.md#graphql-connection-wrappers-break-cslp) |
+| Interactive components stop working inside the editor canvas: carousel arrows, tab strips, accordions, dropdow… | [canvas-swallows-site-click-events](faq-visual-editor.md#canvas-swallows-site-click-events) |
+
+## Timeline
+
+| Symptom | Entry |
+|---|---|
+| Timeline preview shows the wrong point in time — either the current version regardless of the date picked, or… | [timeline-preview-timestamp-ignored-or-dropped](faq-timeline.md#timeline-preview-timestamp-ignored-or-dropped) |
+| Timeline Compare Website renders both versions but highlights no differences between them. | [timeline-compare-highlights-no-differences](faq-timeline.md#timeline-compare-highlights-no-differences) |

From 53a14b920f10aeb54b5387bf1ec35a788d44f883 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Fri, 4 Sep 2026 15:01:00 +0530
Subject: [PATCH 02/21] fix(skills): make the Onboarding Check mandatory and
 warn that onEntryChange is inert under ssr: true

Four edits from a first real dry run of the skill against a Next.js App
Router app, each closing a gap the run walked into:

- Mode table now states that onEntryChange subscribers never fire when
  ssr is true. The SDK dispatches entry-change events only on !ssr, so a
  refetch or router.refresh() registered in an SSR app looks correct and
  does nothing. SSR updates are parent-driven; client-driven refresh
  requires a CSR route. Same warning added to rendering-modes.md.
- Step 3 (Onboarding Check) is now explicitly not skippable whenever a
  pane renders, and repository access does not excuse it. Code detection
  in step 4 reports what the integration intends; the card reports what
  the deployed build did. When they disagree, the card wins.
- Workflow summary is a checklist to report back ticked, so a skipped
  step is a visible gap rather than a silent one.
- Falsification rule beside the stop rule: before acting on a diagnosis,
  fetch the one artifact that would contradict it, especially when
  confident.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../SKILL.md                                  | 39 ++++++++++++++-----
 .../references/rendering-modes.md             | 10 ++++-
 ...review-visual-editor-support-assistant.mdc | 39 ++++++++++++++-----
 .../SKILL.md                                  | 39 ++++++++++++++-----
 .../references/rendering-modes.md             | 10 ++++-
 5 files changed, 108 insertions(+), 29 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
index 2636992..d3bd1b2 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -68,13 +68,16 @@ Collected in the order set out below, not all at once. Never ask for delivery to
 
 ## Workflow Summary
 
-1. Identify the product.
-2. Setup or regression.
-3. Read the Onboarding Check.
-4. Detect framework and rendering mode from the code.
-5. Collect only the evidence detection could not supply.
-6. Localise to one contract.
-7. Fix, verify, or hand to Contentstack Support.
+Work these as a checklist and report it back ticked. An unticked step is a visible gap the user
+can see and question; a silently skipped step is how a wrong diagnosis gets past both of you.
+
+- [ ] 1. Identify the product.
+- [ ] 2. Setup or regression.
+- [ ] 3. Read the Onboarding Check. Not skippable whenever a preview pane renders.
+- [ ] 4. Detect framework and rendering mode from the code.
+- [ ] 5. Collect only the evidence detection could not supply.
+- [ ] 6. Localise to one contract.
+- [ ] 7. Fix, verify, or hand to Contentstack Support.
 
 ## Instructions
 
@@ -84,6 +87,11 @@ whose answers you could already have had.
 **Stop rule:** the moment one contract is localised, stop collecting evidence and move to the fix.
 Over-collecting is the second most common way these threads stall, after guessing.
 
+**Falsification rule:** before acting on a diagnosis, name the one artifact that would contradict
+it, and go get it. Confidence is the cue to do this, not the excuse to skip it. The commonest miss is
+a mode assumption: the code reads one way, and the Onboarding Check card or the network tab says
+otherwise. When they disagree, the observed behaviour wins over the intended one.
+
 ### Step 1. Which product?
 
 Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
@@ -115,6 +123,11 @@ stack settings change, a role change, a new environment, a CDN or hosting change
 Ask for a **screenshot** of the floating status card in the preview panel. Do this before any other
 diagnostic question. The product already ran the check you are about to run by hand.
 
+**This step is not skippable when a pane renders at all, and repository access does not excuse it.**
+Step 4 reads the code and tells you what the integration *intends*; the card tells you what the editor
+*observed* on the actual deployed build. They can disagree, most often on rendering mode, and when
+they do the card is the one that reflects reality. Do step 3 first, then let step 4 explain it.
+
 Ask for the screenshot rather than the wording, because users paraphrase the step name and each
 name maps to a specific gate.
 
@@ -154,7 +167,9 @@ Two readings that decide the whole branch:
 ### Step 4. Establish framework and rendering mode
 
 **Detect this, do not ask for it.** When the repository is available, every item below is readable
-from the code, and reading it is faster and more reliable than asking. Developers routinely answer
+from the code, and reading it is faster and more reliable than asking. Detection does not replace
+step 3: the card still comes first, because it reports the deployed build rather than the branch you
+are reading. Developers routinely answer
 "Next.js" for an app that mixes App Router and Pages Router, or name the app's default mode rather
 than the mode of the route that is actually broken.
 
@@ -196,11 +211,17 @@ tags. Everything else follows from mode and fetch layer.
 | Mode | `ssr` | Hash travels via | Updates arrive as |
 |---|---|---|---|
 | CSR + REST | `false` | postMessage, into `stackSdk` | `onEntryChange` refetch, no reload |
-| SSR + REST | `true` | `live_preview` query parameter | full iframe reload |
+| SSR + REST | `true` | `live_preview` query parameter | full iframe reload, driven by the parent. `onEntryChange` subscribers **never fire** in this mode |
 | CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch, manual host swap |
 | SSR + GraphQL | `true` | `request.query.live_preview` | full reload, manual host swap |
 | SSG | `false` | postMessage | runs as CSR at runtime |
 
+**`onEntryChange` is inert under `ssr: true`.** The SDK guards its entry-change dispatch on `!ssr`,
+so any subscriber registered in an SSR app never runs. Registering one to trigger a refetch or
+`router.refresh()` produces a callback that looks correct and does nothing. Under `ssr: true` the
+update path is the parent reloading the iframe with the new hash; the app's only job is to read the
+hash off that request. If you want client-driven refresh, the route has to be CSR (`ssr: false`).
+
 `stackSdk` is mandatory in CSR and is what the SDK uses to default `ssr`. A CSR app that omits it
 silently gets SSR behaviour; an SSG site initialised with `ssr: true` gives blank screens rather
 than an error. Two mode traps to check before prescribing: **SSR** needs a per-request Stack
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
index a5c552f..46a4016 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -11,11 +11,19 @@ Diagnose against this file. Use `frameworks.md` only for where `init()` is allow
 | Mode | `ssr` | How the hash travels | How updates arrive | Hard requirement |
 |---|---|---|---|---|
 | CSR + REST | `false` | postMessage; the SDK injects it into `stackSdk` | `onEntryChange` / `onLiveEdit` refetch, no reload | `stackSdk` is mandatory |
-| SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload | a fresh Delivery SDK instance per request |
+| SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload, parent-driven; `onEntryChange` subscribers never fire | a fresh Delivery SDK instance per request |
 | CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch | manual host swap plus headers |
 | SSR + GraphQL | `true` | `request.query.live_preview` | full iframe reload | manual host swap plus headers |
 | SSG | `false` | postMessage | runs in CSR mode at runtime | `stackSdk`, and `init()` must be browser-only |
 
+## `onEntryChange` does not fire under `ssr: true`
+
+The SDK dispatches entry-change events only when `ssr` is `false`. In SSR mode the parent reloads
+the iframe with the new hash and the app never receives a client-side event. A subscriber registered
+in an SSR app is silently inert, so a `router.refresh()` or refetch wired into it never runs, and the
+integration looks correct while doing nothing on edit. Drive SSR updates from the request, not from a
+subscriber; if client-driven refresh is wanted, the route must be CSR.
+
 ## How `ssr` is resolved
 
 Precedence is `stackSdk.live_preview.ssr`, then `init({ ssr })`, then the automatic default.
diff --git a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
index 9332a7d..f914231 100644
--- a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
+++ b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
@@ -71,13 +71,16 @@ Collected in the order set out below, not all at once. Never ask for delivery to
 
 ## Workflow Summary
 
-1. Identify the product.
-2. Setup or regression.
-3. Read the Onboarding Check.
-4. Detect framework and rendering mode from the code.
-5. Collect only the evidence detection could not supply.
-6. Localise to one contract.
-7. Fix, verify, or hand to Contentstack Support.
+Work these as a checklist and report it back ticked. An unticked step is a visible gap the user
+can see and question; a silently skipped step is how a wrong diagnosis gets past both of you.
+
+- [ ] 1. Identify the product.
+- [ ] 2. Setup or regression.
+- [ ] 3. Read the Onboarding Check. Not skippable whenever a preview pane renders.
+- [ ] 4. Detect framework and rendering mode from the code.
+- [ ] 5. Collect only the evidence detection could not supply.
+- [ ] 6. Localise to one contract.
+- [ ] 7. Fix, verify, or hand to Contentstack Support.
 
 ## Instructions
 
@@ -87,6 +90,11 @@ whose answers you could already have had.
 **Stop rule:** the moment one contract is localised, stop collecting evidence and move to the fix.
 Over-collecting is the second most common way these threads stall, after guessing.
 
+**Falsification rule:** before acting on a diagnosis, name the one artifact that would contradict
+it, and go get it. Confidence is the cue to do this, not the excuse to skip it. The commonest miss is
+a mode assumption: the code reads one way, and the Onboarding Check card or the network tab says
+otherwise. When they disagree, the observed behaviour wins over the intended one.
+
 ### Step 1. Which product?
 
 Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
@@ -118,6 +126,11 @@ stack settings change, a role change, a new environment, a CDN or hosting change
 Ask for a **screenshot** of the floating status card in the preview panel. Do this before any other
 diagnostic question. The product already ran the check you are about to run by hand.
 
+**This step is not skippable when a pane renders at all, and repository access does not excuse it.**
+Step 4 reads the code and tells you what the integration *intends*; the card tells you what the editor
+*observed* on the actual deployed build. They can disagree, most often on rendering mode, and when
+they do the card is the one that reflects reality. Do step 3 first, then let step 4 explain it.
+
 Ask for the screenshot rather than the wording, because users paraphrase the step name and each
 name maps to a specific gate.
 
@@ -157,7 +170,9 @@ Two readings that decide the whole branch:
 ### Step 4. Establish framework and rendering mode
 
 **Detect this, do not ask for it.** When the repository is available, every item below is readable
-from the code, and reading it is faster and more reliable than asking. Developers routinely answer
+from the code, and reading it is faster and more reliable than asking. Detection does not replace
+step 3: the card still comes first, because it reports the deployed build rather than the branch you
+are reading. Developers routinely answer
 "Next.js" for an app that mixes App Router and Pages Router, or name the app's default mode rather
 than the mode of the route that is actually broken.
 
@@ -199,11 +214,17 @@ tags. Everything else follows from mode and fetch layer.
 | Mode | `ssr` | Hash travels via | Updates arrive as |
 |---|---|---|---|
 | CSR + REST | `false` | postMessage, into `stackSdk` | `onEntryChange` refetch, no reload |
-| SSR + REST | `true` | `live_preview` query parameter | full iframe reload |
+| SSR + REST | `true` | `live_preview` query parameter | full iframe reload, driven by the parent. `onEntryChange` subscribers **never fire** in this mode |
 | CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch, manual host swap |
 | SSR + GraphQL | `true` | `request.query.live_preview` | full reload, manual host swap |
 | SSG | `false` | postMessage | runs as CSR at runtime |
 
+**`onEntryChange` is inert under `ssr: true`.** The SDK guards its entry-change dispatch on `!ssr`,
+so any subscriber registered in an SSR app never runs. Registering one to trigger a refetch or
+`router.refresh()` produces a callback that looks correct and does nothing. Under `ssr: true` the
+update path is the parent reloading the iframe with the new hash; the app's only job is to read the
+hash off that request. If you want client-driven refresh, the route has to be CSR (`ssr: false`).
+
 `stackSdk` is mandatory in CSR and is what the SDK uses to default `ssr`. A CSR app that omits it
 silently gets SSR behaviour; an SSG site initialised with `ssr: true` gives blank screens rather
 than an error. Two mode traps to check before prescribing: **SSR** needs a per-request Stack
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
index 2fa0f7a..e3bea67 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -71,13 +71,16 @@ Collected in the order set out below, not all at once. Never ask for delivery to
 
 ## Workflow Summary
 
-1. Identify the product.
-2. Setup or regression.
-3. Read the Onboarding Check.
-4. Detect framework and rendering mode from the code.
-5. Collect only the evidence detection could not supply.
-6. Localise to one contract.
-7. Fix, verify, or hand to Contentstack Support.
+Work these as a checklist and report it back ticked. An unticked step is a visible gap the user
+can see and question; a silently skipped step is how a wrong diagnosis gets past both of you.
+
+- [ ] 1. Identify the product.
+- [ ] 2. Setup or regression.
+- [ ] 3. Read the Onboarding Check. Not skippable whenever a preview pane renders.
+- [ ] 4. Detect framework and rendering mode from the code.
+- [ ] 5. Collect only the evidence detection could not supply.
+- [ ] 6. Localise to one contract.
+- [ ] 7. Fix, verify, or hand to Contentstack Support.
 
 ## Instructions
 
@@ -87,6 +90,11 @@ whose answers you could already have had.
 **Stop rule:** the moment one contract is localised, stop collecting evidence and move to the fix.
 Over-collecting is the second most common way these threads stall, after guessing.
 
+**Falsification rule:** before acting on a diagnosis, name the one artifact that would contradict
+it, and go get it. Confidence is the cue to do this, not the excuse to skip it. The commonest miss is
+a mode assumption: the code reads one way, and the Onboarding Check card or the network tab says
+otherwise. When they disagree, the observed behaviour wins over the intended one.
+
 ### Step 1. Which product?
 
 Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
@@ -118,6 +126,11 @@ stack settings change, a role change, a new environment, a CDN or hosting change
 Ask for a **screenshot** of the floating status card in the preview panel. Do this before any other
 diagnostic question. The product already ran the check you are about to run by hand.
 
+**This step is not skippable when a pane renders at all, and repository access does not excuse it.**
+Step 4 reads the code and tells you what the integration *intends*; the card tells you what the editor
+*observed* on the actual deployed build. They can disagree, most often on rendering mode, and when
+they do the card is the one that reflects reality. Do step 3 first, then let step 4 explain it.
+
 Ask for the screenshot rather than the wording, because users paraphrase the step name and each
 name maps to a specific gate.
 
@@ -157,7 +170,9 @@ Two readings that decide the whole branch:
 ### Step 4. Establish framework and rendering mode
 
 **Detect this, do not ask for it.** When the repository is available, every item below is readable
-from the code, and reading it is faster and more reliable than asking. Developers routinely answer
+from the code, and reading it is faster and more reliable than asking. Detection does not replace
+step 3: the card still comes first, because it reports the deployed build rather than the branch you
+are reading. Developers routinely answer
 "Next.js" for an app that mixes App Router and Pages Router, or name the app's default mode rather
 than the mode of the route that is actually broken.
 
@@ -199,11 +214,17 @@ tags. Everything else follows from mode and fetch layer.
 | Mode | `ssr` | Hash travels via | Updates arrive as |
 |---|---|---|---|
 | CSR + REST | `false` | postMessage, into `stackSdk` | `onEntryChange` refetch, no reload |
-| SSR + REST | `true` | `live_preview` query parameter | full iframe reload |
+| SSR + REST | `true` | `live_preview` query parameter | full iframe reload, driven by the parent. `onEntryChange` subscribers **never fire** in this mode |
 | CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch, manual host swap |
 | SSR + GraphQL | `true` | `request.query.live_preview` | full reload, manual host swap |
 | SSG | `false` | postMessage | runs as CSR at runtime |
 
+**`onEntryChange` is inert under `ssr: true`.** The SDK guards its entry-change dispatch on `!ssr`,
+so any subscriber registered in an SSR app never runs. Registering one to trigger a refetch or
+`router.refresh()` produces a callback that looks correct and does nothing. Under `ssr: true` the
+update path is the parent reloading the iframe with the new hash; the app's only job is to read the
+hash off that request. If you want client-driven refresh, the route has to be CSR (`ssr: false`).
+
 `stackSdk` is mandatory in CSR and is what the SDK uses to default `ssr`. A CSR app that omits it
 silently gets SSR behaviour; an SSG site initialised with `ssr: true` gives blank screens rather
 than an error. Two mode traps to check before prescribing: **SSR** needs a per-request Stack
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
index a5c552f..46a4016 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -11,11 +11,19 @@ Diagnose against this file. Use `frameworks.md` only for where `init()` is allow
 | Mode | `ssr` | How the hash travels | How updates arrive | Hard requirement |
 |---|---|---|---|---|
 | CSR + REST | `false` | postMessage; the SDK injects it into `stackSdk` | `onEntryChange` / `onLiveEdit` refetch, no reload | `stackSdk` is mandatory |
-| SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload | a fresh Delivery SDK instance per request |
+| SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload, parent-driven; `onEntryChange` subscribers never fire | a fresh Delivery SDK instance per request |
 | CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch | manual host swap plus headers |
 | SSR + GraphQL | `true` | `request.query.live_preview` | full iframe reload | manual host swap plus headers |
 | SSG | `false` | postMessage | runs in CSR mode at runtime | `stackSdk`, and `init()` must be browser-only |
 
+## `onEntryChange` does not fire under `ssr: true`
+
+The SDK dispatches entry-change events only when `ssr` is `false`. In SSR mode the parent reloads
+the iframe with the new hash and the app never receives a client-side event. A subscriber registered
+in an SSR app is silently inert, so a `router.refresh()` or refetch wired into it never runs, and the
+integration looks correct while doing nothing on edit. Drive SSR updates from the request, not from a
+subscriber; if client-driven refresh is wanted, the route must be CSR.
+
 ## How `ssr` is resolved
 
 Precedence is `stackSdk.live_preview.ssr`, then `init({ ssr })`, then the automatic default.

From 7caef3aa121d9136cbc5c9e085878fd7ca195d16 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Fri, 4 Sep 2026 16:07:04 +0530
Subject: [PATCH 03/21] fix(skills): add the reproduction rule; no code change
 without a reproduced failure

Pairs with the stop rule. Before editing application code the agent must
state the contract it believes is broken, the evidence, and the command or
action that reproduces the failure. Without a reproduction it has a
hypothesis, not a diagnosis, and keeps collecting. Step 7 now gates on
this, and defines verification as the reproduction step run again with the
opposite result. From the same dry run as the previous commit.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../SKILL.md                                        | 13 +++++++++++--
 ...live-preview-visual-editor-support-assistant.mdc | 13 +++++++++++--
 .../SKILL.md                                        | 13 +++++++++++--
 3 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
index d3bd1b2..d4e1d20 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -92,6 +92,12 @@ it, and go get it. Confidence is the cue to do this, not the excuse to skip it.
 a mode assumption: the code reads one way, and the Onboarding Check card or the network tab says
 otherwise. When they disagree, the observed behaviour wins over the intended one.
 
+**Reproduction rule:** no code change without a reproduced failure. Before editing application code,
+state the contract you believe is broken, the evidence for it, and the command or action that
+reproduces the failure. If you cannot reproduce it, you have a hypothesis, not a diagnosis. Keep
+collecting. A fix that "works" without a reproduced baseline may be working for a reason you have not
+identified, and you will not know which.
+
 ### Step 1. Which product?
 
 Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
@@ -329,8 +335,11 @@ ordered checks.
 
 ### Step 7. Fix, verify, or hand to Contentstack Support
 
-Propose the smallest correct change at the right layer: init, tagging, fetch, cache boundary,
-routing, or stack configuration. Then give one verification the user runs themselves.
+Before proposing any change, satisfy the reproduction rule: contract, evidence, and the action that
+reproduces the failure, stated in that order. Then propose the smallest correct change at the right
+layer: init, tagging, fetch, cache boundary, routing, or stack configuration, and give one verification
+the user runs themselves. The verification is the reproduction step run again with the opposite
+result.
 
 Some causes sit outside the user's application entirely: stack provisioning, plan gating, and
 browser policy. Recognising one early beats any workaround, because no change to the site can
diff --git a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
index f914231..37bc57c 100644
--- a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
+++ b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
@@ -95,6 +95,12 @@ it, and go get it. Confidence is the cue to do this, not the excuse to skip it.
 a mode assumption: the code reads one way, and the Onboarding Check card or the network tab says
 otherwise. When they disagree, the observed behaviour wins over the intended one.
 
+**Reproduction rule:** no code change without a reproduced failure. Before editing application code,
+state the contract you believe is broken, the evidence for it, and the command or action that
+reproduces the failure. If you cannot reproduce it, you have a hypothesis, not a diagnosis. Keep
+collecting. A fix that "works" without a reproduced baseline may be working for a reason you have not
+identified, and you will not know which.
+
 ### Step 1. Which product?
 
 Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
@@ -332,8 +338,11 @@ ordered checks.
 
 ### Step 7. Fix, verify, or hand to Contentstack Support
 
-Propose the smallest correct change at the right layer: init, tagging, fetch, cache boundary,
-routing, or stack configuration. Then give one verification the user runs themselves.
+Before proposing any change, satisfy the reproduction rule: contract, evidence, and the action that
+reproduces the failure, stated in that order. Then propose the smallest correct change at the right
+layer: init, tagging, fetch, cache boundary, routing, or stack configuration, and give one verification
+the user runs themselves. The verification is the reproduction step run again with the opposite
+result.
 
 Some causes sit outside the user's application entirely: stack provisioning, plan gating, and
 browser policy. Recognising one early beats any workaround, because no change to the site can
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
index e3bea67..2b1777f 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -95,6 +95,12 @@ it, and go get it. Confidence is the cue to do this, not the excuse to skip it.
 a mode assumption: the code reads one way, and the Onboarding Check card or the network tab says
 otherwise. When they disagree, the observed behaviour wins over the intended one.
 
+**Reproduction rule:** no code change without a reproduced failure. Before editing application code,
+state the contract you believe is broken, the evidence for it, and the command or action that
+reproduces the failure. If you cannot reproduce it, you have a hypothesis, not a diagnosis. Keep
+collecting. A fix that "works" without a reproduced baseline may be working for a reason you have not
+identified, and you will not know which.
+
 ### Step 1. Which product?
 
 Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
@@ -332,8 +338,11 @@ ordered checks.
 
 ### Step 7. Fix, verify, or hand to Contentstack Support
 
-Propose the smallest correct change at the right layer: init, tagging, fetch, cache boundary,
-routing, or stack configuration. Then give one verification the user runs themselves.
+Before proposing any change, satisfy the reproduction rule: contract, evidence, and the action that
+reproduces the failure, stated in that order. Then propose the smallest correct change at the right
+layer: init, tagging, fetch, cache boundary, routing, or stack configuration, and give one verification
+the user runs themselves. The verification is the reproduction step run again with the opposite
+result.
 
 Some causes sit outside the user's application entirely: stack provisioning, plan gating, and
 browser policy. Recognising one early beats any workaround, because no change to the site can

From 2440e8e835a30058ea183970954a00fefb4ae0fd Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Fri, 4 Sep 2026 16:12:27 +0530
Subject: [PATCH 04/21] fix(skills): add the transition rule; any regression
 restarts at step 2

Worked then broke, a gate that advanced then regressed, a new error
replacing an old one: each restarts at step 2 with "what changed since it
last worked", and the answer must include the agent's own edits since the
last known-good state, not only the user's. Step 2 now says the question
applies to every mid-session transition, not only at intake. From the same
dry run as the previous two commits.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../SKILL.md                                          | 11 ++++++++++-
 ...s-live-preview-visual-editor-support-assistant.mdc | 11 ++++++++++-
 .../SKILL.md                                          | 11 ++++++++++-
 3 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
index d4e1d20..6347c8d 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -98,6 +98,12 @@ reproduces the failure. If you cannot reproduce it, you have a hypothesis, not a
 collecting. A fix that "works" without a reproduced baseline may be working for a reason you have not
 identified, and you will not know which.
 
+**Transition rule:** any transition restarts at step 2. Worked then broke, a gate that advanced then
+regressed, a new error replacing an old one: each is a regression from a known state, and the first
+question is what changed since it last worked. Include your own edits in that question, not only the
+user's. Mid-session, the change most likely to have caused a transition is the one you just made, and
+it is also the one you are least likely to suspect.
+
 ### Step 1. Which product?
 
 Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
@@ -122,7 +128,10 @@ documentation for the framework and mode. Do not reconstruct setup steps from me
 here when the documented setup is in place and something still fails.
 
 **Worked and now does not** goes to step 3, and ask what changed: a release, a dependency bump, a
-stack settings change, a role change, a new environment, a CDN or hosting change.
+stack settings change, a role change, a new environment, a CDN or hosting change. This question is not
+only for intake. Every transition during the session, such as a gate that advanced and then regressed
+or a new error replacing the old one, comes back here, and the list of changes must include every
+edit you made since the last known-good state, not only the user's.
 
 ### Step 3. Read the Onboarding Check
 
diff --git a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
index 37bc57c..e51be10 100644
--- a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
+++ b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
@@ -101,6 +101,12 @@ reproduces the failure. If you cannot reproduce it, you have a hypothesis, not a
 collecting. A fix that "works" without a reproduced baseline may be working for a reason you have not
 identified, and you will not know which.
 
+**Transition rule:** any transition restarts at step 2. Worked then broke, a gate that advanced then
+regressed, a new error replacing an old one: each is a regression from a known state, and the first
+question is what changed since it last worked. Include your own edits in that question, not only the
+user's. Mid-session, the change most likely to have caused a transition is the one you just made, and
+it is also the one you are least likely to suspect.
+
 ### Step 1. Which product?
 
 Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
@@ -125,7 +131,10 @@ documentation for the framework and mode. Do not reconstruct setup steps from me
 here when the documented setup is in place and something still fails.
 
 **Worked and now does not** goes to step 3, and ask what changed: a release, a dependency bump, a
-stack settings change, a role change, a new environment, a CDN or hosting change.
+stack settings change, a role change, a new environment, a CDN or hosting change. This question is not
+only for intake. Every transition during the session, such as a gate that advanced and then regressed
+or a new error replacing the old one, comes back here, and the list of changes must include every
+edit you made since the last known-good state, not only the user's.
 
 ### Step 3. Read the Onboarding Check
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
index 2b1777f..72adbac 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -101,6 +101,12 @@ reproduces the failure. If you cannot reproduce it, you have a hypothesis, not a
 collecting. A fix that "works" without a reproduced baseline may be working for a reason you have not
 identified, and you will not know which.
 
+**Transition rule:** any transition restarts at step 2. Worked then broke, a gate that advanced then
+regressed, a new error replacing an old one: each is a regression from a known state, and the first
+question is what changed since it last worked. Include your own edits in that question, not only the
+user's. Mid-session, the change most likely to have caused a transition is the one you just made, and
+it is also the one you are least likely to suspect.
+
 ### Step 1. Which product?
 
 Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
@@ -125,7 +131,10 @@ documentation for the framework and mode. Do not reconstruct setup steps from me
 here when the documented setup is in place and something still fails.
 
 **Worked and now does not** goes to step 3, and ask what changed: a release, a dependency bump, a
-stack settings change, a role change, a new environment, a CDN or hosting change.
+stack settings change, a role change, a new environment, a CDN or hosting change. This question is not
+only for intake. Every transition during the session, such as a gate that advanced and then regressed
+or a new error replacing the old one, comes back here, and the list of changes must include every
+edit you made since the last known-good state, not only the user's.
 
 ### Step 3. Read the Onboarding Check
 

From 62515b35cd30f735aecb2cf28c68f3577439bbc2 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Fri, 4 Sep 2026 16:48:22 +0530
Subject: [PATCH 05/21] fix(skills): document the Visual Editor onboarding
 check and the mode: "builder" requirement

Two gaps from the dry run. The skill described Live Preview's five-gate
card and Timeline's three-gate card and said Visual Editor needs "Live
Preview plus edit tags". Both were incomplete.

- Visual Editor runs its own six-item check: Configure environment
  (Default Environment, Base URL), Install SDK, Verify Mode for Live
  Preview, Preview Token. Items are evaluated independently and each shows
  its own status, unlike the single-card checks. The "only one step is ever
  shown" inference is now scoped to Live Preview and Timeline.
- Verify Mode passes only on mode: "builder"; mode: "preview" fails it, so
  edit tags alone do not produce a canvas. The product table, step 3,
  contract 2 and the edit-tags FAQ entry now say Visual Editor needs
  working Live Preview, edit tags, and mode: "builder".
- Base URL is origin-exact against the previewed page: scheme and host
  must match, and the frame can render while this item fails.

Conditions taken from the editor's onboarding hook, not inferred.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../references/onboarding-check.md            | 47 +++++++++++++++----
 .../references/onboarding-check.md            | 47 +++++++++++++++----
 2 files changed, 78 insertions(+), 16 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index 89566f9..f68e86f 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -1,17 +1,21 @@
 # The Onboarding Check
 
-Every visual experience product ships a setup check that runs automatically when the preview panel
-opens and reports its result in a small floating status card. It is the highest-yield thing to ask
+Every visual experience product ships a setup check that runs automatically when its panel opens.
+There are **three** of them, and they differ in both gates and shape: Live Preview shows one card
+with the first failing gate; Visual Editor shows a six-item list with a status per item; Timeline
+shows one card with three gates. Confirm which product the user is in before reading anything below. It is the highest-yield thing to ask
 about, because it has already run the diagnosis the user is asking you to do.
 
 **Always ask for a screenshot of this card before asking anything else.** The step name on it
 localises the problem to one gate, and because of how the check is structured, it also tells you
 everything that already passed.
 
-## The property that makes it powerful
+## The property that makes the Live Preview and Timeline cards powerful
 
-The gates are evaluated as a single ordered chain, and it stops at the first failure. Only one
-step is ever shown.
+For Live Preview and Timeline the gates are evaluated as a single ordered chain that stops at the
+first failure, so only one step is ever shown. **Visual Editor is different**: every item is evaluated
+independently and shown with its own status, so read the whole list rather than one card. The
+inference below applies to the single-card checks only.
 
 So a card reading "Preview Service Not Enabled" is not just one fact. It proves the website loaded
 in the frame, the SDK initialised, and the SDK version is supported. Three contracts are already
@@ -37,9 +41,35 @@ The exact body text is worth quoting back to users, because they often paraphras
 something ambiguous. Gate 1 reads "Ensure the website is live and accessible via Contentstack
 origins." Gate 4 reads "Please enable the Preview Service for a seamless live preview experience."
 
+## Visual Editor
+
+Visual Editor runs its own check, not Live Preview's. Six items, shown as a list with a status per
+item. Every item is evaluated independently (`steps.every(isComplete)`), so a partially green list is
+the normal way it looks while something is wrong, and the failing items are the ones to read. Card
+text as observed in the UI; the identifier is the implementation's step id.
+
+| # | Item (card text) | Step id | Passes when |
+|---|---|---|---|
+| 1 | Configure environment | `ENVIRONMENT` | both sub-steps below pass |
+| 1a | Default Environment | `LP_DEFAULT_ENV` | the environment in the preview URL's parameters exists on the stack |
+| 1b | Base URL | `BASE_URL` | that environment has a Base URL for the current locale, and its **origin matches the origin of the page being previewed**. A Base URL on a different host or scheme fails here even though the page loads |
+| 2 | Install SDK | `LP_SDK_VERSION` | Live Preview Utils major version is 3 or higher |
+| 3 | Verify Mode for Live Preview | `LP_SDK_INIT_MODE` | `init()` was called with `mode: "builder"`. **`mode: "preview"` fails this gate.** Edit tags alone do not get you a canvas |
+| 4 | Preview Token | `LP_SERVICE` | after the init handshake, the editor polls the Preview Service and it responds; the site is fetching through the Preview Service, not the delivery CDN |
+
+Two consequences worth stating:
+
+- **Visual Editor needs three things, not two.** Working Live Preview, edit tags, and `mode: "builder"`
+  in `init()`. The product table in SKILL.md says so; a customer who followed a Live Preview guide has
+  `mode: "preview"` and will fail item 3 with everything else green.
+- **Item 1b is origin-exact.** The Base URL must match the previewed page's scheme and host. A Base
+  URL of `https://www.example.com` with the site served at `https://example.com`, or `http` versus
+  `https`, fails the check while the frame still renders.
+
 ## Timeline
 
-Timeline runs its own check with three gates, not the five above. Do not map one onto the other.
+Timeline runs its own check with three gates, not Live Preview's five or Visual Editor's six. Do not
+map any of the three onto another.
 
 | # | Card | On failure | Meaning |
 |---|---|---|---|
@@ -106,5 +136,6 @@ Ask for the screenshot rather than the wording. Users paraphrase the step name i
 one, and since each name maps to a specific gate, a paraphrase can send you down the wrong branch.
 
 If they cannot screenshot it, ask for the exact step name and body text as displayed, and confirm
-which product they are in, because Live Preview and Timeline share a visual style but not a set of
-gates.
+which product they are in. Live Preview and Timeline share a single-card style but not a set of
+gates, and Visual Editor's is a six-item list; a paraphrased step name from the wrong product sends
+you down the wrong branch.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index 89566f9..f68e86f 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -1,17 +1,21 @@
 # The Onboarding Check
 
-Every visual experience product ships a setup check that runs automatically when the preview panel
-opens and reports its result in a small floating status card. It is the highest-yield thing to ask
+Every visual experience product ships a setup check that runs automatically when its panel opens.
+There are **three** of them, and they differ in both gates and shape: Live Preview shows one card
+with the first failing gate; Visual Editor shows a six-item list with a status per item; Timeline
+shows one card with three gates. Confirm which product the user is in before reading anything below. It is the highest-yield thing to ask
 about, because it has already run the diagnosis the user is asking you to do.
 
 **Always ask for a screenshot of this card before asking anything else.** The step name on it
 localises the problem to one gate, and because of how the check is structured, it also tells you
 everything that already passed.
 
-## The property that makes it powerful
+## The property that makes the Live Preview and Timeline cards powerful
 
-The gates are evaluated as a single ordered chain, and it stops at the first failure. Only one
-step is ever shown.
+For Live Preview and Timeline the gates are evaluated as a single ordered chain that stops at the
+first failure, so only one step is ever shown. **Visual Editor is different**: every item is evaluated
+independently and shown with its own status, so read the whole list rather than one card. The
+inference below applies to the single-card checks only.
 
 So a card reading "Preview Service Not Enabled" is not just one fact. It proves the website loaded
 in the frame, the SDK initialised, and the SDK version is supported. Three contracts are already
@@ -37,9 +41,35 @@ The exact body text is worth quoting back to users, because they often paraphras
 something ambiguous. Gate 1 reads "Ensure the website is live and accessible via Contentstack
 origins." Gate 4 reads "Please enable the Preview Service for a seamless live preview experience."
 
+## Visual Editor
+
+Visual Editor runs its own check, not Live Preview's. Six items, shown as a list with a status per
+item. Every item is evaluated independently (`steps.every(isComplete)`), so a partially green list is
+the normal way it looks while something is wrong, and the failing items are the ones to read. Card
+text as observed in the UI; the identifier is the implementation's step id.
+
+| # | Item (card text) | Step id | Passes when |
+|---|---|---|---|
+| 1 | Configure environment | `ENVIRONMENT` | both sub-steps below pass |
+| 1a | Default Environment | `LP_DEFAULT_ENV` | the environment in the preview URL's parameters exists on the stack |
+| 1b | Base URL | `BASE_URL` | that environment has a Base URL for the current locale, and its **origin matches the origin of the page being previewed**. A Base URL on a different host or scheme fails here even though the page loads |
+| 2 | Install SDK | `LP_SDK_VERSION` | Live Preview Utils major version is 3 or higher |
+| 3 | Verify Mode for Live Preview | `LP_SDK_INIT_MODE` | `init()` was called with `mode: "builder"`. **`mode: "preview"` fails this gate.** Edit tags alone do not get you a canvas |
+| 4 | Preview Token | `LP_SERVICE` | after the init handshake, the editor polls the Preview Service and it responds; the site is fetching through the Preview Service, not the delivery CDN |
+
+Two consequences worth stating:
+
+- **Visual Editor needs three things, not two.** Working Live Preview, edit tags, and `mode: "builder"`
+  in `init()`. The product table in SKILL.md says so; a customer who followed a Live Preview guide has
+  `mode: "preview"` and will fail item 3 with everything else green.
+- **Item 1b is origin-exact.** The Base URL must match the previewed page's scheme and host. A Base
+  URL of `https://www.example.com` with the site served at `https://example.com`, or `http` versus
+  `https`, fails the check while the frame still renders.
+
 ## Timeline
 
-Timeline runs its own check with three gates, not the five above. Do not map one onto the other.
+Timeline runs its own check with three gates, not Live Preview's five or Visual Editor's six. Do not
+map any of the three onto another.
 
 | # | Card | On failure | Meaning |
 |---|---|---|---|
@@ -106,5 +136,6 @@ Ask for the screenshot rather than the wording. Users paraphrase the step name i
 one, and since each name maps to a specific gate, a paraphrase can send you down the wrong branch.
 
 If they cannot screenshot it, ask for the exact step name and body text as displayed, and confirm
-which product they are in, because Live Preview and Timeline share a visual style but not a set of
-gates.
+which product they are in. Live Preview and Timeline share a single-card style but not a set of
+gates, and Visual Editor's is a six-item list; a paraphrased step name from the wrong product sends
+you down the wrong branch.

From 096d026a568e813b00cb0d938fb61ee6bf3466af Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Fri, 4 Sep 2026 16:50:56 +0530
Subject: [PATCH 06/21] fix(skills): state the mode: "builder" requirement in
 SKILL.md and the edit-tags entry

Completes the previous commit, which landed only the onboarding-check.md
half before a bad anchor stopped the script. The product table, step 3,
the step-6 contract-2 note and the edit-tags FAQ entry now all say Visual
Editor needs working Live Preview, edit tags, and mode: "builder"; step 3
describes the six-item Visual Editor list alongside the two single-card
checks instead of treating Live Preview's chain as universal.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../SKILL.md                                  | 22 ++++++++++++-------
 .../references/faq-setup.md                   |  2 +-
 ...review-visual-editor-support-assistant.mdc | 22 ++++++++++++-------
 .../SKILL.md                                  | 22 ++++++++++++-------
 .../references/faq-setup.md                   |  2 +-
 5 files changed, 44 insertions(+), 26 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
index 6347c8d..db60633 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -112,7 +112,7 @@ Onboarding Check, or a failure set.
 | Product | What it is | Notes |
 |---|---|---|
 | **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
-| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags. Not a separate integration. |
+| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags **plus** `mode: "builder"` in `init()`. `mode: "preview"` fails its Verify Mode gate even with tags present. Not a separate integration. |
 | **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
 | **Preview Sharing** | Share a preview link externally | Plan-gated. |
 
@@ -146,10 +146,11 @@ they do the card is the one that reflects reality. Do step 3 first, then let ste
 Ask for the screenshot rather than the wording, because users paraphrase the step name and each
 name maps to a specific gate.
 
-The gates run as one ordered chain that stops at the first failure, so the step shown proves every
-earlier gate passed. Full gate list, meanings, and the Timeline variant are in
-[references/onboarding-check.md](references/onboarding-check.md). In short, for Live Preview and
-Visual Editor:
+Three products, three different checks. Confirm the product first. Full gate lists and meanings are
+in [references/onboarding-check.md](references/onboarding-check.md).
+
+**Live Preview** shows one card. The gates run as one ordered chain that stops at the first failure,
+so the step shown proves every earlier gate passed:
 
 | Card | Localises to |
 |---|---|
@@ -160,8 +161,13 @@ Visual Editor:
 | Default Environment Not Set | Setup is fine; no default preview environment on the stack |
 | Setup Complete | Reachability, handshake, version and Preview Service are all fine |
 
-**Timeline runs a different check.** Three gates, not these five, so do not map a Timeline card
-onto the table above:
+**Visual Editor shows a six-item list, not a card.** Every item is evaluated on its own and carries
+its own status, so read the failing items rather than the first one. Configure environment (Default
+Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
+customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
+Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
+
+**Timeline runs a third check.** Three gates, so do not map a Timeline card onto either table:
 
 | Card | Localises to |
 |---|---|
@@ -310,7 +316,7 @@ addEditableTags(entry, contentTypeUid, true, locale);
 <h1 {...data.$?.title}>{data.title}</h1>
 ```
 
-`mode: "builder"` does not generate tags; only `addEditableTags()` does, it mutates the entry and
+`mode: "builder"` does not generate tags; only `addEditableTags()` does, though `mode: "builder"` is still required because Visual Editor's Verify Mode gate fails on `mode: "preview"`, it mutates the entry and
 returns nothing, and the third argument must be `true` for React and JSX. Mirror the data path
 exactly, because references come back as arrays: `post.author[0].$?.name`, not
 `post.$?.author.name`. Tag the leaf element, one `data-cslp` per element, and call it on referenced
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
index 6886b7f..a960ae6 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
@@ -71,7 +71,7 @@ contract tells you which section to read; this file tells you what to do.
 - **symptom**: Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar. Clicking the canvas does nothing, or selects the wrong (parent) element. `entry.$` / `post.$` is `undefined` in the app, or `data-cslp` renders as literal text instead of an attribute. Live Preview auto-refresh often still works, which makes it look like a Visual Editor bug.
 - **frameworks**: React, Next.js, Vue, Angular, Gatsby, Blazor/.NET, jQuery
 - **rendering_modes**: any
-- **root_cause**: Tags need two independent things and teams usually do only one: `addEditableTags()` must run on every fetched entry, **and** the generated `$` attributes must be spread onto the DOM elements that render each field. `mode: "builder"` does not generate tags — it only controls where **Start Editing** redirects. Four ways this goes wrong: the call is missing entirely (commonly commented out during a migration); `tagsAsObject` is `false` or omitted, producing a `data-cslp` string React cannot spread; the content type **title** is passed instead of its **uid**; or the call is correct but nothing spreads the result into the markup.
+- **root_cause**: Tags need two independent things and teams usually do only one: `addEditableTags()` must run on every fetched entry, **and** the generated `$` attributes must be spread onto the DOM elements that render each field. `mode: "builder"` does not generate tags, but it is still required: Visual Editor's Verify Mode gate fails on `mode: "preview"`, so tags alone do not produce a canvas. Four ways this goes wrong: the call is missing entirely (commonly commented out during a migration); `tagsAsObject` is `false` or omitted, producing a `data-cslp` string React cannot spread; the content type **title** is passed instead of its **uid**; or the call is correct but nothing spreads the result into the markup.
 - **fix**:
   1. Call it on every entry right after fetching, including referenced entries: `addEditableTags(entry, contentTypeUid, true, locale)`. The third argument must be `true` for React and JSX.
   2. Pass the content type **uid**, not its display title.
diff --git a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
index e51be10..c051f81 100644
--- a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
+++ b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
@@ -115,7 +115,7 @@ Onboarding Check, or a failure set.
 | Product | What it is | Notes |
 |---|---|---|
 | **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
-| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags. Not a separate integration. |
+| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags **plus** `mode: "builder"` in `init()`. `mode: "preview"` fails its Verify Mode gate even with tags present. Not a separate integration. |
 | **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
 | **Preview Sharing** | Share a preview link externally | Plan-gated. |
 
@@ -149,10 +149,11 @@ they do the card is the one that reflects reality. Do step 3 first, then let ste
 Ask for the screenshot rather than the wording, because users paraphrase the step name and each
 name maps to a specific gate.
 
-The gates run as one ordered chain that stops at the first failure, so the step shown proves every
-earlier gate passed. Full gate list, meanings, and the Timeline variant are in
-[references/onboarding-check.md](references/onboarding-check.md). In short, for Live Preview and
-Visual Editor:
+Three products, three different checks. Confirm the product first. Full gate lists and meanings are
+in [references/onboarding-check.md](references/onboarding-check.md).
+
+**Live Preview** shows one card. The gates run as one ordered chain that stops at the first failure,
+so the step shown proves every earlier gate passed:
 
 | Card | Localises to |
 |---|---|
@@ -163,8 +164,13 @@ Visual Editor:
 | Default Environment Not Set | Setup is fine; no default preview environment on the stack |
 | Setup Complete | Reachability, handshake, version and Preview Service are all fine |
 
-**Timeline runs a different check.** Three gates, not these five, so do not map a Timeline card
-onto the table above:
+**Visual Editor shows a six-item list, not a card.** Every item is evaluated on its own and carries
+its own status, so read the failing items rather than the first one. Configure environment (Default
+Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
+customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
+Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
+
+**Timeline runs a third check.** Three gates, so do not map a Timeline card onto either table:
 
 | Card | Localises to |
 |---|---|
@@ -313,7 +319,7 @@ addEditableTags(entry, contentTypeUid, true, locale);
 <h1 {...data.$?.title}>{data.title}</h1>
 ```
 
-`mode: "builder"` does not generate tags; only `addEditableTags()` does, it mutates the entry and
+`mode: "builder"` does not generate tags; only `addEditableTags()` does, though `mode: "builder"` is still required because Visual Editor's Verify Mode gate fails on `mode: "preview"`, it mutates the entry and
 returns nothing, and the third argument must be `true` for React and JSX. Mirror the data path
 exactly, because references come back as arrays: `post.author[0].$?.name`, not
 `post.$?.author.name`. Tag the leaf element, one `data-cslp` per element, and call it on referenced
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
index 72adbac..0171b6f 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -115,7 +115,7 @@ Onboarding Check, or a failure set.
 | Product | What it is | Notes |
 |---|---|---|
 | **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
-| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags. Not a separate integration. |
+| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags **plus** `mode: "builder"` in `init()`. `mode: "preview"` fails its Verify Mode gate even with tags present. Not a separate integration. |
 | **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
 | **Preview Sharing** | Share a preview link externally | Plan-gated. |
 
@@ -149,10 +149,11 @@ they do the card is the one that reflects reality. Do step 3 first, then let ste
 Ask for the screenshot rather than the wording, because users paraphrase the step name and each
 name maps to a specific gate.
 
-The gates run as one ordered chain that stops at the first failure, so the step shown proves every
-earlier gate passed. Full gate list, meanings, and the Timeline variant are in
-[references/onboarding-check.md](references/onboarding-check.md). In short, for Live Preview and
-Visual Editor:
+Three products, three different checks. Confirm the product first. Full gate lists and meanings are
+in [references/onboarding-check.md](references/onboarding-check.md).
+
+**Live Preview** shows one card. The gates run as one ordered chain that stops at the first failure,
+so the step shown proves every earlier gate passed:
 
 | Card | Localises to |
 |---|---|
@@ -163,8 +164,13 @@ Visual Editor:
 | Default Environment Not Set | Setup is fine; no default preview environment on the stack |
 | Setup Complete | Reachability, handshake, version and Preview Service are all fine |
 
-**Timeline runs a different check.** Three gates, not these five, so do not map a Timeline card
-onto the table above:
+**Visual Editor shows a six-item list, not a card.** Every item is evaluated on its own and carries
+its own status, so read the failing items rather than the first one. Configure environment (Default
+Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
+customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
+Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
+
+**Timeline runs a third check.** Three gates, so do not map a Timeline card onto either table:
 
 | Card | Localises to |
 |---|---|
@@ -313,7 +319,7 @@ addEditableTags(entry, contentTypeUid, true, locale);
 <h1 {...data.$?.title}>{data.title}</h1>
 ```
 
-`mode: "builder"` does not generate tags; only `addEditableTags()` does, it mutates the entry and
+`mode: "builder"` does not generate tags; only `addEditableTags()` does, though `mode: "builder"` is still required because Visual Editor's Verify Mode gate fails on `mode: "preview"`, it mutates the entry and
 returns nothing, and the third argument must be `true` for React and JSX. Mirror the data path
 exactly, because references come back as arrays: `post.author[0].$?.name`, not
 `post.$?.author.name`. Tag the leaf element, one `data-cslp` per element, and call it on referenced
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
index 6886b7f..a960ae6 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
@@ -71,7 +71,7 @@ contract tells you which section to read; this file tells you what to do.
 - **symptom**: Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar. Clicking the canvas does nothing, or selects the wrong (parent) element. `entry.$` / `post.$` is `undefined` in the app, or `data-cslp` renders as literal text instead of an attribute. Live Preview auto-refresh often still works, which makes it look like a Visual Editor bug.
 - **frameworks**: React, Next.js, Vue, Angular, Gatsby, Blazor/.NET, jQuery
 - **rendering_modes**: any
-- **root_cause**: Tags need two independent things and teams usually do only one: `addEditableTags()` must run on every fetched entry, **and** the generated `$` attributes must be spread onto the DOM elements that render each field. `mode: "builder"` does not generate tags — it only controls where **Start Editing** redirects. Four ways this goes wrong: the call is missing entirely (commonly commented out during a migration); `tagsAsObject` is `false` or omitted, producing a `data-cslp` string React cannot spread; the content type **title** is passed instead of its **uid**; or the call is correct but nothing spreads the result into the markup.
+- **root_cause**: Tags need two independent things and teams usually do only one: `addEditableTags()` must run on every fetched entry, **and** the generated `$` attributes must be spread onto the DOM elements that render each field. `mode: "builder"` does not generate tags, but it is still required: Visual Editor's Verify Mode gate fails on `mode: "preview"`, so tags alone do not produce a canvas. Four ways this goes wrong: the call is missing entirely (commonly commented out during a migration); `tagsAsObject` is `false` or omitted, producing a `data-cslp` string React cannot spread; the content type **title** is passed instead of its **uid**; or the call is correct but nothing spreads the result into the markup.
 - **fix**:
   1. Call it on every entry right after fetching, including referenced entries: `addEditableTags(entry, contentTypeUid, true, locale)`. The third argument must be `true` for React and JSX.
   2. Pass the content type **uid**, not its display title.

From 29b41d24f2943113ad5b953cbc93a248228b3be7 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Fri, 4 Sep 2026 16:52:29 +0530
Subject: [PATCH 07/21] fix(skills): carry the mode: "builder" requirement into
 setup-docs and the preflight checklist

Same finding as the previous two commits, applied to the two files that
still described Visual Editor as "Live Preview plus edit tags". The
preflight checklist gains an explicit item: mode: "builder" must be set if
Visual Editor is the target, because its Verify Mode gate fails on
"preview".

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../references/preflight-checklist.md         | 36 ++++++++++---------
 .../references/setup-docs.md                  |  5 +--
 .../references/preflight-checklist.md         | 36 ++++++++++---------
 .../references/setup-docs.md                  |  5 +--
 4 files changed, 44 insertions(+), 38 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
index 2bcb6ff..1904d1c 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -51,43 +51,45 @@ meaningless.
     produces blank screens rather than an error.
 16. **`stackDetails: { apiKey, environment }` is passed explicitly.** Since v2 the SDK no longer
     derives the API key from the Stack object for edit tags.
+17. **`mode: "builder"` is set if Visual Editor is the target.** Visual Editor's own onboarding check
+    has a Verify Mode item that fails on `mode: "preview"`. Edit tags alone do not produce a canvas.
 
 ## Contract 2: edit tags reach the DOM
 
-17. **A rendered field carries `data-cslp`**, formed as
+18. **A rendered field carries `data-cslp`**, formed as
     `<content_type_uid>.<entry_uid>.<locale>.<field_path>`.
-18. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called on every fetched entry,
+19. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called on every fetched entry,
     including referenced entries. The third argument must be `true` for React and JSX.
-19. **The `$` attributes are spread onto the leaf element** that renders the value, one `data-cslp`
+20. **The `$` attributes are spread onto the leaf element** that renders the value, one `data-cslp`
     per element. Tagging a wrapper selects the wrong field.
-20. **Reference paths mirror the data shape.** References come back as arrays:
+21. **Reference paths mirror the data shape.** References come back as arrays:
     `post.author[0].$?.name`, not `post.$?.author.name`.
-21. **For GraphQL**, connection wrappers are flattened and `system { uid, content_type_uid }` is
+22. **For GraphQL**, connection wrappers are flattened and `system { uid, content_type_uid }` is
     requested on every node, before `addEditableTags()` runs.
 
 ## Contract 3: the hash reaches the fetch
 
-22. **Content requests hit a `*-preview.contentstack.com` host** during an active preview session.
+23. **Content requests hit a `*-preview.contentstack.com` host** during an active preview session.
     Seeing `cdn.contentstack.io` or `graphql.contentstack.com` here is the single most common setup
     failure, whatever the reported symptom was.
-23. **Those requests carry `live_preview` and `preview_token` headers** and return 200.
-24. **Every fetch path uses the initialized Stack instance.** A second instance, a hand-rolled
+24. **Those requests carry `live_preview` and `preview_token` headers** and return 200.
+25. **Every fetch path uses the initialized Stack instance.** A second instance, a hand-rolled
     wrapper, or a BFF that bypasses it will keep serving published content.
-25. **The hash is never hardcoded or invented.** An unrecognised hash returns
+26. **The hash is never hardcoded or invented.** An unrecognised hash returns
     `error_code 382, Please create tracker before starting live preview session`.
-26. **If the app proxies Contentstack through its own backend**, the hash is forwarded end to end.
-27. **SSR only: the Stack instance is built per request.** A module-level instance leaks one
+27. **If the app proxies Contentstack through its own backend**, the hash is forwarded end to end.
+28. **SSR only: the Stack instance is built per request.** A module-level instance leaks one
     editor's draft into other users' responses, including public traffic.
-28. **Caching is bypassed for preview requests.** Any cache on the preview path serves published
+29. **Caching is bypassed for preview requests.** Any cache on the preview path serves published
     content after the host switch is already correct, and can serve preview output to real visitors.
 
 ## Behaviour
 
-29. **Edit a field without saving.** The preview updates.
-30. **Hover a tagged element in Visual Editor.** It highlights, and clicking focuses the matching
+30. **Edit a field without saving.** The preview updates.
+31. **Hover a tagged element in Visual Editor.** It highlights, and clicking focuses the matching
     field in the form panel.
-31. **Open entries from several content types**, including a nested route and one with no `url`
+32. **Open entries from several content types**, including a nested route and one with no `url`
     field. Each loads its own page.
-32. **Navigate inside the preview pane.** Preview context survives the navigation.
-33. **Load the public site in a normal browser tab.** No edit button, no `#cslp-tooltip` in the DOM,
+33. **Navigate inside the preview pane.** Preview context survives the navigation.
+34. **Load the public site in a normal browser tab.** No edit button, no `#cslp-tooltip` in the DOM,
     and no preview response served from cache.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 60475ab..bb5a26a 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -29,8 +29,9 @@ Establish framework and rendering mode first, then route.
 
 ### Visual Editor, on top of a working Live Preview
 
-Visual Editor is not a separate integration. It is Live Preview plus edit tags, so Live Preview
-must work first.
+Visual Editor is not a separate integration. It is Live Preview plus edit tags plus `mode: "builder"`
+in `init()`, so Live Preview must work first, and a setup copied from a Live Preview guide will still
+fail Visual Editor's Verify Mode gate until the mode is changed from `"preview"`.
 
 - [Set Up Visual Builder for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-builder/set-up-visual-builder-for-your-website)
 - [Set Up Visual Editor for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-editor/set-up-visual-editor-for-your-website)
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
index 2bcb6ff..1904d1c 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -51,43 +51,45 @@ meaningless.
     produces blank screens rather than an error.
 16. **`stackDetails: { apiKey, environment }` is passed explicitly.** Since v2 the SDK no longer
     derives the API key from the Stack object for edit tags.
+17. **`mode: "builder"` is set if Visual Editor is the target.** Visual Editor's own onboarding check
+    has a Verify Mode item that fails on `mode: "preview"`. Edit tags alone do not produce a canvas.
 
 ## Contract 2: edit tags reach the DOM
 
-17. **A rendered field carries `data-cslp`**, formed as
+18. **A rendered field carries `data-cslp`**, formed as
     `<content_type_uid>.<entry_uid>.<locale>.<field_path>`.
-18. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called on every fetched entry,
+19. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called on every fetched entry,
     including referenced entries. The third argument must be `true` for React and JSX.
-19. **The `$` attributes are spread onto the leaf element** that renders the value, one `data-cslp`
+20. **The `$` attributes are spread onto the leaf element** that renders the value, one `data-cslp`
     per element. Tagging a wrapper selects the wrong field.
-20. **Reference paths mirror the data shape.** References come back as arrays:
+21. **Reference paths mirror the data shape.** References come back as arrays:
     `post.author[0].$?.name`, not `post.$?.author.name`.
-21. **For GraphQL**, connection wrappers are flattened and `system { uid, content_type_uid }` is
+22. **For GraphQL**, connection wrappers are flattened and `system { uid, content_type_uid }` is
     requested on every node, before `addEditableTags()` runs.
 
 ## Contract 3: the hash reaches the fetch
 
-22. **Content requests hit a `*-preview.contentstack.com` host** during an active preview session.
+23. **Content requests hit a `*-preview.contentstack.com` host** during an active preview session.
     Seeing `cdn.contentstack.io` or `graphql.contentstack.com` here is the single most common setup
     failure, whatever the reported symptom was.
-23. **Those requests carry `live_preview` and `preview_token` headers** and return 200.
-24. **Every fetch path uses the initialized Stack instance.** A second instance, a hand-rolled
+24. **Those requests carry `live_preview` and `preview_token` headers** and return 200.
+25. **Every fetch path uses the initialized Stack instance.** A second instance, a hand-rolled
     wrapper, or a BFF that bypasses it will keep serving published content.
-25. **The hash is never hardcoded or invented.** An unrecognised hash returns
+26. **The hash is never hardcoded or invented.** An unrecognised hash returns
     `error_code 382, Please create tracker before starting live preview session`.
-26. **If the app proxies Contentstack through its own backend**, the hash is forwarded end to end.
-27. **SSR only: the Stack instance is built per request.** A module-level instance leaks one
+27. **If the app proxies Contentstack through its own backend**, the hash is forwarded end to end.
+28. **SSR only: the Stack instance is built per request.** A module-level instance leaks one
     editor's draft into other users' responses, including public traffic.
-28. **Caching is bypassed for preview requests.** Any cache on the preview path serves published
+29. **Caching is bypassed for preview requests.** Any cache on the preview path serves published
     content after the host switch is already correct, and can serve preview output to real visitors.
 
 ## Behaviour
 
-29. **Edit a field without saving.** The preview updates.
-30. **Hover a tagged element in Visual Editor.** It highlights, and clicking focuses the matching
+30. **Edit a field without saving.** The preview updates.
+31. **Hover a tagged element in Visual Editor.** It highlights, and clicking focuses the matching
     field in the form panel.
-31. **Open entries from several content types**, including a nested route and one with no `url`
+32. **Open entries from several content types**, including a nested route and one with no `url`
     field. Each loads its own page.
-32. **Navigate inside the preview pane.** Preview context survives the navigation.
-33. **Load the public site in a normal browser tab.** No edit button, no `#cslp-tooltip` in the DOM,
+33. **Navigate inside the preview pane.** Preview context survives the navigation.
+34. **Load the public site in a normal browser tab.** No edit button, no `#cslp-tooltip` in the DOM,
     and no preview response served from cache.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 60475ab..bb5a26a 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -29,8 +29,9 @@ Establish framework and rendering mode first, then route.
 
 ### Visual Editor, on top of a working Live Preview
 
-Visual Editor is not a separate integration. It is Live Preview plus edit tags, so Live Preview
-must work first.
+Visual Editor is not a separate integration. It is Live Preview plus edit tags plus `mode: "builder"`
+in `init()`, so Live Preview must work first, and a setup copied from a Live Preview guide will still
+fail Visual Editor's Verify Mode gate until the mode is changed from `"preview"`.
 
 - [Set Up Visual Builder for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-builder/set-up-visual-builder-for-your-website)
 - [Set Up Visual Editor for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-editor/set-up-visual-editor-for-your-website)

From 9960b5af143779f9c715f7d14a17ff526b6407d9 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Fri, 4 Sep 2026 17:53:40 +0530
Subject: [PATCH 08/21] docs(skills): document edit-tag key convention and
 container tagging

Contract 2 told the reader to "tag the leaf element" and to call
addEditableTags on referenced entries as well. Both were wrong for the
common case, and the FAQ already said otherwise:

- @contentstack/utils rebases tags onto a referenced entry automatically
  when the resolved object carries uid and _content_type_uid. A separate
  call is only needed for hand-merged references or GraphQL nodes without
  system.
- Multiple, reference and modular-block fields need the container tag on
  the wrapper plus <field>__<index> on each instance. The SDK finds the
  container with closest('[data-cslp="<container>"]') before drawing add
  and reorder controls, so leaf-only tagging leaves them unreachable.
- An empty multiple or block field has to keep its wrapper in the DOM
  with VB_EmptyBlockParentClass and the container tag, or the SDK has no
  element to render its add button into. This lived only in the FAQ, so a
  first-pass tagging implementation was incomplete by construction.

Add references/edit-tags.md with the $ key convention (<field>,
<field>__<index>, <field>__parent), a per-field-kind checklist with each
kind's empty-state behaviour, and the rule to enumerate fields from
Object.keys(entry.$) rather than the JSX. Align preflight items 19 and 20
and regenerate the cursor and codex trees.

Found in a dry run against the Next.js App Router example.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../SKILL.md                                  |  24 +++-
 .../references/edit-tags.md                   | 111 ++++++++++++++++++
 .../references/preflight-checklist.md         |  11 +-
 ...review-visual-editor-support-assistant.mdc |  24 +++-
 .../SKILL.md                                  |  24 +++-
 .../references/edit-tags.md                   | 111 ++++++++++++++++++
 .../references/preflight-checklist.md         |  11 +-
 7 files changed, 293 insertions(+), 23 deletions(-)
 create mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
 create mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
index db60633..172df68 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -316,11 +316,25 @@ addEditableTags(entry, contentTypeUid, true, locale);
 <h1 {...data.$?.title}>{data.title}</h1>
 ```
 
-`mode: "builder"` does not generate tags; only `addEditableTags()` does, though `mode: "builder"` is still required because Visual Editor's Verify Mode gate fails on `mode: "preview"`, it mutates the entry and
-returns nothing, and the third argument must be `true` for React and JSX. Mirror the data path
-exactly, because references come back as arrays: `post.author[0].$?.name`, not
-`post.$?.author.name`. Tag the leaf element, one `data-cslp` per element, and call it on referenced
-entries too.
+`mode: "builder"` does not generate tags; only `addEditableTags()` does. (`mode: "builder"` is
+still required, because Visual Editor's Verify Mode gate fails on `mode: "preview"`.) The call
+mutates the entry and returns nothing, and the third argument must be `true` for React and JSX.
+Call it once per top-level entry: references resolved with `includeReference()` or `include[]`
+carry `uid` and `_content_type_uid`, and their tags are rebased to the referenced entry
+automatically. A separate call is needed only for references merged by hand, or GraphQL nodes
+fetched without `system`. Mirror the data path exactly, because references come back as arrays:
+`post.author[0].$?.name`, not `post.$?.author.name`.
+
+Tag leaves **and** containers. A scalar takes `entry.$.field` on the element that renders the value.
+Multiple fields, references and modular blocks take `entry.$.field` on the wrapper plus
+`entry.$["field__" + i]` on each instance; the canvas attaches add and reorder controls only when
+an instance sits inside an element carrying the container tag. An empty multiple or block field
+keeps its wrapper in the DOM while previewing, marked with `VB_EmptyBlockParentClass` and the
+container tag, or the canvas has nothing to draw its add button on.
+
+Enumerate fields from `Object.keys(entry.$)` and diff against what the page renders. Do not eyeball
+the JSX. The full key convention and a per-field-kind checklist are in
+[references/edit-tags.md](references/edit-tags.md).
 
 For contract 3:
 
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md b/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
new file mode 100644
index 0000000..6ba4e8e
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
@@ -0,0 +1,111 @@
+# Edit tags: what `addEditableTags()` produces and where each key goes
+
+Checked against `@contentstack/utils` 1.9.1 (`addTags`, exported as `addEditableTags`) and the
+Live Preview SDK's empty-block and add-instance code. Use this to make a first tagging pass complete
+by construction, not by diligence.
+
+## The call
+
+```js
+addEditableTags(entry, contentTypeUid, true, locale /*, { useLowerCaseLocale: false } */);
+```
+
+- Mutates the entry and returns nothing. It attaches a `$` object at every level: the entry, each
+  group, each block instance, and each resolved reference.
+- Call it **once per top-level entry**. A resolved reference that carries `uid` and
+  `_content_type_uid` (which `includeReference()` and REST `include[]` preserve) gets its own `$`,
+  rebased to the referenced entry: `author.<author_uid>.<locale>.title`, not
+  `blog_post.<post_uid>.<locale>.author.0.title`. A separate call per referenced entry is needed
+  only when references were fetched separately and merged by hand, or when a GraphQL query omitted
+  `system { uid content_type_uid locale }`.
+- The third argument must be `true` in React and JSX so the values are objects you can spread.
+- `locale` and `contentTypeUid` are lowercased; pass `{ useLowerCaseLocale: false }` for stacks with
+  mixed-case locale codes.
+
+## The `$` key convention
+
+| Key on `$` | Attribute it holds | Value | Spread it onto |
+|---|---|---|---|
+| `<field>` | `data-cslp` | `<ct>.<entry>.<locale>.<field>` | the element rendering a scalar; the wrapper of an array, group, or asset |
+| `<field>__<index>` | `data-cslp` | `<ct>.<entry>.<locale>.<field>.<index>` | the element wrapping instance `<index>`; lives on the **parent's** `$` |
+| `<field>__parent` | `data-cslp-parent-field` | `<ct>.<entry>.<locale>.<field>` | nothing. The SDK does not read this attribute; skip it |
+
+Nesting follows the data, so read tags off the object at the same depth as the value:
+
+| Value | Tag | Resolves to |
+|---|---|---|
+| `entry.group.title` | `entry.group.$.title` | `…group.title` |
+| `entry.blocks[i]` | `entry.$["blocks__" + i]` | `…blocks.<i>` |
+| `entry.blocks[i].hero` | `entry.blocks[i].$.hero` | `…blocks.<i>.hero` |
+| `entry.blocks[i].hero.title` | `entry.blocks[i].hero.$.title` | `…blocks.<i>.hero.title` |
+| `entry.author[i].title` | `entry.author[i].$.title` | `author.<author_uid>.<locale>.title` (rebased) |
+
+## Rule: enumerate from `$`, never from the JSX
+
+```js
+// once, while previewing
+console.log(Object.keys(entry.$));
+```
+
+Diff that list against what the page renders. Any key never spread onto an element is a field the
+canvas cannot reach, and reading the JSX will not show you the gap. Do the same on each block and
+group object.
+
+## Per-field-kind checklist
+
+| Field kind | Spread | Empty state while previewing |
+|---|---|---|
+| Scalar (text, number, boolean, date, select) | `entry.$.field` on the element that renders the value | Render a placeholder box that keeps the tag and has height. Nothing rendered means nothing clickable |
+| Link | `entry.$.link` on the `<a>` | Same as scalar |
+| RTE (HTML string) | `entry.$.rte` on the container that receives the HTML | Same as scalar |
+| JSON RTE | Render with `jsonToHTML` first (it mutates the entry), then `entry.$.body` on the container | Same as scalar |
+| Asset (file) | `entry.$.image` on the `<img>` or its wrapper | Placeholder box or omit. The SDK draws no add button for assets |
+| Single reference | Reference fields always arrive as arrays. `entry.$.ref` on the wrapper; `entry.ref[0].$.title` on the leaf, already rebased | Wrapper with the empty-block contract below |
+| Multiple reference, multiple scalar | `entry.$.field` on the wrapper **and** `entry.$["field__" + i]` on each instance; leaves inside a reference instance use the referenced entry's `$` | Empty-block contract below |
+| Modular blocks | `entry.$.blocks` on the wrapper; `entry.$["blocks__" + i]` on each block wrapper; `block.$.hero` on the block-type element; `block.hero.$.title` on fields inside | Empty-block contract below |
+| Group | `entry.$.group` on the group wrapper; `entry.group.$.field` inside | A group object is never absent; its fields follow the scalar rule. A multiple group follows the multiple rules as well |
+
+**Why the container tag matters for multiple fields.** Add and reorder controls appear on an
+instance only if `closest('[data-cslp="<container value>"]')` finds an ancestor. Leaves alone give
+the canvas nothing to attach them to. An optional `data-add-direction="vertical"` or
+`"horizontal"` on the container overrides the SDK's layout detection.
+
+## Empty-block contract
+
+The SDK renders its own "Add <field display name>" button, but only on an element that satisfies
+all three:
+
+1. carries the class `visual-builder__empty-block-parent` (exported as `VB_EmptyBlockParentClass`);
+2. carries its own `data-cslp` for the field, that is the container tag `entry.$.field`;
+3. that field path exists in the content type schema.
+
+So the wrapper has to stay in the DOM when the array is empty, which a plain `items.length > 0 &&`
+guard removes:
+
+```jsx
+import { VB_EmptyBlockParentClass } from "@contentstack/live-preview-utils";
+
+{related.length > 0 || isPreview ? (
+  <ul
+    className={related.length === 0 ? `list ${VB_EmptyBlockParentClass}` : "list"}
+    {...post.$?.related_post}
+  >
+    {related.map((r, i) => (
+      <li key={r.uid} {...post.$?.[`related_post__${i}`]}>
+        <a href={r.url} {...r.$?.title}>{r.title}</a>
+      </li>
+    ))}
+  </ul>
+) : null}
+```
+
+Hover and click on the marked wrapper draw no outline; the button is the affordance.
+
+## Verify
+
+- `document.querySelectorAll('[data-cslp]')` in DevTools should account for every key you expect
+  from `Object.keys(entry.$)` at each level.
+- Hover each region in builder mode: the outline and toolbar label name the field you intended.
+- Hover an instance of a multiple field: add and reorder controls appear between instances.
+- Clear a multiple or block field and reload the canvas: the "Add …" button appears where the field
+  renders, and adding an instance inserts it into the canvas and the form.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
index 1904d1c..1dc0dd0 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -58,10 +58,13 @@ meaningless.
 
 18. **A rendered field carries `data-cslp`**, formed as
     `<content_type_uid>.<entry_uid>.<locale>.<field_path>`.
-19. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called on every fetched entry,
-    including referenced entries. The third argument must be `true` for React and JSX.
-20. **The `$` attributes are spread onto the leaf element** that renders the value, one `data-cslp`
-    per element. Tagging a wrapper selects the wrong field.
+19. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called once on every fetched
+    top-level entry. The third argument must be `true` for React and JSX. References resolved with
+    `includeReference()` are rebased automatically; a separate call is only for hand-merged ones.
+20. **`$` keys are spread onto leaves and containers.** Scalars: the element rendering the value.
+    Multiple, reference and block fields: `entry.$.field` on the wrapper plus `entry.$["field__" + i]`
+    per instance, and an empty one keeps the wrapper with `VB_EmptyBlockParentClass`. Enumerate from
+    `Object.keys(entry.$)`, not from the JSX. See [edit-tags.md](edit-tags.md).
 21. **Reference paths mirror the data shape.** References come back as arrays:
     `post.author[0].$?.name`, not `post.$?.author.name`.
 22. **For GraphQL**, connection wrappers are flattened and `system { uid, content_type_uid }` is
diff --git a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
index c051f81..9d88df5 100644
--- a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
+++ b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
@@ -319,11 +319,25 @@ addEditableTags(entry, contentTypeUid, true, locale);
 <h1 {...data.$?.title}>{data.title}</h1>
 ```
 
-`mode: "builder"` does not generate tags; only `addEditableTags()` does, though `mode: "builder"` is still required because Visual Editor's Verify Mode gate fails on `mode: "preview"`, it mutates the entry and
-returns nothing, and the third argument must be `true` for React and JSX. Mirror the data path
-exactly, because references come back as arrays: `post.author[0].$?.name`, not
-`post.$?.author.name`. Tag the leaf element, one `data-cslp` per element, and call it on referenced
-entries too.
+`mode: "builder"` does not generate tags; only `addEditableTags()` does. (`mode: "builder"` is
+still required, because Visual Editor's Verify Mode gate fails on `mode: "preview"`.) The call
+mutates the entry and returns nothing, and the third argument must be `true` for React and JSX.
+Call it once per top-level entry: references resolved with `includeReference()` or `include[]`
+carry `uid` and `_content_type_uid`, and their tags are rebased to the referenced entry
+automatically. A separate call is needed only for references merged by hand, or GraphQL nodes
+fetched without `system`. Mirror the data path exactly, because references come back as arrays:
+`post.author[0].$?.name`, not `post.$?.author.name`.
+
+Tag leaves **and** containers. A scalar takes `entry.$.field` on the element that renders the value.
+Multiple fields, references and modular blocks take `entry.$.field` on the wrapper plus
+`entry.$["field__" + i]` on each instance; the canvas attaches add and reorder controls only when
+an instance sits inside an element carrying the container tag. An empty multiple or block field
+keeps its wrapper in the DOM while previewing, marked with `VB_EmptyBlockParentClass` and the
+container tag, or the canvas has nothing to draw its add button on.
+
+Enumerate fields from `Object.keys(entry.$)` and diff against what the page renders. Do not eyeball
+the JSX. The full key convention and a per-field-kind checklist are in
+[references/edit-tags.md](references/edit-tags.md).
 
 For contract 3:
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
index 0171b6f..a7a34dd 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -319,11 +319,25 @@ addEditableTags(entry, contentTypeUid, true, locale);
 <h1 {...data.$?.title}>{data.title}</h1>
 ```
 
-`mode: "builder"` does not generate tags; only `addEditableTags()` does, though `mode: "builder"` is still required because Visual Editor's Verify Mode gate fails on `mode: "preview"`, it mutates the entry and
-returns nothing, and the third argument must be `true` for React and JSX. Mirror the data path
-exactly, because references come back as arrays: `post.author[0].$?.name`, not
-`post.$?.author.name`. Tag the leaf element, one `data-cslp` per element, and call it on referenced
-entries too.
+`mode: "builder"` does not generate tags; only `addEditableTags()` does. (`mode: "builder"` is
+still required, because Visual Editor's Verify Mode gate fails on `mode: "preview"`.) The call
+mutates the entry and returns nothing, and the third argument must be `true` for React and JSX.
+Call it once per top-level entry: references resolved with `includeReference()` or `include[]`
+carry `uid` and `_content_type_uid`, and their tags are rebased to the referenced entry
+automatically. A separate call is needed only for references merged by hand, or GraphQL nodes
+fetched without `system`. Mirror the data path exactly, because references come back as arrays:
+`post.author[0].$?.name`, not `post.$?.author.name`.
+
+Tag leaves **and** containers. A scalar takes `entry.$.field` on the element that renders the value.
+Multiple fields, references and modular blocks take `entry.$.field` on the wrapper plus
+`entry.$["field__" + i]` on each instance; the canvas attaches add and reorder controls only when
+an instance sits inside an element carrying the container tag. An empty multiple or block field
+keeps its wrapper in the DOM while previewing, marked with `VB_EmptyBlockParentClass` and the
+container tag, or the canvas has nothing to draw its add button on.
+
+Enumerate fields from `Object.keys(entry.$)` and diff against what the page renders. Do not eyeball
+the JSX. The full key convention and a per-field-kind checklist are in
+[references/edit-tags.md](references/edit-tags.md).
 
 For contract 3:
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md b/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
new file mode 100644
index 0000000..6ba4e8e
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
@@ -0,0 +1,111 @@
+# Edit tags: what `addEditableTags()` produces and where each key goes
+
+Checked against `@contentstack/utils` 1.9.1 (`addTags`, exported as `addEditableTags`) and the
+Live Preview SDK's empty-block and add-instance code. Use this to make a first tagging pass complete
+by construction, not by diligence.
+
+## The call
+
+```js
+addEditableTags(entry, contentTypeUid, true, locale /*, { useLowerCaseLocale: false } */);
+```
+
+- Mutates the entry and returns nothing. It attaches a `$` object at every level: the entry, each
+  group, each block instance, and each resolved reference.
+- Call it **once per top-level entry**. A resolved reference that carries `uid` and
+  `_content_type_uid` (which `includeReference()` and REST `include[]` preserve) gets its own `$`,
+  rebased to the referenced entry: `author.<author_uid>.<locale>.title`, not
+  `blog_post.<post_uid>.<locale>.author.0.title`. A separate call per referenced entry is needed
+  only when references were fetched separately and merged by hand, or when a GraphQL query omitted
+  `system { uid content_type_uid locale }`.
+- The third argument must be `true` in React and JSX so the values are objects you can spread.
+- `locale` and `contentTypeUid` are lowercased; pass `{ useLowerCaseLocale: false }` for stacks with
+  mixed-case locale codes.
+
+## The `$` key convention
+
+| Key on `$` | Attribute it holds | Value | Spread it onto |
+|---|---|---|---|
+| `<field>` | `data-cslp` | `<ct>.<entry>.<locale>.<field>` | the element rendering a scalar; the wrapper of an array, group, or asset |
+| `<field>__<index>` | `data-cslp` | `<ct>.<entry>.<locale>.<field>.<index>` | the element wrapping instance `<index>`; lives on the **parent's** `$` |
+| `<field>__parent` | `data-cslp-parent-field` | `<ct>.<entry>.<locale>.<field>` | nothing. The SDK does not read this attribute; skip it |
+
+Nesting follows the data, so read tags off the object at the same depth as the value:
+
+| Value | Tag | Resolves to |
+|---|---|---|
+| `entry.group.title` | `entry.group.$.title` | `…group.title` |
+| `entry.blocks[i]` | `entry.$["blocks__" + i]` | `…blocks.<i>` |
+| `entry.blocks[i].hero` | `entry.blocks[i].$.hero` | `…blocks.<i>.hero` |
+| `entry.blocks[i].hero.title` | `entry.blocks[i].hero.$.title` | `…blocks.<i>.hero.title` |
+| `entry.author[i].title` | `entry.author[i].$.title` | `author.<author_uid>.<locale>.title` (rebased) |
+
+## Rule: enumerate from `$`, never from the JSX
+
+```js
+// once, while previewing
+console.log(Object.keys(entry.$));
+```
+
+Diff that list against what the page renders. Any key never spread onto an element is a field the
+canvas cannot reach, and reading the JSX will not show you the gap. Do the same on each block and
+group object.
+
+## Per-field-kind checklist
+
+| Field kind | Spread | Empty state while previewing |
+|---|---|---|
+| Scalar (text, number, boolean, date, select) | `entry.$.field` on the element that renders the value | Render a placeholder box that keeps the tag and has height. Nothing rendered means nothing clickable |
+| Link | `entry.$.link` on the `<a>` | Same as scalar |
+| RTE (HTML string) | `entry.$.rte` on the container that receives the HTML | Same as scalar |
+| JSON RTE | Render with `jsonToHTML` first (it mutates the entry), then `entry.$.body` on the container | Same as scalar |
+| Asset (file) | `entry.$.image` on the `<img>` or its wrapper | Placeholder box or omit. The SDK draws no add button for assets |
+| Single reference | Reference fields always arrive as arrays. `entry.$.ref` on the wrapper; `entry.ref[0].$.title` on the leaf, already rebased | Wrapper with the empty-block contract below |
+| Multiple reference, multiple scalar | `entry.$.field` on the wrapper **and** `entry.$["field__" + i]` on each instance; leaves inside a reference instance use the referenced entry's `$` | Empty-block contract below |
+| Modular blocks | `entry.$.blocks` on the wrapper; `entry.$["blocks__" + i]` on each block wrapper; `block.$.hero` on the block-type element; `block.hero.$.title` on fields inside | Empty-block contract below |
+| Group | `entry.$.group` on the group wrapper; `entry.group.$.field` inside | A group object is never absent; its fields follow the scalar rule. A multiple group follows the multiple rules as well |
+
+**Why the container tag matters for multiple fields.** Add and reorder controls appear on an
+instance only if `closest('[data-cslp="<container value>"]')` finds an ancestor. Leaves alone give
+the canvas nothing to attach them to. An optional `data-add-direction="vertical"` or
+`"horizontal"` on the container overrides the SDK's layout detection.
+
+## Empty-block contract
+
+The SDK renders its own "Add <field display name>" button, but only on an element that satisfies
+all three:
+
+1. carries the class `visual-builder__empty-block-parent` (exported as `VB_EmptyBlockParentClass`);
+2. carries its own `data-cslp` for the field, that is the container tag `entry.$.field`;
+3. that field path exists in the content type schema.
+
+So the wrapper has to stay in the DOM when the array is empty, which a plain `items.length > 0 &&`
+guard removes:
+
+```jsx
+import { VB_EmptyBlockParentClass } from "@contentstack/live-preview-utils";
+
+{related.length > 0 || isPreview ? (
+  <ul
+    className={related.length === 0 ? `list ${VB_EmptyBlockParentClass}` : "list"}
+    {...post.$?.related_post}
+  >
+    {related.map((r, i) => (
+      <li key={r.uid} {...post.$?.[`related_post__${i}`]}>
+        <a href={r.url} {...r.$?.title}>{r.title}</a>
+      </li>
+    ))}
+  </ul>
+) : null}
+```
+
+Hover and click on the marked wrapper draw no outline; the button is the affordance.
+
+## Verify
+
+- `document.querySelectorAll('[data-cslp]')` in DevTools should account for every key you expect
+  from `Object.keys(entry.$)` at each level.
+- Hover each region in builder mode: the outline and toolbar label name the field you intended.
+- Hover an instance of a multiple field: add and reorder controls appear between instances.
+- Clear a multiple or block field and reload the canvas: the "Add …" button appears where the field
+  renders, and adding an instance inserts it into the canvas and the form.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
index 1904d1c..1dc0dd0 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -58,10 +58,13 @@ meaningless.
 
 18. **A rendered field carries `data-cslp`**, formed as
     `<content_type_uid>.<entry_uid>.<locale>.<field_path>`.
-19. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called on every fetched entry,
-    including referenced entries. The third argument must be `true` for React and JSX.
-20. **The `$` attributes are spread onto the leaf element** that renders the value, one `data-cslp`
-    per element. Tagging a wrapper selects the wrong field.
+19. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called once on every fetched
+    top-level entry. The third argument must be `true` for React and JSX. References resolved with
+    `includeReference()` are rebased automatically; a separate call is only for hand-merged ones.
+20. **`$` keys are spread onto leaves and containers.** Scalars: the element rendering the value.
+    Multiple, reference and block fields: `entry.$.field` on the wrapper plus `entry.$["field__" + i]`
+    per instance, and an empty one keeps the wrapper with `VB_EmptyBlockParentClass`. Enumerate from
+    `Object.keys(entry.$)`, not from the JSX. See [edit-tags.md](edit-tags.md).
 21. **Reference paths mirror the data shape.** References come back as arrays:
     `post.author[0].$?.name`, not `post.$?.author.name`.
 22. **For GraphQL**, connection wrappers are flattened and `system { uid, content_type_uid }` is

From 0cf6360cfe6cad6f4db513da579aa4c73e7684d4 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Fri, 4 Sep 2026 18:24:48 +0530
Subject: [PATCH 09/21] docs(skills): add no-resilience rule and backwards-gate
 note

Two process rules from a dry run against the Next.js example, where the
diagnosis went wrong in ways the existing rules did not catch:

- A fallback to published content on preview failure showed the editor
  published data while they believed they were seeing their edit, and
  hid the signal being debugged. Rule: while diagnosing, add no
  fallbacks, retries, caches or optimisations; fail visibly. When
  SDK-prescribed behaviour looks improvable, find the guard the SDK
  already has for that concern first.
- An onboarding gate that went backwards was treated as flakiness and
  answered with a reload. Rule: a backwards gate is information; it
  re-enters the Transition rule, not a refresh.

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../SKILL.md                                             | 9 ++++++++-
 ...-cms-live-preview-visual-editor-support-assistant.mdc | 9 ++++++++-
 .../SKILL.md                                             | 9 ++++++++-
 3 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
index 172df68..b341f3f 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -102,7 +102,14 @@ identified, and you will not know which.
 regressed, a new error replacing an old one: each is a regression from a known state, and the first
 question is what changed since it last worked. Include your own edits in that question, not only the
 user's. Mid-session, the change most likely to have caused a transition is the one you just made, and
-it is also the one you are least likely to suspect.
+it is also the one you are least likely to suspect. An Onboarding Check gate that goes backwards is
+information, not flakiness; do not answer it with a reload.
+
+**No-resilience rule:** while diagnosing, add no fallbacks, retries, caches, or optimisations.
+Falling back to published content when the preview fetch fails shows an editor published content
+while they believe they are looking at their edit, and hides the very signal being debugged. Fail
+visibly. If SDK-prescribed behaviour looks improvable, find the guard the SDK already has for that
+concern before changing anything; it usually exists.
 
 ### Step 1. Which product?
 
diff --git a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
index 9d88df5..4f0a331 100644
--- a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
+++ b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
@@ -105,7 +105,14 @@ identified, and you will not know which.
 regressed, a new error replacing an old one: each is a regression from a known state, and the first
 question is what changed since it last worked. Include your own edits in that question, not only the
 user's. Mid-session, the change most likely to have caused a transition is the one you just made, and
-it is also the one you are least likely to suspect.
+it is also the one you are least likely to suspect. An Onboarding Check gate that goes backwards is
+information, not flakiness; do not answer it with a reload.
+
+**No-resilience rule:** while diagnosing, add no fallbacks, retries, caches, or optimisations.
+Falling back to published content when the preview fetch fails shows an editor published content
+while they believe they are looking at their edit, and hides the very signal being debugged. Fail
+visibly. If SDK-prescribed behaviour looks improvable, find the guard the SDK already has for that
+concern before changing anything; it usually exists.
 
 ### Step 1. Which product?
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
index a7a34dd..071e741 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -105,7 +105,14 @@ identified, and you will not know which.
 regressed, a new error replacing an old one: each is a regression from a known state, and the first
 question is what changed since it last worked. Include your own edits in that question, not only the
 user's. Mid-session, the change most likely to have caused a transition is the one you just made, and
-it is also the one you are least likely to suspect.
+it is also the one you are least likely to suspect. An Onboarding Check gate that goes backwards is
+information, not flakiness; do not answer it with a reload.
+
+**No-resilience rule:** while diagnosing, add no fallbacks, retries, caches, or optimisations.
+Falling back to published content when the preview fetch fails shows an editor published content
+while they believe they are looking at their edit, and hides the very signal being debugged. Fail
+visibly. If SDK-prescribed behaviour looks improvable, find the guard the SDK already has for that
+concern before changing anything; it usually exists.
 
 ### Step 1. Which product?
 

From ef91c6533ec236d68ef74b995d21abd0c8d99aa6 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Fri, 4 Sep 2026 19:43:56 +0530
Subject: [PATCH 10/21] docs(skills): say where include_applied_variants has to
 be passed

The skill mentioned the flag once, as an aside claiming it "only adds
metadata to the response body". That undersells it: the metadata is
_applied_variants, which is what makes addEditableTags emit v2 tags,
which is what Highlight Variant and audience mode key on. Without the
flag the variant content renders and both features silently do nothing.

Verified against delivery-sdk 5.6.0 and core 1.5.2: the flag only works
as a query parameter on the content request (addParams on the query or
single-entry fetch, or the raw REST parameter). livePreviewQuery() and
the Stack live_preview config both accept it in their types and store
it, but core never forwards it to the request.

- New FAQ entry highlight-variant-or-audience-mode-does-nothing with the
  working and non-working entry points, plus a symptom-index row.
- Variants section in references/edit-tags.md.
- Rewrite the aside in variant-or-audience-switch-shows-base-entry to
  point at the new entry.

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../references/edit-tags.md                   | 23 +++++++++++++++++++
 .../references/faq-preview-runtime.md         |  2 +-
 .../references/faq-visual-editor.md           | 16 +++++++++++++
 .../references/symptom-index.md               |  1 +
 .../references/edit-tags.md                   | 23 +++++++++++++++++++
 .../references/faq-preview-runtime.md         |  2 +-
 .../references/faq-visual-editor.md           | 16 +++++++++++++
 .../references/symptom-index.md               |  1 +
 8 files changed, 82 insertions(+), 2 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md b/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
index 6ba4e8e..54f246d 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
@@ -101,6 +101,29 @@ import { VB_EmptyBlockParentClass } from "@contentstack/live-preview-utils";
 
 Hover and click on the marked wrapper draw no outline; the button is the affordance.
 
+## Variants
+
+Highlight Variant and audience mode key on v2 tags:
+`v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>`. `addEditableTags()` emits them only for fields
+listed in the entry's `_applied_variants`, and the response includes that map only when the request
+carries `include_applied_variants=true`. Pass it on the content request, not on the Live Preview
+config:
+
+```js
+// Honoured: a query parameter on the request itself
+stack.contentType(ct).entry().query().addParams({ include_applied_variants: "true" }).find();
+stack.contentType(ct).entry(uid).addParams({ include_applied_variants: "true" }).fetch();
+// REST: ...&include_applied_variants=true
+
+// Accepted by the types, never sent (delivery-sdk 5.6.0, core 1.5.2)
+stack.livePreviewQuery({ live_preview: hash, include_applied_variants: true });
+contentstack.stack({ live_preview: { enable: true, include_applied_variants: true } });
+```
+
+Leave it on for delivery traffic; with no variant applied the response is unchanged. Never pass the
+variant uid yourself, the Preview Service applies it from the UI selection. One flag on the page
+query covers references that `includeReference()` resolved.
+
 ## Verify
 
 - `document.querySelectorAll('[data-cslp]')` in DevTools should account for every key you expect
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
index 8109e83..5527067 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -15,7 +15,7 @@ the fixes here will help.
 - **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-setup.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the parent Contentstack UI fetches the entry separately over the Management service. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
 - **fix**:
   1. First confirm the preview path works at all: change a plain text field and check the canvas updates. If it does not, fix that first — the variant symptom is downstream of it.
-  2. Do **not** try to pass the variant yourself. The Preview Service resolves the variant from the UI selection; no extra `variant` query param is needed. `include_applied_variants=true` only adds metadata to the response body.
+  2. Do **not** pass the variant yourself. The Preview Service resolves it from the UI selection; no `variant` query param, no `Entries.variants()`. Do pass `include_applied_variants=true` as a query parameter on the content request (`.addParams({ include_applied_variants: "true" })`), or the variant renders but Highlight Variant and audience mode have nothing to key on; see `highlight-variant-or-audience-mode-does-nothing` in `faq-visual-editor.md`.
   3. Confirm the Preview Service is actually configured: a preview token on the Stack's `live_preview` config, and content requests going to a `*-preview.contentstack.com` host during the session. This is the most common cause.
   4. Register `ContentstackLivePreview.onEntryChange(fetchFn)` and make `fetchFn` re-query through the preview-configured Stack. This is the second most common cause. Confirm `ssr` matches the route's actual rendering mode while you are there.
   5. Check the cache layer. If preview responses are cached under a key that ignores the `live_preview` hash, the base content is served no matter what. Bypass caching entirely for preview requests.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
index bc50f2c..520cc67 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -86,6 +86,22 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 
 ---
 
+### highlight-variant-or-audience-mode-does-nothing
+- **bucket**: visual-editor
+- **symptom**: Variant content renders correctly on the canvas, but Highlight Variant outlines nothing and audience mode shows no variant-specific fields. No error anywhere. Every `data-cslp` on the page is v1 (`<ct>.<uid>.<locale>.<field>`); none starts with `v2:`.
+- **frameworks**: any
+- **rendering_modes**: any
+- **root_cause**: `addEditableTags()` emits a `v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>` tag only for fields listed in the entry's `_applied_variants`. That map is in the response only when the content request carries `include_applied_variants=true`. Without it every tag is v1, the SDK parses no variant, and both features have nothing to key on. Content still renders correctly because the Preview Service already applied the variant, which is why this looks like a highlighting bug rather than a fetch problem. Two places look like they set the flag and do not: `livePreviewQuery({ include_applied_variants: true })` and `include_applied_variants` on the Stack's `live_preview` config are accepted by the delivery-sdk types and stored, but `@contentstack/core` never reads them off that config, so the flag never reaches the request (checked against delivery-sdk 5.6.0, core 1.5.2).
+- **fix**:
+  1. Pass it as a query parameter on the content request itself. Delivery SDK: `.addParams({ include_applied_variants: "true" })` on the query chain (`.entry().query().addParams(...)`) or on a single-entry fetch (`.entry(uid).addParams(...)`). REST: append `include_applied_variants=true` to the URL.
+  2. Do not route it through `livePreviewQuery()` or the Stack `live_preview` config. Both drop it silently.
+  3. Leave it on for delivery traffic too. When no variant applies the response carries no `_applied_variants` and is otherwise unchanged, so a preview-only branch buys nothing.
+  4. One flag on the page query covers referenced entries that `includeReference()` resolved; `addEditableTags()` reads `_applied_variants` per reference.
+  5. Never pass the variant uid yourself. The Preview Service applies it from the UI selection; `Entries.variants()` and `x-cs-variant-uid` are for regular delivery.
+- **verification**: With a variant selected, inspect a variantised field in DevTools. Its `data-cslp` starts with `v2:` and the entry segment reads `<entry_uid>_<variant_uid>`. Highlight Variant now outlines it.
+
+---
+
 ### canvas-swallows-site-click-events
 - **bucket**: visual-editor
 - **symptom**: Interactive components stop working inside the editor canvas: carousel arrows, tab strips, accordions, dropdowns and links do nothing when clicked, while the same page works normally outside the editor. Often noticed as soon as a parent container gets a `data-cslp`.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md b/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
index 29eb687..1da6105 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
@@ -60,6 +60,7 @@ SKILL.md before reading anything below.
 | A page or component with an empty modular-block / multiple field shows no "+ Add Component" affordance, so aut… | [empty-block-add-button-not-appearing-or-failing](faq-visual-editor.md#empty-block-add-button-not-appearing-or-failing) |
 | With GraphQL, edit tags are generated but Visual Editor cannot resolve them | [graphql-connection-wrappers-break-cslp](faq-visual-editor.md#graphql-connection-wrappers-break-cslp) |
 | Interactive components stop working inside the editor canvas: carousel arrows, tab strips, accordions, dropdow… | [canvas-swallows-site-click-events](faq-visual-editor.md#canvas-swallows-site-click-events) |
+| Variant content renders on the canvas but Highlight Variant outlines nothing and audience mode shows no variant fields | [highlight-variant-or-audience-mode-does-nothing](faq-visual-editor.md#highlight-variant-or-audience-mode-does-nothing) |
 
 ## Timeline
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md b/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
index 6ba4e8e..54f246d 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
@@ -101,6 +101,29 @@ import { VB_EmptyBlockParentClass } from "@contentstack/live-preview-utils";
 
 Hover and click on the marked wrapper draw no outline; the button is the affordance.
 
+## Variants
+
+Highlight Variant and audience mode key on v2 tags:
+`v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>`. `addEditableTags()` emits them only for fields
+listed in the entry's `_applied_variants`, and the response includes that map only when the request
+carries `include_applied_variants=true`. Pass it on the content request, not on the Live Preview
+config:
+
+```js
+// Honoured: a query parameter on the request itself
+stack.contentType(ct).entry().query().addParams({ include_applied_variants: "true" }).find();
+stack.contentType(ct).entry(uid).addParams({ include_applied_variants: "true" }).fetch();
+// REST: ...&include_applied_variants=true
+
+// Accepted by the types, never sent (delivery-sdk 5.6.0, core 1.5.2)
+stack.livePreviewQuery({ live_preview: hash, include_applied_variants: true });
+contentstack.stack({ live_preview: { enable: true, include_applied_variants: true } });
+```
+
+Leave it on for delivery traffic; with no variant applied the response is unchanged. Never pass the
+variant uid yourself, the Preview Service applies it from the UI selection. One flag on the page
+query covers references that `includeReference()` resolved.
+
 ## Verify
 
 - `document.querySelectorAll('[data-cslp]')` in DevTools should account for every key you expect
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
index 8109e83..5527067 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -15,7 +15,7 @@ the fixes here will help.
 - **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-setup.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the parent Contentstack UI fetches the entry separately over the Management service. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
 - **fix**:
   1. First confirm the preview path works at all: change a plain text field and check the canvas updates. If it does not, fix that first — the variant symptom is downstream of it.
-  2. Do **not** try to pass the variant yourself. The Preview Service resolves the variant from the UI selection; no extra `variant` query param is needed. `include_applied_variants=true` only adds metadata to the response body.
+  2. Do **not** pass the variant yourself. The Preview Service resolves it from the UI selection; no `variant` query param, no `Entries.variants()`. Do pass `include_applied_variants=true` as a query parameter on the content request (`.addParams({ include_applied_variants: "true" })`), or the variant renders but Highlight Variant and audience mode have nothing to key on; see `highlight-variant-or-audience-mode-does-nothing` in `faq-visual-editor.md`.
   3. Confirm the Preview Service is actually configured: a preview token on the Stack's `live_preview` config, and content requests going to a `*-preview.contentstack.com` host during the session. This is the most common cause.
   4. Register `ContentstackLivePreview.onEntryChange(fetchFn)` and make `fetchFn` re-query through the preview-configured Stack. This is the second most common cause. Confirm `ssr` matches the route's actual rendering mode while you are there.
   5. Check the cache layer. If preview responses are cached under a key that ignores the `live_preview` hash, the base content is served no matter what. Bypass caching entirely for preview requests.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
index bc50f2c..520cc67 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -86,6 +86,22 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 
 ---
 
+### highlight-variant-or-audience-mode-does-nothing
+- **bucket**: visual-editor
+- **symptom**: Variant content renders correctly on the canvas, but Highlight Variant outlines nothing and audience mode shows no variant-specific fields. No error anywhere. Every `data-cslp` on the page is v1 (`<ct>.<uid>.<locale>.<field>`); none starts with `v2:`.
+- **frameworks**: any
+- **rendering_modes**: any
+- **root_cause**: `addEditableTags()` emits a `v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>` tag only for fields listed in the entry's `_applied_variants`. That map is in the response only when the content request carries `include_applied_variants=true`. Without it every tag is v1, the SDK parses no variant, and both features have nothing to key on. Content still renders correctly because the Preview Service already applied the variant, which is why this looks like a highlighting bug rather than a fetch problem. Two places look like they set the flag and do not: `livePreviewQuery({ include_applied_variants: true })` and `include_applied_variants` on the Stack's `live_preview` config are accepted by the delivery-sdk types and stored, but `@contentstack/core` never reads them off that config, so the flag never reaches the request (checked against delivery-sdk 5.6.0, core 1.5.2).
+- **fix**:
+  1. Pass it as a query parameter on the content request itself. Delivery SDK: `.addParams({ include_applied_variants: "true" })` on the query chain (`.entry().query().addParams(...)`) or on a single-entry fetch (`.entry(uid).addParams(...)`). REST: append `include_applied_variants=true` to the URL.
+  2. Do not route it through `livePreviewQuery()` or the Stack `live_preview` config. Both drop it silently.
+  3. Leave it on for delivery traffic too. When no variant applies the response carries no `_applied_variants` and is otherwise unchanged, so a preview-only branch buys nothing.
+  4. One flag on the page query covers referenced entries that `includeReference()` resolved; `addEditableTags()` reads `_applied_variants` per reference.
+  5. Never pass the variant uid yourself. The Preview Service applies it from the UI selection; `Entries.variants()` and `x-cs-variant-uid` are for regular delivery.
+- **verification**: With a variant selected, inspect a variantised field in DevTools. Its `data-cslp` starts with `v2:` and the entry segment reads `<entry_uid>_<variant_uid>`. Highlight Variant now outlines it.
+
+---
+
 ### canvas-swallows-site-click-events
 - **bucket**: visual-editor
 - **symptom**: Interactive components stop working inside the editor canvas: carousel arrows, tab strips, accordions, dropdowns and links do nothing when clicked, while the same page works normally outside the editor. Often noticed as soon as a parent container gets a `data-cslp`.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md b/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
index 29eb687..1da6105 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
@@ -60,6 +60,7 @@ SKILL.md before reading anything below.
 | A page or component with an empty modular-block / multiple field shows no "+ Add Component" affordance, so aut… | [empty-block-add-button-not-appearing-or-failing](faq-visual-editor.md#empty-block-add-button-not-appearing-or-failing) |
 | With GraphQL, edit tags are generated but Visual Editor cannot resolve them | [graphql-connection-wrappers-break-cslp](faq-visual-editor.md#graphql-connection-wrappers-break-cslp) |
 | Interactive components stop working inside the editor canvas: carousel arrows, tab strips, accordions, dropdow… | [canvas-swallows-site-click-events](faq-visual-editor.md#canvas-swallows-site-click-events) |
+| Variant content renders on the canvas but Highlight Variant outlines nothing and audience mode shows no variant fields | [highlight-variant-or-audience-mode-does-nothing](faq-visual-editor.md#highlight-variant-or-audience-mode-does-nothing) |
 
 ## Timeline
 

From 8614c2db3652cc3b92d1ac63549ff1fa190340a2 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Fri, 4 Sep 2026 19:48:16 +0530
Subject: [PATCH 11/21] docs(skills): keep only the working
 include_applied_variants form

Drop the two "accepted but never sent" examples and the version-pinned
note about them. The skill documents the query-parameter form that
works; the SDK-side gap is tracked in Jira instead, so the skill does
not carry bug state that goes stale once it is fixed.

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../references/edit-tags.md                              | 7 +------
 .../references/faq-visual-editor.md                      | 9 ++++-----
 .../references/edit-tags.md                              | 7 +------
 .../references/faq-visual-editor.md                      | 9 ++++-----
 4 files changed, 10 insertions(+), 22 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md b/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
index 54f246d..f045012 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
@@ -106,18 +106,13 @@ Hover and click on the marked wrapper draw no outline; the button is the afforda
 Highlight Variant and audience mode key on v2 tags:
 `v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>`. `addEditableTags()` emits them only for fields
 listed in the entry's `_applied_variants`, and the response includes that map only when the request
-carries `include_applied_variants=true`. Pass it on the content request, not on the Live Preview
-config:
+carries `include_applied_variants=true`. Pass it as a query parameter on the content request:
 
 ```js
 // Honoured: a query parameter on the request itself
 stack.contentType(ct).entry().query().addParams({ include_applied_variants: "true" }).find();
 stack.contentType(ct).entry(uid).addParams({ include_applied_variants: "true" }).fetch();
 // REST: ...&include_applied_variants=true
-
-// Accepted by the types, never sent (delivery-sdk 5.6.0, core 1.5.2)
-stack.livePreviewQuery({ live_preview: hash, include_applied_variants: true });
-contentstack.stack({ live_preview: { enable: true, include_applied_variants: true } });
 ```
 
 Leave it on for delivery traffic; with no variant applied the response is unchanged. Never pass the
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
index 520cc67..7296df6 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -91,13 +91,12 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 - **symptom**: Variant content renders correctly on the canvas, but Highlight Variant outlines nothing and audience mode shows no variant-specific fields. No error anywhere. Every `data-cslp` on the page is v1 (`<ct>.<uid>.<locale>.<field>`); none starts with `v2:`.
 - **frameworks**: any
 - **rendering_modes**: any
-- **root_cause**: `addEditableTags()` emits a `v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>` tag only for fields listed in the entry's `_applied_variants`. That map is in the response only when the content request carries `include_applied_variants=true`. Without it every tag is v1, the SDK parses no variant, and both features have nothing to key on. Content still renders correctly because the Preview Service already applied the variant, which is why this looks like a highlighting bug rather than a fetch problem. Two places look like they set the flag and do not: `livePreviewQuery({ include_applied_variants: true })` and `include_applied_variants` on the Stack's `live_preview` config are accepted by the delivery-sdk types and stored, but `@contentstack/core` never reads them off that config, so the flag never reaches the request (checked against delivery-sdk 5.6.0, core 1.5.2).
+- **root_cause**: `addEditableTags()` emits a `v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>` tag only for fields listed in the entry's `_applied_variants`. That map is in the response only when the content request carries `include_applied_variants=true`. Without it every tag is v1, the SDK parses no variant, and both features have nothing to key on. Content still renders correctly because the Preview Service already applied the variant, which is why this looks like a highlighting bug rather than a fetch problem.
 - **fix**:
   1. Pass it as a query parameter on the content request itself. Delivery SDK: `.addParams({ include_applied_variants: "true" })` on the query chain (`.entry().query().addParams(...)`) or on a single-entry fetch (`.entry(uid).addParams(...)`). REST: append `include_applied_variants=true` to the URL.
-  2. Do not route it through `livePreviewQuery()` or the Stack `live_preview` config. Both drop it silently.
-  3. Leave it on for delivery traffic too. When no variant applies the response carries no `_applied_variants` and is otherwise unchanged, so a preview-only branch buys nothing.
-  4. One flag on the page query covers referenced entries that `includeReference()` resolved; `addEditableTags()` reads `_applied_variants` per reference.
-  5. Never pass the variant uid yourself. The Preview Service applies it from the UI selection; `Entries.variants()` and `x-cs-variant-uid` are for regular delivery.
+  2. Leave it on for delivery traffic too. When no variant applies the response carries no `_applied_variants` and is otherwise unchanged, so a preview-only branch buys nothing.
+  3. One flag on the page query covers referenced entries that `includeReference()` resolved; `addEditableTags()` reads `_applied_variants` per reference.
+  4. Never pass the variant uid yourself. The Preview Service applies it from the UI selection; `Entries.variants()` and `x-cs-variant-uid` are for regular delivery.
 - **verification**: With a variant selected, inspect a variantised field in DevTools. Its `data-cslp` starts with `v2:` and the entry segment reads `<entry_uid>_<variant_uid>`. Highlight Variant now outlines it.
 
 ---
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md b/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
index 54f246d..f045012 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
@@ -106,18 +106,13 @@ Hover and click on the marked wrapper draw no outline; the button is the afforda
 Highlight Variant and audience mode key on v2 tags:
 `v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>`. `addEditableTags()` emits them only for fields
 listed in the entry's `_applied_variants`, and the response includes that map only when the request
-carries `include_applied_variants=true`. Pass it on the content request, not on the Live Preview
-config:
+carries `include_applied_variants=true`. Pass it as a query parameter on the content request:
 
 ```js
 // Honoured: a query parameter on the request itself
 stack.contentType(ct).entry().query().addParams({ include_applied_variants: "true" }).find();
 stack.contentType(ct).entry(uid).addParams({ include_applied_variants: "true" }).fetch();
 // REST: ...&include_applied_variants=true
-
-// Accepted by the types, never sent (delivery-sdk 5.6.0, core 1.5.2)
-stack.livePreviewQuery({ live_preview: hash, include_applied_variants: true });
-contentstack.stack({ live_preview: { enable: true, include_applied_variants: true } });
 ```
 
 Leave it on for delivery traffic; with no variant applied the response is unchanged. Never pass the
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
index 520cc67..7296df6 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -91,13 +91,12 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 - **symptom**: Variant content renders correctly on the canvas, but Highlight Variant outlines nothing and audience mode shows no variant-specific fields. No error anywhere. Every `data-cslp` on the page is v1 (`<ct>.<uid>.<locale>.<field>`); none starts with `v2:`.
 - **frameworks**: any
 - **rendering_modes**: any
-- **root_cause**: `addEditableTags()` emits a `v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>` tag only for fields listed in the entry's `_applied_variants`. That map is in the response only when the content request carries `include_applied_variants=true`. Without it every tag is v1, the SDK parses no variant, and both features have nothing to key on. Content still renders correctly because the Preview Service already applied the variant, which is why this looks like a highlighting bug rather than a fetch problem. Two places look like they set the flag and do not: `livePreviewQuery({ include_applied_variants: true })` and `include_applied_variants` on the Stack's `live_preview` config are accepted by the delivery-sdk types and stored, but `@contentstack/core` never reads them off that config, so the flag never reaches the request (checked against delivery-sdk 5.6.0, core 1.5.2).
+- **root_cause**: `addEditableTags()` emits a `v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>` tag only for fields listed in the entry's `_applied_variants`. That map is in the response only when the content request carries `include_applied_variants=true`. Without it every tag is v1, the SDK parses no variant, and both features have nothing to key on. Content still renders correctly because the Preview Service already applied the variant, which is why this looks like a highlighting bug rather than a fetch problem.
 - **fix**:
   1. Pass it as a query parameter on the content request itself. Delivery SDK: `.addParams({ include_applied_variants: "true" })` on the query chain (`.entry().query().addParams(...)`) or on a single-entry fetch (`.entry(uid).addParams(...)`). REST: append `include_applied_variants=true` to the URL.
-  2. Do not route it through `livePreviewQuery()` or the Stack `live_preview` config. Both drop it silently.
-  3. Leave it on for delivery traffic too. When no variant applies the response carries no `_applied_variants` and is otherwise unchanged, so a preview-only branch buys nothing.
-  4. One flag on the page query covers referenced entries that `includeReference()` resolved; `addEditableTags()` reads `_applied_variants` per reference.
-  5. Never pass the variant uid yourself. The Preview Service applies it from the UI selection; `Entries.variants()` and `x-cs-variant-uid` are for regular delivery.
+  2. Leave it on for delivery traffic too. When no variant applies the response carries no `_applied_variants` and is otherwise unchanged, so a preview-only branch buys nothing.
+  3. One flag on the page query covers referenced entries that `includeReference()` resolved; `addEditableTags()` reads `_applied_variants` per reference.
+  4. Never pass the variant uid yourself. The Preview Service applies it from the UI selection; `Entries.variants()` and `x-cs-variant-uid` are for regular delivery.
 - **verification**: With a variant selected, inspect a variantised field in DevTools. Its `data-cslp` starts with `v2:` and the entry segment reads `<entry_uid>_<variant_uid>`. Highlight Variant now outlines it.
 
 ---

From e94588f532f24a6dbea5d28b39e3d4f5509f132d Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Tue, 8 Sep 2026 12:30:13 +0530
Subject: [PATCH 12/21] docs(skills): describe the Timeline onboarding check as
 it renders

The skill described Timeline's check as one card whose failure labels
were "Set default environment", "Use updated SDK" and "Use preview
token". Those are the Heap analytics strings, not what the editor shows.

Rewrite from OnboardingOverlay.tsx and useOnboardingValidations.tsx:

- Two surfaces. A small status card while the check runs (Default
  Environment, Live Preview SDK, Preview Token, All Set!), then a
  full-pane "Set Up Timeline" overlay listing three items with a status
  circle each once one fails: Configure the environment, Install the
  latest Live Preview SDK, Generate and use Preview Token.
- The items are chained, so the first empty circle is the failure and
  the ones below it never ran.
- Pass conditions per item: environment resolves from URL or default
  preview environment; init handshake received with SDK major >= 2;
  tracker reports a Preview Service version within a ~9 s poll.
- Timing: overlay after 10 s from the last status change, 1 s when no
  environment resolves. Replaces the vague "fixed delay".
- Suppression: overlay X is view-only; status-card X is role-gated
  between session storage and the stack setting.

Add a Timeline row to setup-docs.md pointing at the Set Up Timeline page
the overlay links to. Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../SKILL.md                                  | 17 +++---
 .../references/faq-timeline.md                |  3 +-
 .../references/onboarding-check.md            | 56 +++++++++++++------
 .../references/setup-docs.md                  |  8 +++
 ...review-visual-editor-support-assistant.mdc | 17 +++---
 .../SKILL.md                                  | 17 +++---
 .../references/faq-timeline.md                |  3 +-
 .../references/onboarding-check.md            | 56 +++++++++++++------
 .../references/setup-docs.md                  |  8 +++
 9 files changed, 128 insertions(+), 57 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
index b341f3f..5dc43fa 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -174,16 +174,19 @@ Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token
 customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
 Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
 
-**Timeline runs a third check.** Three gates, so do not map a Timeline card onto either table:
+**Timeline runs a third check.** A small status card while it runs, then a full-pane "Set Up
+Timeline" overlay with three items once one fails. The items are chained, so the first empty circle
+is the failure and the ones below it never ran:
 
-| Card | Localises to |
+| Overlay item | Localises to |
 |---|---|
-| Default Environment | No default preview environment on the stack |
-| Live Preview SDK | SDK version below the supported minimum |
-| Preview Token | Requests are not using the Preview Service |
+| Configure the environment | No environment on the Timeline URL and no default preview environment on the stack |
+| Install the latest Live Preview SDK | The `init()` handshake never reached Timeline, or the SDK major version is below 2 |
+| Generate and use Preview Token | No content request hit the Preview Service inside the polling window |
 
-Timeline's check also waits a fixed delay before declaring failure, so a slow site can produce a
-failure card on a correct setup. Have the user reopen the panel on a warm cache before believing it.
+The overlay appears ten seconds after the last status change and item 3 polls for about nine, so a
+slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
+before believing it.
 
 Two readings that decide the whole branch:
 
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
index 52e93ba..53b4f72 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
@@ -1,8 +1,7 @@
 # Timeline FAQ
 
 Timeline previews an entry at a point in time. It shares the Live Preview SDK and the same preview
-host, but it is a distinct product: it has its own Onboarding Check with three gates rather than
-five (see [onboarding-check.md](onboarding-check.md)), and it carries a `preview_timestamp` alongside the usual
+host, but it is a distinct product: it has its own Onboarding Check with three chained items (see [onboarding-check.md](onboarding-check.md)), and it carries a `preview_timestamp` alongside the usual
 `live_preview` hash.
 
 If plain Live Preview does not work, fix that first — everything here assumes the preview path is
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index f68e86f..e2baf86 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -3,19 +3,22 @@
 Every visual experience product ships a setup check that runs automatically when its panel opens.
 There are **three** of them, and they differ in both gates and shape: Live Preview shows one card
 with the first failing gate; Visual Editor shows a six-item list with a status per item; Timeline
-shows one card with three gates. Confirm which product the user is in before reading anything below. It is the highest-yield thing to ask
+shows a small status card while it checks, then a full-pane "Set Up Timeline" overlay listing three
+items with a status each once one fails. Confirm which product the user is in before reading anything below. It is the highest-yield thing to ask
 about, because it has already run the diagnosis the user is asking you to do.
 
 **Always ask for a screenshot of this card before asking anything else.** The step name on it
 localises the problem to one gate, and because of how the check is structured, it also tells you
 everything that already passed.
 
-## The property that makes the Live Preview and Timeline cards powerful
+## The property that makes the Live Preview and Timeline checks powerful
 
-For Live Preview and Timeline the gates are evaluated as a single ordered chain that stops at the
-first failure, so only one step is ever shown. **Visual Editor is different**: every item is evaluated
+For Live Preview the gates are evaluated as a single ordered chain that stops at the first failure,
+so only one step is ever shown. Timeline's three items are chained the same way, each evaluated only
+after the previous one passed, so on its overlay the first empty circle is the failure and the ones
+below it never ran. **Visual Editor is different**: every item is evaluated
 independently and shown with its own status, so read the whole list rather than one card. The
-inference below applies to the single-card checks only.
+inference below applies to the two chained checks, Live Preview and Timeline, not to Visual Editor.
 
 So a card reading "Preview Service Not Enabled" is not just one fact. It proves the website loaded
 in the frame, the SDK initialised, and the SDK version is supported. Three contracts are already
@@ -68,18 +71,39 @@ Two consequences worth stating:
 
 ## Timeline
 
-Timeline runs its own check with three gates, not Live Preview's five or Visual Editor's six. Do not
-map any of the three onto another.
+Timeline runs its own check with three items, not Live Preview's five or Visual Editor's six. Do not
+map any of them onto another table. It has two surfaces:
 
-| # | Card | On failure | Meaning |
+1. **A small status card** at the bottom of the pane while the check runs. Its header names the item
+   under test: "Default Environment", then "Live Preview SDK", then "Preview Token", then "All Set!".
+   When everything passes it shows All Set! and disappears about two seconds later.
+2. **A full-pane "Set Up Timeline" overlay** that replaces the card when an item fails. It lists all
+   three items under "Get Started", each with a filled or empty circle. This is the screenshot to ask
+   for.
+
+| # | Overlay item | Passes when | Empty circle means |
 |---|---|---|---|
-| 1 | Default Environment | Set default environment | No default environment configured |
-| 2 | Live Preview SDK | Use updated SDK | SDK version below the supported minimum |
-| 3 | Preview Token | Use preview token | Requests are not using the Preview Service |
+| 1 | Configure the environment | an environment resolves for the session: the `environment` on the Timeline URL, falling back to the stack's default preview environment (`live_preview.default-env`) | no environment on the URL and no default preview environment in stack settings |
+| 2 | Install the latest Live Preview SDK | item 1 passed and the SDK's `init()` handshake reached Timeline with a major version of 2 or higher | `init()` never ran inside the frame, or the SDK is 1.x |
+| 3 | Generate and use Preview Token | item 2 passed and, inside the polling window, the tracker for this session's hash reports a REST or GraphQL Preview Service version, meaning a content request hit the Preview Service | the site fetched from the delivery CDN, or fetched nothing in time |
+
+The items are chained: 2 is only evaluated after 1 passes, 3 only after 2. Read the **first** empty
+circle. The ones below it never ran and tell you nothing.
+
+**Timing.** The overlay appears ten seconds after the last status change if anything is still
+unchecked, or after one second when no environment resolves at all. Item 3 polls the tracker up to
+five times, first after one second and then every two, roughly a nine-second window. A site whose
+first preview request lands later than that shows item 3 empty on a correct setup. Have the user
+reopen the panel on a warm cache before believing it.
+
+**Links on the overlay.** "Configure" opens Settings → Live Preview for the stack. "Install" and
+"Preview Token" open help articles. The footer links to the Set Up Timeline documentation page.
 
-**Timeline's check has a fixed delay before it declares failure.** A site slower than that window
-produces a failure card even though the setup is correct. If a Timeline user reports a failing gate
-on a site you know is slow, have them re-open the panel on a warm cache before believing the card.
+**Closing it.** The X on the full overlay hides it for the current view only; nothing is stored. The
+X on the small status card is where suppression happens: owners, admins and developers get a modal
+offering "this session" (browser storage, per stack) or "for everyone" (writes
+`timeline.onboarding-setup-visible: false` to stack settings); any other role gets the session
+suppression silently.
 
 ## What the check does not cover
 
@@ -136,6 +160,6 @@ Ask for the screenshot rather than the wording. Users paraphrase the step name i
 one, and since each name maps to a specific gate, a paraphrase can send you down the wrong branch.
 
 If they cannot screenshot it, ask for the exact step name and body text as displayed, and confirm
-which product they are in. Live Preview and Timeline share a single-card style but not a set of
-gates, and Visual Editor's is a six-item list; a paraphrased step name from the wrong product sends
+which product they are in. Live Preview shows one card, Timeline a three-item overlay, Visual Editor
+a six-item list, and none of them share gates; a paraphrased step name from the wrong product sends
 you down the wrong branch.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index bb5a26a..8c41895 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -37,6 +37,14 @@ fail Visual Editor's Verify Mode gate until the mode is changed from `"preview"`
 - [Set Up Visual Editor for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-editor/set-up-visual-editor-for-your-website)
 - [Set Up Live Edit Tags for Entries with REST](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-edit-tags-for-entries-with-rest) — the `addEditableTags()` reference
 
+### Timeline
+
+Timeline sits on the same Live Preview integration: `init()` in the frame and the Preview Service on
+the fetch. On top of that the site has to forward `preview_timestamp` next to the hash on every
+request. Its onboarding overlay links to this page:
+
+- [Set Up Timeline](https://www.contentstack.com/docs/developers/set-up-timeline)
+
 ### Starters
 
 [Kickstart Next.js](https://www.contentstack.com/docs/developers/kickstarts/next) and its siblings
diff --git a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
index 4f0a331..a4ca859 100644
--- a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
+++ b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
@@ -177,16 +177,19 @@ Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token
 customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
 Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
 
-**Timeline runs a third check.** Three gates, so do not map a Timeline card onto either table:
+**Timeline runs a third check.** A small status card while it runs, then a full-pane "Set Up
+Timeline" overlay with three items once one fails. The items are chained, so the first empty circle
+is the failure and the ones below it never ran:
 
-| Card | Localises to |
+| Overlay item | Localises to |
 |---|---|
-| Default Environment | No default preview environment on the stack |
-| Live Preview SDK | SDK version below the supported minimum |
-| Preview Token | Requests are not using the Preview Service |
+| Configure the environment | No environment on the Timeline URL and no default preview environment on the stack |
+| Install the latest Live Preview SDK | The `init()` handshake never reached Timeline, or the SDK major version is below 2 |
+| Generate and use Preview Token | No content request hit the Preview Service inside the polling window |
 
-Timeline's check also waits a fixed delay before declaring failure, so a slow site can produce a
-failure card on a correct setup. Have the user reopen the panel on a warm cache before believing it.
+The overlay appears ten seconds after the last status change and item 3 polls for about nine, so a
+slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
+before believing it.
 
 Two readings that decide the whole branch:
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
index 071e741..2ec2afb 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -177,16 +177,19 @@ Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token
 customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
 Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
 
-**Timeline runs a third check.** Three gates, so do not map a Timeline card onto either table:
+**Timeline runs a third check.** A small status card while it runs, then a full-pane "Set Up
+Timeline" overlay with three items once one fails. The items are chained, so the first empty circle
+is the failure and the ones below it never ran:
 
-| Card | Localises to |
+| Overlay item | Localises to |
 |---|---|
-| Default Environment | No default preview environment on the stack |
-| Live Preview SDK | SDK version below the supported minimum |
-| Preview Token | Requests are not using the Preview Service |
+| Configure the environment | No environment on the Timeline URL and no default preview environment on the stack |
+| Install the latest Live Preview SDK | The `init()` handshake never reached Timeline, or the SDK major version is below 2 |
+| Generate and use Preview Token | No content request hit the Preview Service inside the polling window |
 
-Timeline's check also waits a fixed delay before declaring failure, so a slow site can produce a
-failure card on a correct setup. Have the user reopen the panel on a warm cache before believing it.
+The overlay appears ten seconds after the last status change and item 3 polls for about nine, so a
+slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
+before believing it.
 
 Two readings that decide the whole branch:
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
index 52e93ba..53b4f72 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
@@ -1,8 +1,7 @@
 # Timeline FAQ
 
 Timeline previews an entry at a point in time. It shares the Live Preview SDK and the same preview
-host, but it is a distinct product: it has its own Onboarding Check with three gates rather than
-five (see [onboarding-check.md](onboarding-check.md)), and it carries a `preview_timestamp` alongside the usual
+host, but it is a distinct product: it has its own Onboarding Check with three chained items (see [onboarding-check.md](onboarding-check.md)), and it carries a `preview_timestamp` alongside the usual
 `live_preview` hash.
 
 If plain Live Preview does not work, fix that first — everything here assumes the preview path is
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index f68e86f..e2baf86 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -3,19 +3,22 @@
 Every visual experience product ships a setup check that runs automatically when its panel opens.
 There are **three** of them, and they differ in both gates and shape: Live Preview shows one card
 with the first failing gate; Visual Editor shows a six-item list with a status per item; Timeline
-shows one card with three gates. Confirm which product the user is in before reading anything below. It is the highest-yield thing to ask
+shows a small status card while it checks, then a full-pane "Set Up Timeline" overlay listing three
+items with a status each once one fails. Confirm which product the user is in before reading anything below. It is the highest-yield thing to ask
 about, because it has already run the diagnosis the user is asking you to do.
 
 **Always ask for a screenshot of this card before asking anything else.** The step name on it
 localises the problem to one gate, and because of how the check is structured, it also tells you
 everything that already passed.
 
-## The property that makes the Live Preview and Timeline cards powerful
+## The property that makes the Live Preview and Timeline checks powerful
 
-For Live Preview and Timeline the gates are evaluated as a single ordered chain that stops at the
-first failure, so only one step is ever shown. **Visual Editor is different**: every item is evaluated
+For Live Preview the gates are evaluated as a single ordered chain that stops at the first failure,
+so only one step is ever shown. Timeline's three items are chained the same way, each evaluated only
+after the previous one passed, so on its overlay the first empty circle is the failure and the ones
+below it never ran. **Visual Editor is different**: every item is evaluated
 independently and shown with its own status, so read the whole list rather than one card. The
-inference below applies to the single-card checks only.
+inference below applies to the two chained checks, Live Preview and Timeline, not to Visual Editor.
 
 So a card reading "Preview Service Not Enabled" is not just one fact. It proves the website loaded
 in the frame, the SDK initialised, and the SDK version is supported. Three contracts are already
@@ -68,18 +71,39 @@ Two consequences worth stating:
 
 ## Timeline
 
-Timeline runs its own check with three gates, not Live Preview's five or Visual Editor's six. Do not
-map any of the three onto another.
+Timeline runs its own check with three items, not Live Preview's five or Visual Editor's six. Do not
+map any of them onto another table. It has two surfaces:
 
-| # | Card | On failure | Meaning |
+1. **A small status card** at the bottom of the pane while the check runs. Its header names the item
+   under test: "Default Environment", then "Live Preview SDK", then "Preview Token", then "All Set!".
+   When everything passes it shows All Set! and disappears about two seconds later.
+2. **A full-pane "Set Up Timeline" overlay** that replaces the card when an item fails. It lists all
+   three items under "Get Started", each with a filled or empty circle. This is the screenshot to ask
+   for.
+
+| # | Overlay item | Passes when | Empty circle means |
 |---|---|---|---|
-| 1 | Default Environment | Set default environment | No default environment configured |
-| 2 | Live Preview SDK | Use updated SDK | SDK version below the supported minimum |
-| 3 | Preview Token | Use preview token | Requests are not using the Preview Service |
+| 1 | Configure the environment | an environment resolves for the session: the `environment` on the Timeline URL, falling back to the stack's default preview environment (`live_preview.default-env`) | no environment on the URL and no default preview environment in stack settings |
+| 2 | Install the latest Live Preview SDK | item 1 passed and the SDK's `init()` handshake reached Timeline with a major version of 2 or higher | `init()` never ran inside the frame, or the SDK is 1.x |
+| 3 | Generate and use Preview Token | item 2 passed and, inside the polling window, the tracker for this session's hash reports a REST or GraphQL Preview Service version, meaning a content request hit the Preview Service | the site fetched from the delivery CDN, or fetched nothing in time |
+
+The items are chained: 2 is only evaluated after 1 passes, 3 only after 2. Read the **first** empty
+circle. The ones below it never ran and tell you nothing.
+
+**Timing.** The overlay appears ten seconds after the last status change if anything is still
+unchecked, or after one second when no environment resolves at all. Item 3 polls the tracker up to
+five times, first after one second and then every two, roughly a nine-second window. A site whose
+first preview request lands later than that shows item 3 empty on a correct setup. Have the user
+reopen the panel on a warm cache before believing it.
+
+**Links on the overlay.** "Configure" opens Settings → Live Preview for the stack. "Install" and
+"Preview Token" open help articles. The footer links to the Set Up Timeline documentation page.
 
-**Timeline's check has a fixed delay before it declares failure.** A site slower than that window
-produces a failure card even though the setup is correct. If a Timeline user reports a failing gate
-on a site you know is slow, have them re-open the panel on a warm cache before believing the card.
+**Closing it.** The X on the full overlay hides it for the current view only; nothing is stored. The
+X on the small status card is where suppression happens: owners, admins and developers get a modal
+offering "this session" (browser storage, per stack) or "for everyone" (writes
+`timeline.onboarding-setup-visible: false` to stack settings); any other role gets the session
+suppression silently.
 
 ## What the check does not cover
 
@@ -136,6 +160,6 @@ Ask for the screenshot rather than the wording. Users paraphrase the step name i
 one, and since each name maps to a specific gate, a paraphrase can send you down the wrong branch.
 
 If they cannot screenshot it, ask for the exact step name and body text as displayed, and confirm
-which product they are in. Live Preview and Timeline share a single-card style but not a set of
-gates, and Visual Editor's is a six-item list; a paraphrased step name from the wrong product sends
+which product they are in. Live Preview shows one card, Timeline a three-item overlay, Visual Editor
+a six-item list, and none of them share gates; a paraphrased step name from the wrong product sends
 you down the wrong branch.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index bb5a26a..8c41895 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -37,6 +37,14 @@ fail Visual Editor's Verify Mode gate until the mode is changed from `"preview"`
 - [Set Up Visual Editor for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-editor/set-up-visual-editor-for-your-website)
 - [Set Up Live Edit Tags for Entries with REST](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-edit-tags-for-entries-with-rest) — the `addEditableTags()` reference
 
+### Timeline
+
+Timeline sits on the same Live Preview integration: `init()` in the frame and the Preview Service on
+the fetch. On top of that the site has to forward `preview_timestamp` next to the hash on every
+request. Its onboarding overlay links to this page:
+
+- [Set Up Timeline](https://www.contentstack.com/docs/developers/set-up-timeline)
+
 ### Starters
 
 [Kickstart Next.js](https://www.contentstack.com/docs/developers/kickstarts/next) and its siblings

From beab56fab74c6acf96d12ecdccc2055e61058ef6 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Tue, 8 Sep 2026 17:08:11 +0530
Subject: [PATCH 13/21] docs(skills): link the Custom Preview URLs docs instead
 of restating syntax

Two FAQ steps carried their own placeholder examples and a description
of Base URL aliases. Replace those with a link to the Custom Preview
URLs documentation page, which owns the pattern syntax and the current
placeholder list, and add the same pointer to setup-docs.md next to the
Live Preview pages.

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../references/faq-preview-runtime.md                         | 2 +-
 .../references/faq-setup.md                                   | 2 +-
 .../references/setup-docs.md                                  | 4 ++++
 .../references/faq-preview-runtime.md                         | 2 +-
 .../references/faq-setup.md                                   | 2 +-
 .../references/setup-docs.md                                  | 4 ++++
 6 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
index 5527067..3108fea 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -78,7 +78,7 @@ the fixes here will help.
 - **fix**:
   1. Preserve `live_preview`, `content_type_uid`, `entry_uid`, and `preview_timestamp` in the URL across programmatic navigations, or trigger a hard navigation inside the preview.
   2. For routes that cannot be derived from the entry `url` field, enable **Custom Preview URLs** and then call `setPageContext({ entryUid, contentTypeUid })` on each page (Live Preview Utils v4.4.4+). The call only takes effect when Custom Preview URLs is configured and enabled on the plan; otherwise it is silently ignored and the editor keeps resolving by URL.
-  3. For non-trivial URL structures, configure **Custom Preview URLs** in Settings → Visual Experience → Preview URL with placeholders (e.g. `/blog/{{entry.category}}/{{entry.slug}}`) and base URL aliases.
+  3. For non-trivial URL structures, configure **Custom Preview URLs** in Settings → Visual Experience → Preview URL, following [the docs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls) for patterns and Base URL aliases.
   4. Confirm every route allows iframe embedding, not just the root — an `X-Frame-Options` or CSP `frame-ancestors` header, or a hard redirect to a different host, on a deep route will break navigation inside the panel.
 - **verification**: Click through the site's own nav inside the preview panel; the URL keeps its preview params and edits still apply on the new page.
 
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
index a960ae6..600d30c 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
@@ -92,7 +92,7 @@ contract tells you which section to read; this file tells you what to do.
 - **rendering_modes**: any
 - **root_cause**: By default the preview URL is `environment Base URL` + the entry's `url` field. That only works when app routing maps 1:1 to the `url` field. Nested paths, custom route prefixes, several content types with different URL shapes, multiple sites served from one stack, or a URL stored in a custom text field instead of the built-in `url` field all break the concatenation.
 - **fix**:
-  1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL) with pattern placeholders such as `/blog/{{entry.category}}/{{entry.slug}}`, plus Base URL aliases when several hostnames map to one stack. This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated and has to be enabled on the account.
+  1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL). This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated. Follow the docs for the pattern syntax, placeholders, Base URL aliases and defaults: [Custom Preview URLs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls).
   2. With Custom Preview URLs enabled, tell the editor which entry each page is by calling `setPageContext({ entryUid, contentTypeUid })` on every page (Live Preview Utils v4.4.4+). Fallbacks: the `window.__CS_PAGE_CONTEXT__` global, or `<meta name="contentstack:entry-uid">` and `<meta name="contentstack:content-type-uid">`. **This only has an effect when Custom Preview URLs is configured and enabled on the plan.** Without it the editor resolves by URL alone and the call is silently ignored — it does not error, so a missing feature flag looks like `setPageContext` not working.
   3. Do not narrow the environment Base URL to one content type's prefix (for example `.../inspiration/articles/`) — that fixes one content type and breaks all others.
   4. Verify the entry's `url` field actually corresponds to a route the app serves, and that the route renders the content type you expect.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 8c41895..5da51f9 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -27,6 +27,10 @@ Establish framework and rendering mode first, then route.
 | Any framework, SSG | [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-static-site-generator-ssg) — runs in CSR mode, `ssr: false` |
 | Any framework, SSR over REST | [Set Up Live Preview with REST for Server-Side Rendering](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-with-rest-for-server-side-rendering) |
 
+When app routing does not map 1:1 onto `Base URL + entry.url`, or `setPageContext()` is in play, the
+relevant page is [Custom Preview URLs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls). Point to it rather than
+restating its pattern syntax; it is plan-gated and the page carries the current placeholder list.
+
 ### Visual Editor, on top of a working Live Preview
 
 Visual Editor is not a separate integration. It is Live Preview plus edit tags plus `mode: "builder"`
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
index 5527067..3108fea 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -78,7 +78,7 @@ the fixes here will help.
 - **fix**:
   1. Preserve `live_preview`, `content_type_uid`, `entry_uid`, and `preview_timestamp` in the URL across programmatic navigations, or trigger a hard navigation inside the preview.
   2. For routes that cannot be derived from the entry `url` field, enable **Custom Preview URLs** and then call `setPageContext({ entryUid, contentTypeUid })` on each page (Live Preview Utils v4.4.4+). The call only takes effect when Custom Preview URLs is configured and enabled on the plan; otherwise it is silently ignored and the editor keeps resolving by URL.
-  3. For non-trivial URL structures, configure **Custom Preview URLs** in Settings → Visual Experience → Preview URL with placeholders (e.g. `/blog/{{entry.category}}/{{entry.slug}}`) and base URL aliases.
+  3. For non-trivial URL structures, configure **Custom Preview URLs** in Settings → Visual Experience → Preview URL, following [the docs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls) for patterns and Base URL aliases.
   4. Confirm every route allows iframe embedding, not just the root — an `X-Frame-Options` or CSP `frame-ancestors` header, or a hard redirect to a different host, on a deep route will break navigation inside the panel.
 - **verification**: Click through the site's own nav inside the preview panel; the URL keeps its preview params and edits still apply on the new page.
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
index a960ae6..600d30c 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
@@ -92,7 +92,7 @@ contract tells you which section to read; this file tells you what to do.
 - **rendering_modes**: any
 - **root_cause**: By default the preview URL is `environment Base URL` + the entry's `url` field. That only works when app routing maps 1:1 to the `url` field. Nested paths, custom route prefixes, several content types with different URL shapes, multiple sites served from one stack, or a URL stored in a custom text field instead of the built-in `url` field all break the concatenation.
 - **fix**:
-  1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL) with pattern placeholders such as `/blog/{{entry.category}}/{{entry.slug}}`, plus Base URL aliases when several hostnames map to one stack. This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated and has to be enabled on the account.
+  1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL). This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated. Follow the docs for the pattern syntax, placeholders, Base URL aliases and defaults: [Custom Preview URLs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls).
   2. With Custom Preview URLs enabled, tell the editor which entry each page is by calling `setPageContext({ entryUid, contentTypeUid })` on every page (Live Preview Utils v4.4.4+). Fallbacks: the `window.__CS_PAGE_CONTEXT__` global, or `<meta name="contentstack:entry-uid">` and `<meta name="contentstack:content-type-uid">`. **This only has an effect when Custom Preview URLs is configured and enabled on the plan.** Without it the editor resolves by URL alone and the call is silently ignored — it does not error, so a missing feature flag looks like `setPageContext` not working.
   3. Do not narrow the environment Base URL to one content type's prefix (for example `.../inspiration/articles/`) — that fixes one content type and breaks all others.
   4. Verify the entry's `url` field actually corresponds to a route the app serves, and that the route renders the content type you expect.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 8c41895..5da51f9 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -27,6 +27,10 @@ Establish framework and rendering mode first, then route.
 | Any framework, SSG | [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-static-site-generator-ssg) — runs in CSR mode, `ssr: false` |
 | Any framework, SSR over REST | [Set Up Live Preview with REST for Server-Side Rendering](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-with-rest-for-server-side-rendering) |
 
+When app routing does not map 1:1 onto `Base URL + entry.url`, or `setPageContext()` is in play, the
+relevant page is [Custom Preview URLs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls). Point to it rather than
+restating its pattern syntax; it is plan-gated and the page carries the current placeholder list.
+
 ### Visual Editor, on top of a working Live Preview
 
 Visual Editor is not a separate integration. It is Live Preview plus edit tags plus `mode: "builder"`

From 39c13c74fb0f4516777a0bed5eb565f769e9cd11 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Tue, 8 Sep 2026 17:15:38 +0530
Subject: [PATCH 14/21] docs(skills): separate the HTTP and
 untrusted-certificate cases

Both blank the preview frame at the first Live Preview gate, but they
differ in what the customer can do. Plain HTTP inside the HTTPS app is
mixed content and the browser blocks it with no bypass. An untrusted
certificate (self-signed localhost, corporate CA) can be accepted by
opening the preview URL in its own tab and proceeding past the warning;
the browser keeps that exception for the origin and the pane loads on
reload. State both in preflight item 6 and the gate-1 row.

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../references/onboarding-check.md                          | 2 +-
 .../references/preflight-checklist.md                       | 6 +++++-
 .../references/onboarding-check.md                          | 2 +-
 .../references/preflight-checklist.md                       | 6 +++++-
 4 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index e2baf86..4f051ea 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -33,7 +33,7 @@ Five gates, in this order.
 
 | # | Card while checking | Card on failure | What the failure means |
 |---|---|---|---|
-| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, HTTP or an untrusted certificate, or the browser blocking localhost. Nothing after this ran. |
+| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, HTTP (mixed content, no bypass) or an untrusted certificate (bypass: open the URL in its own tab, accept the warning, reload the pane), or the browser blocking localhost. Nothing after this ran. |
 | 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | The frame loaded but no init handshake arrived. `init()` is in server-only code, the enable flag did not parse as a boolean in the deployed build, the init module was tree-shaken out, or init runs after the check window. |
 | 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake arrived from a version below the supported minimum. Upgrade Live Preview Utils. |
 | 4 | Verifying Preview Service | **Preview Service Not Enabled** | The SDK is fine and the site is fine, but content is not coming from the Preview Service. This is the fetch layer never switching host and headers, which is the most common failure of all. |
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
index 1dc0dd0..ab465e4 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -22,7 +22,11 @@ meaningless.
 
 ## Reachability
 
-6. **The preview host is served over HTTPS** with a trusted certificate.
+6. **The preview host is served over HTTPS.** The Contentstack app is HTTPS, so an `http://` preview
+   URL is mixed content and the browser blocks the frame with no bypass. An untrusted certificate
+   (self-signed localhost, a corporate CA) also blanks the frame, but has a bypass: open the preview
+   URL in its own tab, accept the browser's certificate warning, then reload the preview pane. The
+   browser keeps that exception for the origin.
 7. **`curl -I https://<preview-host>/<a-deep-route>`** returns no `X-Frame-Options`, and a CSP
    `frame-ancestors` that includes the Contentstack app origin. Test a deep route, not the site
    root, and confirm it holds after any redirect.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index e2baf86..4f051ea 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -33,7 +33,7 @@ Five gates, in this order.
 
 | # | Card while checking | Card on failure | What the failure means |
 |---|---|---|---|
-| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, HTTP or an untrusted certificate, or the browser blocking localhost. Nothing after this ran. |
+| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, HTTP (mixed content, no bypass) or an untrusted certificate (bypass: open the URL in its own tab, accept the warning, reload the pane), or the browser blocking localhost. Nothing after this ran. |
 | 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | The frame loaded but no init handshake arrived. `init()` is in server-only code, the enable flag did not parse as a boolean in the deployed build, the init module was tree-shaken out, or init runs after the check window. |
 | 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake arrived from a version below the supported minimum. Upgrade Live Preview Utils. |
 | 4 | Verifying Preview Service | **Preview Service Not Enabled** | The SDK is fine and the site is fine, but content is not coming from the Preview Service. This is the fetch layer never switching host and headers, which is the most common failure of all. |
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
index 1dc0dd0..ab465e4 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -22,7 +22,11 @@ meaningless.
 
 ## Reachability
 
-6. **The preview host is served over HTTPS** with a trusted certificate.
+6. **The preview host is served over HTTPS.** The Contentstack app is HTTPS, so an `http://` preview
+   URL is mixed content and the browser blocks the frame with no bypass. An untrusted certificate
+   (self-signed localhost, a corporate CA) also blanks the frame, but has a bypass: open the preview
+   URL in its own tab, accept the browser's certificate warning, then reload the preview pane. The
+   browser keeps that exception for the origin.
 7. **`curl -I https://<preview-host>/<a-deep-route>`** returns no `X-Frame-Options`, and a CSP
    `frame-ancestors` that includes the Contentstack app origin. Test a deep route, not the site
    root, and confirm it holds after any redirect.

From 2522442304f857330ddd9216f22833ea7baa11f6 Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Tue, 8 Sep 2026 17:23:17 +0530
Subject: [PATCH 15/21] docs(skills): localhost over HTTP is fine; mixed
 content has a bypass

The previous wording said any http:// preview URL is blocked with no
bypass. Two corrections: browsers treat http://localhost as a secure
context, so a plain-HTTP dev server loads in the pane, which is the
common local setup. For other http:// hosts the frame is mixed content
and blocked, but the user can allow insecure content for the
Contentstack app origin (Chrome shield icon or the Insecure content site
setting). Certificate wording unchanged.

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../references/onboarding-check.md                   |  2 +-
 .../references/preflight-checklist.md                | 12 +++++++-----
 .../references/onboarding-check.md                   |  2 +-
 .../references/preflight-checklist.md                | 12 +++++++-----
 4 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index 4f051ea..6eba71e 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -33,7 +33,7 @@ Five gates, in this order.
 
 | # | Card while checking | Card on failure | What the failure means |
 |---|---|---|---|
-| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, HTTP (mixed content, no bypass) or an untrusted certificate (bypass: open the URL in its own tab, accept the warning, reload the pane), or the browser blocking localhost. Nothing after this ran. |
+| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, a non-localhost `http://` host (mixed content; allow insecure content for the app origin) or an untrusted certificate (open the URL in its own tab, accept the warning, reload the pane), or the browser blocking localhost. Nothing after this ran. |
 | 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | The frame loaded but no init handshake arrived. `init()` is in server-only code, the enable flag did not parse as a boolean in the deployed build, the init module was tree-shaken out, or init runs after the check window. |
 | 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake arrived from a version below the supported minimum. Upgrade Live Preview Utils. |
 | 4 | Verifying Preview Service | **Preview Service Not Enabled** | The SDK is fine and the site is fine, but content is not coming from the Preview Service. This is the fetch layer never switching host and headers, which is the most common failure of all. |
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
index ab465e4..79e9f75 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -22,11 +22,13 @@ meaningless.
 
 ## Reachability
 
-6. **The preview host is served over HTTPS.** The Contentstack app is HTTPS, so an `http://` preview
-   URL is mixed content and the browser blocks the frame with no bypass. An untrusted certificate
-   (self-signed localhost, a corporate CA) also blanks the frame, but has a bypass: open the preview
-   URL in its own tab, accept the browser's certificate warning, then reload the preview pane. The
-   browser keeps that exception for the origin.
+6. **The preview host is HTTPS, or it is `localhost`.** Browsers treat `http://localhost` as a secure
+   context, so a plain-HTTP dev server loads in the pane. Any other `http://` host inside the HTTPS app
+   is mixed content and the browser blocks the frame; the user can allow it for the Contentstack app
+   origin (Chrome: the shield icon, or Site settings → Insecure content → Allow). An untrusted
+   certificate (self-signed, corporate CA) blanks the frame too, with its own bypass: open the preview
+   URL in its own tab, accept the certificate warning, reload the pane. The browser keeps that
+   exception for the origin.
 7. **`curl -I https://<preview-host>/<a-deep-route>`** returns no `X-Frame-Options`, and a CSP
    `frame-ancestors` that includes the Contentstack app origin. Test a deep route, not the site
    root, and confirm it holds after any redirect.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index 4f051ea..6eba71e 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -33,7 +33,7 @@ Five gates, in this order.
 
 | # | Card while checking | Card on failure | What the failure means |
 |---|---|---|---|
-| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, HTTP (mixed content, no bypass) or an untrusted certificate (bypass: open the URL in its own tab, accept the warning, reload the pane), or the browser blocking localhost. Nothing after this ran. |
+| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, a non-localhost `http://` host (mixed content; allow insecure content for the app origin) or an untrusted certificate (open the URL in its own tab, accept the warning, reload the pane), or the browser blocking localhost. Nothing after this ran. |
 | 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | The frame loaded but no init handshake arrived. `init()` is in server-only code, the enable flag did not parse as a boolean in the deployed build, the init module was tree-shaken out, or init runs after the check window. |
 | 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake arrived from a version below the supported minimum. Upgrade Live Preview Utils. |
 | 4 | Verifying Preview Service | **Preview Service Not Enabled** | The SDK is fine and the site is fine, but content is not coming from the Preview Service. This is the fetch layer never switching host and headers, which is the most common failure of all. |
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
index ab465e4..79e9f75 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -22,11 +22,13 @@ meaningless.
 
 ## Reachability
 
-6. **The preview host is served over HTTPS.** The Contentstack app is HTTPS, so an `http://` preview
-   URL is mixed content and the browser blocks the frame with no bypass. An untrusted certificate
-   (self-signed localhost, a corporate CA) also blanks the frame, but has a bypass: open the preview
-   URL in its own tab, accept the browser's certificate warning, then reload the preview pane. The
-   browser keeps that exception for the origin.
+6. **The preview host is HTTPS, or it is `localhost`.** Browsers treat `http://localhost` as a secure
+   context, so a plain-HTTP dev server loads in the pane. Any other `http://` host inside the HTTPS app
+   is mixed content and the browser blocks the frame; the user can allow it for the Contentstack app
+   origin (Chrome: the shield icon, or Site settings → Insecure content → Allow). An untrusted
+   certificate (self-signed, corporate CA) blanks the frame too, with its own bypass: open the preview
+   URL in its own tab, accept the certificate warning, reload the pane. The browser keeps that
+   exception for the origin.
 7. **`curl -I https://<preview-host>/<a-deep-route>`** returns no `X-Frame-Options`, and a CSP
    `frame-ancestors` that includes the Contentstack app origin. Test a deep route, not the site
    root, and confirm it holds after any redirect.

From d30117ff53b64bcb9c3ee803fcedb41318015a3e Mon Sep 17 00:00:00 2001
From: hitesh-shetty-cstk <hitesh.shetty@contentstack.com>
Date: Wed, 9 Sep 2026 00:22:02 +0530
Subject: [PATCH 16/21] docs(skills): only ask the customer for things they can
 observe
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The skill pointed readers at Contentstack-app internals as if they were
their own site's evidence. Worst case was contract 1, whose one-look
check was "POST /live-preview/tracker returns 2xx" — a request the
Contentstack app issues, never the customer's site, and one that
succeeds even when init() never ran, so it could not fail for the reason
it existed to detect.

Swept all fourteen files. Removed or re-anchored:

- the tracker POST and tracker-document explanations in contract 1,
  preflight item 12, console-noise, and the 382 entry's fix and
  verification steps, all replaced with the Onboarding Check clearing
  "Live Preview SDK Not Initialized", qualified by the enable flag
- Timeline's "polling window" and "polls the tracker up to five times",
  now stated as what the customer waits on
- the PATCH notice body and the Management-service fetch behind the
  side form, neither of which reaches the customer's network tab
- internal step ids in the Visual Editor table, and the Pages Router
  claim that leaned on an internal sanity fixture
- plan-entitlement wording where a stack settings screen is the real
  observable

Also corrects a wrong claim of mine: Visual Editor's six items are not
independently evaluated. useOnboarding.ts breaks out of the step loop at
the first failure, so the list renders all six but everything below the
first incomplete item is unevaluated. All three products are
first-failure chains and differ only in how much they display.

Preview Sharing now points at its documentation and is named a
content-manager feature rather than an integration.

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../SKILL.md                                  | 16 ++---
 .../references/console-noise.md               |  3 +-
 .../references/contact-support.md             |  2 +-
 .../references/faq-preview-runtime.md         |  4 +-
 .../references/faq-setup.md                   | 18 +++---
 .../references/faq-timeline.md                |  4 +-
 .../references/frameworks.md                  |  5 +-
 .../references/onboarding-check.md            | 60 +++++++++----------
 .../references/preflight-checklist.md         | 11 ++--
 .../references/setup-docs.md                  |  7 +++
 ...review-visual-editor-support-assistant.mdc | 16 ++---
 .../SKILL.md                                  | 16 ++---
 .../references/console-noise.md               |  3 +-
 .../references/contact-support.md             |  2 +-
 .../references/faq-preview-runtime.md         |  4 +-
 .../references/faq-setup.md                   | 18 +++---
 .../references/faq-timeline.md                |  4 +-
 .../references/frameworks.md                  |  5 +-
 .../references/onboarding-check.md            | 60 +++++++++----------
 .../references/preflight-checklist.md         | 11 ++--
 .../references/setup-docs.md                  |  7 +++
 21 files changed, 146 insertions(+), 130 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
index 5dc43fa..a5c846b 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -121,7 +121,7 @@ Onboarding Check, or a failure set.
 | **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
 | **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags **plus** `mode: "builder"` in `init()`. `mode: "preview"` fails its Verify Mode gate even with tags present. Not a separate integration. |
 | **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
-| **Preview Sharing** | Share a preview link externally | Plan-gated. |
+| **Preview Sharing** | Share a preview link externally | Plan-gated, and a content-manager feature rather than an integration. The skill carries no troubleshooting for it; point at [Preview Sharing](https://www.contentstack.com/docs/content-managers/preview-sharing). |
 
 If the user is on Visual Editor, confirm whether plain Live Preview works. If it does not, that is
 the problem, and the Visual Editor symptom is downstream noise.
@@ -168,9 +168,9 @@ so the step shown proves every earlier gate passed:
 | Default Environment Not Set | Setup is fine; no default preview environment on the stack |
 | Setup Complete | Reachability, handshake, version and Preview Service are all fine |
 
-**Visual Editor shows a six-item list, not a card.** Every item is evaluated on its own and carries
-its own status, so read the failing items rather than the first one. Configure environment (Default
-Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
+**Visual Editor shows a six-item list, not a card**, but it still stops evaluating at the first item
+that fails, so read the first incomplete item and ignore the ones under it. Configure environment
+(Default Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
 customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
 Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
 
@@ -182,10 +182,10 @@ is the failure and the ones below it never ran:
 |---|---|
 | Configure the environment | No environment on the Timeline URL and no default preview environment on the stack |
 | Install the latest Live Preview SDK | The `init()` handshake never reached Timeline, or the SDK major version is below 2 |
-| Generate and use Preview Token | No content request hit the Preview Service inside the polling window |
+| Generate and use Preview Token | No content request reached the Preview Service before the check stopped waiting |
 
-The overlay appears ten seconds after the last status change and item 3 polls for about nine, so a
-slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
+The overlay appears ten seconds after the last status change, and item 3 gives up waiting at about
+nine, so a slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
 before believing it.
 
 Two readings that decide the whole branch:
@@ -311,7 +311,7 @@ identically. Name which one is unmet, with the evidence, before proposing anythi
 
 | # | Contract | One-look check |
 |---|---|---|
-| 1 | `init()` runs, on the client, in the deployed build | `POST /live-preview/tracker` returns 2xx when the panel loads |
+| 1 | `init()` runs, on the client, in the deployed build | The Live Preview Onboarding Check moves past "Live Preview SDK Not Initialized" — that item clears only when the SDK's init message reaches the app, which happens only from `init()` |
 | 2 | Edit tags are generated and land on DOM elements | Some rendered element carries `data-cslp` |
 | 3 | The hash reaches the fetch, which switches host plus headers | Content requests hit a `*-preview.contentstack.com` host |
 | 4 | The preview target is reachable in an iframe | The pane renders at all |
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md b/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
index 482347e..2d609f0 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
@@ -19,7 +19,8 @@ Routine. It means a postMessage arrived with no registered listener, which happe
 load and teardown. Appears on working setups.
 
 Never conclude anything from it on its own. It does not affect SSR content, and it is not evidence
-that the handshake failed — check for the tracker POST instead.
+that the handshake failed — read the Live Preview Onboarding Check instead, which sticks on **Live
+Preview SDK Not Initialized** until the SDK's init message arrives.
 
 ### Third-party script errors from ad, consent, or personalisation tags
 
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md b/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
index f361144..db17626 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
@@ -52,7 +52,7 @@ assumption. Keep it to the fields; a Support or Product Engineer wants the facts
 | Started after | new setup (never worked) / release / dependency bump / settings change / role change / nothing known |
 | Failing request | `METHOD host/path → status` — URL redacted, no tokens |
 | Console or server log | one-line excerpt, redacted |
-| Ruled out | contracts verified and how, e.g. "tracker POST 200; `data-cslp` present; requests hit the preview host" |
+| Ruled out | contracts verified and how, e.g. "Onboarding Check past 'Live Preview SDK Not Initialized'; `data-cslp` present; requests hit the preview host" |
 | Suspected category | provisioning / plan gating / browser policy / other |
 | Workaround applied | what, or "none" |
 
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
index 3108fea..cf5377a 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -12,7 +12,7 @@ the fixes here will help.
 - **symptom**: Selecting a variant (or switching audience in Audience Preview) in Visual Experience keeps rendering the base entry. The side form shows the correct variant content, but the canvas does not. A manual browser refresh sometimes fixes it. Clicking into the element shows the correct variant value while the rendered page does not.
 - **frameworks**: Next.js, React, framework-agnostic
 - **rendering_modes**: CSR | SSR
-- **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-setup.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the parent Contentstack UI fetches the entry separately over the Management service. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
+- **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-setup.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the Contentstack UI loads the entry on its own, independently of your site's fetch. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
 - **fix**:
   1. First confirm the preview path works at all: change a plain text field and check the canvas updates. If it does not, fix that first — the variant symptom is downstream of it.
   2. Do **not** pass the variant yourself. The Preview Service resolves it from the UI selection; no `variant` query param, no `Entries.variants()`. Do pass `include_applied_variants=true` as a query parameter on the content request (`.addParams({ include_applied_variants: "true" })`), or the variant renders but Highlight Variant and audience mode have nothing to key on; see `highlight-variant-or-audience-mode-does-nothing` in `faq-visual-editor.md`.
@@ -27,7 +27,7 @@ the fixes here will help.
 
 ### cached-response-serves-stale-preview
 - **bucket**: preview-runtime
-- **symptom**: Preview works on localhost but not on a deployed environment with identical code and config — the setup status can even show "Setup Completed" and every edit return `{"notice":"Live Preview entry updated successfully."}` while the rendered page never changes. Or preview stops updating and only recovers in an incognito window or after a hard reload.
+- **symptom**: Preview works on localhost but not on a deployed environment with identical code and config — the setup status can even show "Setup Completed" and edits go through in the entry form while the rendered page never changes. Or preview stops updating and only recovers in an incognito window or after a hard reload.
 - **frameworks**: Next.js, framework-agnostic
 - **rendering_modes**: SSR | SSG/ISR | edge
 - **root_cause**: A cache sits between the browser and the preview service. Whether or not its key includes the `live_preview` hash, preview requests get a stored payload instead of a live one. Seen with a customer CDN in front of the deployed environment, with an app-level fetch cache, and (on the Contentstack side) with stale JS bundles cached in the browser or CDN after a release. The Contentstack SDKs' own cache policies (`IGNORE_CACHE`, `CACHE_THEN_NETWORK`, `CACHE_ELSE_NETWORK`, `NETWORK_ELSE_CACHE`) do **not** switch themselves off for Live Preview — they cache regardless of the preview config.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
index 600d30c..d08f67d 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
@@ -56,13 +56,13 @@ contract tells you which section to read; this file tells you what to do.
   (a sibling variant is `{"error_message":"Please provide live preview hash in request","error_code":382}`). Often appears the moment `mode: "builder"` is set, or when the site is opened directly rather than from inside the Contentstack preview pane. Sometimes reproduces for one developer and not another on "identical" setups.
 - **frameworks**: Next.js, React, framework-agnostic REST/GraphQL clients
 - **rendering_modes**: CSR, SSR
-- **root_cause**: The `live_preview` hash sent on the request has no matching tracker document. Contentstack creates that tracker with a `POST /live-preview/tracker` when the preview session starts inside the CMS. The error means either (a) the app sent a hardcoded, stale, or hand-invented hash, (b) the app sent `live_preview=true` or an empty value instead of the real hash, or (c) the request was made outside any preview session (the site opened directly, or a custom preview tool that has no way to obtain a hash).
+- **root_cause**: The `live_preview` hash on the request is not one Contentstack issued for a live preview session. Contentstack generates the hash when the entry is opened in the preview pane and hands it to the site: as `?live_preview=<hash>` on the URL for SSR (and when the preview is opened in a new tab), or to the SDK running in the pane for CSR, where it surfaces as `ContentstackLivePreview.hash`. A hash from anywhere else is rejected with this error. The error means either (a) the app sent a hardcoded, stale, or hand-invented hash, (b) the app sent `live_preview=true` or an empty value instead of the real hash, or (c) the request was made outside any preview session (the site opened directly, or a custom preview tool that has no way to obtain a hash).
 - **fix**:
   1. Never hardcode or invent a hash. Read it from `?live_preview=` on the request (SSR) or from `ContentstackLivePreview.hash` (CSR), and skip the preview host entirely when it is absent.
-  2. Confirm the tracker call fires: in DevTools → Network, look for `POST /live-preview/tracker` returning 2xx when the preview pane loads. If it never fires, the SDK did not initialize (check `enable`, the `.env` value actually parsing as `true`, and that `init()` runs on the client).
+  2. Confirm the SDK initialised: the Live Preview Onboarding Check must get past **Live Preview SDK Not Initialized**. That item clears only when the SDK's init message reaches the CMS, and the SDK sends it only when `init()` ran on the client with a truthy `enable`. If it sticks there, check `enable`, the `.env` value actually parsing as `true`, and that `init()` runs on the client.
   3. If the app proxies Contentstack through its own backend, forward the hash end to end. The front end must pass the hash it received to the backend, and the backend must put it in the `live_preview` header.
   4. Building a preview tool entirely outside Contentstack is not supported with a Preview Token alone; the hash originates in the CMS session. Use a dedicated publishing environment for an internal preview tool instead.
-- **verification**: With the entry open in Live Preview, the network log shows a successful tracker POST followed by preview reads returning 200 with the same hash value.
+- **verification**: With the entry open in Live Preview, the site's content requests go to the preview host and return 200, and the 382 error is gone.
 
 ---
 
@@ -93,7 +93,7 @@ contract tells you which section to read; this file tells you what to do.
 - **root_cause**: By default the preview URL is `environment Base URL` + the entry's `url` field. That only works when app routing maps 1:1 to the `url` field. Nested paths, custom route prefixes, several content types with different URL shapes, multiple sites served from one stack, or a URL stored in a custom text field instead of the built-in `url` field all break the concatenation.
 - **fix**:
   1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL). This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated. Follow the docs for the pattern syntax, placeholders, Base URL aliases and defaults: [Custom Preview URLs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls).
-  2. With Custom Preview URLs enabled, tell the editor which entry each page is by calling `setPageContext({ entryUid, contentTypeUid })` on every page (Live Preview Utils v4.4.4+). Fallbacks: the `window.__CS_PAGE_CONTEXT__` global, or `<meta name="contentstack:entry-uid">` and `<meta name="contentstack:content-type-uid">`. **This only has an effect when Custom Preview URLs is configured and enabled on the plan.** Without it the editor resolves by URL alone and the call is silently ignored — it does not error, so a missing feature flag looks like `setPageContext` not working.
+  2. With Custom Preview URLs enabled, tell the editor which entry each page is by calling `setPageContext({ entryUid, contentTypeUid })` on every page (Live Preview Utils v4.4.4+). Fallbacks: the `window.__CS_PAGE_CONTEXT__` global, or `<meta name="contentstack:entry-uid">` and `<meta name="contentstack:content-type-uid">`. **This only has an effect when the Custom Preview URLs setting exists for the stack and is configured.** Without it the editor resolves by URL alone and the call is silently ignored — it does not error, so a stack without the feature looks like `setPageContext` not working.
   3. Do not narrow the environment Base URL to one content type's prefix (for example `.../inspiration/articles/`) — that fixes one content type and breaks all others.
   4. Verify the entry's `url` field actually corresponds to a route the app serves, and that the route renders the content type you expect.
 - **verification**: Open entries from several content types (root page, nested page, no-URL page). Each should load its own page in the preview pane, and the URL bar in the pane should show the real route.
@@ -165,7 +165,7 @@ contract tells you which section to read; this file tells you what to do.
 - **symptom**: Two opposite failures from the same mistake. **(A) Hash never arrives:** `init()` succeeds and `ContentstackLivePreview.hash` is populated on the client, but server-rendered pages still return published content. Deterministic, and only the author notices. **(B) Preview state leaks out:** intermittent, user-dependent wrong content, and the **production** site failing with `The Live Preview tracker is invalid or no longer exists. Create a new tracker to continue.` (error_code 382) or `The requested tracker was created for the 'dev' branch. Access using the 'main' branch is not allowed.`; preview stalling after a while; `TypeError: Cannot read properties of undefined (reading 'uid')` after idle hours in production; two editors seeing each other's content; personalization on the public site stopping resolving per visitor because a cached preview render is being served instead. This one reaches real visitors.
 - **frameworks**: Next.js (App Router and Pages Router), Express/Node, Nuxt
 - **rendering_modes**: SSR | edge
-- **root_cause**: In SSR the SDK does not fetch content. It puts `?live_preview=<hash>&content_type_uid=...&entry_uid=...` on the URL and reloads, and preview state lives **on the Stack instance**. Failure (A) is having two instances: a long-lived "default" Stack for page queries plus a second Stack passed only to `init()`, so the hash never lands on the instance that queries. Failure (B) is having one module-level instance shared across requests: once any request puts it into preview mode, unrelated requests inherit it, and ordinary delivery traffic starts hitting the preview service with a hash that has expired (the tracker lasts about a day; the session hash rotates roughly every 30 minutes) or belongs to another branch. Under concurrency requests can also overwrite each other's config mid-flight.
+- **root_cause**: In SSR the SDK does not fetch content. It puts `?live_preview=<hash>&content_type_uid=...&entry_uid=...` on the URL and reloads, and preview state lives **on the Stack instance**. Failure (A) is having two instances: a long-lived "default" Stack for page queries plus a second Stack passed only to `init()`, so the hash never lands on the instance that queries. Failure (B) is having one module-level instance shared across requests: once any request puts it into preview mode, unrelated requests inherit it, and ordinary delivery traffic starts hitting the preview service with a hash that has expired (hashes are session-scoped and time-limited; the preview session issues a fresh one, so a stored or hardcoded hash eventually fails with the tracker-invalid text above) or belongs to another branch. Under concurrency requests can also overwrite each other's config mid-flight.
 - **fix**:
   1. Create a fresh Delivery SDK instance **per request**. Do not share a module-level Stack, and pass the instance down through request-scoped context rather than importing a singleton. This one change fixes both failures.
   2. Read the hash off the incoming request each time and apply it to that instance: `stack.livePreviewQuery({ live_preview: hash, contentTypeUid, entryUid })`.
@@ -183,7 +183,7 @@ contract tells you which section to read; this file tells you what to do.
 - **symptom**: In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit tags render but do nothing, or nothing at all happens when the entry is edited. The same code works in a Pages Router project.
 - **frameworks**: Next.js App Router
 - **rendering_modes**: SSR, CSR
-- **root_cause**: `ContentstackLivePreview.init()` has to run in the browser. In App Router, code placed in a server component or in the root layout module body never executes client-side, so the SDK never installs its postMessage listeners and never advertises SSR mode.
+- **root_cause**: `ContentstackLivePreview.init()` has to run in the browser. In App Router, code placed in a server component or in the root layout module body never executes client-side, so the SDK never installs its postMessage listeners and the Onboarding Check stays on **Live Preview SDK Not Initialized**.
 - **fix**:
   1. Create a dedicated client component and call `init()` from an effect:
      ```tsx
@@ -288,13 +288,13 @@ contract tells you which section to read; this file tells you what to do.
 - **symptom**: A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days later on its own. Conversely, other teams never see the status card at all when they want to diagnose a failing integration.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: any
-- **root_cause**: Each product keeps its own stack setting, and they do not agree on what "unset" means. Timeline treats an unset value as visible. Live Preview treats an unset value as hidden. Visual Editor depends on whether its settings object exists at all. Meanwhile the Visual Experience settings screen renders the toggle as on whenever the value is unset, so a stack that never explicitly saved the setting can show the toggle on while Live Preview behaves as though it is off. Separately, the checks run asynchronously with a timeout, so the card can appear briefly on a correctly configured site whose first preview fetch is slow, then clear itself once the request lands.
+- **root_cause**: Each product keeps its own stack setting, and they do not agree on what "unset" means. Timeline treats an unset value as visible. Live Preview treats an unset value as hidden. Visual Editor treats an unset value as visible, and also treats a stack with no `visual_builder` settings at all as visible. Meanwhile the Visual Experience settings screen renders the toggle as on whenever the value is unset, so a stack that never explicitly saved the setting can show the toggle on while Live Preview behaves as though it is off. Separately, the checks run asynchronously with a timeout, so the card can appear briefly on a correctly configured site whose first preview fetch is slow, then clear itself once the request lands.
 - **fix**:
-  1. Open Settings → Visual Experience and click Save without changing anything. The form always submits all three products' visibility keys, and an unset value arrives in the form as on, so a single save writes an explicit `true` for Live Preview, Visual Editor and Timeline at once. That removes the unset ambiguity and makes all three agree.
+  1. Open Settings → Visual Experience and click Save without changing anything. Saving once stores the state shown for Live Preview, Visual Editor and Timeline together, and a toggle that was never saved still shows as on, so one save records an explicit on for all three. That removes the unset ambiguity and makes all three agree.
   2. Check the setting for the product actually being used. Live Preview, Visual Editor and Timeline each have their own, under Settings → Visual Experience.
   3. Read the one step the card shows. The gates run as an ordered chain that stops at the first failure, so the card names a single gate — that is the configuration gap, and every gate before it has already passed.
   4. If it still does not appear for one user but does for others, that user dismissed it. The suppression is stored per stack in their browser, and no stack-level save clears it — they need to clear site data for the app origin, or use another browser profile.
-  5. If the card flashes then clears on a working site, no action is needed — the first preview request simply arrived after the check timeout.
+  5. If the card flashes then clears on a working site, no action is needed — the first preview request was simply slow to land.
 - **verification**: Open an entry in the product in question and confirm the status card appears. If it does not appear after saving the setting explicitly, it is being suppressed locally rather than by the stack setting.
 
 ---
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
index 53b4f72..b5b5a83 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
@@ -12,12 +12,12 @@ already good.
 - **symptom**: Timeline preview shows the wrong point in time — either the current version regardless of the date picked, or version 1 of the entry for every timestamp. Reference-field changes that render correctly on the live site, in Live Preview, and in Visual Editor do not show in Timeline. Clicking an internal link inside Timeline preview loses the timestamp and the page reloads twice.
 - **frameworks**: Next.js, React, framework-agnostic
 - **rendering_modes**: CSR | SSR
-- **root_cause**: Timeline adds `preview_timestamp` to the iframe URL alongside the `live_preview` hash, and the site must forward **both** to the preview service. Common failures: (a) the app only forwards the hash; (b) the app calls `stack.livePreviewQuery()` manually on the client and passes the hash without `preview_timestamp`, overwriting what the SDK had; (c) client-side internal navigation rewrites the iframe URL and drops the query params, so the next render has no timestamp (the double reload is Timeline re-injecting it); (d) a Timeline tracker is a different tracker type than a Visual Editor tracker, so a hash captured from one context does not work in the other.
+- **root_cause**: Timeline adds `preview_timestamp` to the iframe URL alongside the `live_preview` hash, and the site must forward **both** to the preview service. Common failures: (a) the app only forwards the hash; (b) the app calls `stack.livePreviewQuery()` manually on the client and passes the hash without `preview_timestamp`, overwriting what the SDK had; (c) client-side internal navigation rewrites the iframe URL and drops the query params, so the next render has no timestamp (the double reload is Timeline re-injecting it); (d) a `live_preview` hash is tied to the preview context that issued it, so a hash captured in Visual Editor does not work in Timeline and vice versa.
 - **fix**:
   1. On the server, read `preview_timestamp` from the request URL on every request and pass it with the hash: `stack.livePreviewQuery({ live_preview: hash, preview_timestamp: ts, content_type_uid, entry_uid })`.
   2. On the client, prefer letting the SDK read the params from `document.location` — do not call `livePreviewQuery()` yourself. If you must, always include `preview_timestamp` next to the hash.
   3. Preserve `live_preview` and `preview_timestamp` across client-side route changes, or force a full navigation inside preview. Use Timeline's URL navigation box rather than in-page link clicks when demoing.
-  4. Do not reuse a hash across contexts. A Timeline hash comes from the Timeline preview page's tracker call; a Visual Editor hash comes from Visual Editor.
+  4. Do not reuse a hash across contexts. For Timeline requests use the `live_preview` hash Timeline puts on the iframe URL; for Visual Editor requests use the one Visual Editor puts there.
   5. Append the params correctly when the base URL already carries a query string, rather than overwriting the existing one.
 - **verification**: Pick a future scheduled-publish marker; the request to the preview host should carry both headers and the response `_version` should match the version expected at that timestamp.
 
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md b/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
index 555a2e5..5ca0f83 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -66,8 +66,7 @@ Initialise once in `_app`, guarded to the client, since `init()` touches `window
 
 There is no page dedicated to the Pages Router in the Contentstack docs. Use the general pages for
 the mode in play — Set Up Live Preview with REST for SSR for `getServerSideProps`, and the SSG page
-for `getStaticProps` — and the same contracts hold. Contentstack's own Live Preview sanity fixture
-runs on the Pages Router.
+for `getStaticProps` — and the same contracts hold.
 
 ## React SPA with Vite
 
@@ -127,7 +126,7 @@ Gatsby uses its own path via `ContentstackGatsby`, which previews without a rebu
 
 Two cautions. The published Gatsby starter is pinned to a Live Preview Utils v1.x release that
 predates Visual Editor, so it is not a valid Visual Editor reference. And whether Visual Editor
-works on a Gatsby static architecture is an open question internally, not a settled yes. Scope
+works on a Gatsby static architecture is undocumented and unverified, not a settled yes. Scope
 Gatsby answers to Live Preview unless the user has verified Visual Editor themselves.
 
 Note that `getGatsbyDataFormat` still appears in the SDK's README and configuration docs but has no
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index 6eba71e..5585428 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -1,24 +1,24 @@
 # The Onboarding Check
 
 Every visual experience product ships a setup check that runs automatically when its panel opens.
-There are **three** of them, and they differ in both gates and shape: Live Preview shows one card
-with the first failing gate; Visual Editor shows a six-item list with a status per item; Timeline
-shows a small status card while it checks, then a full-pane "Set Up Timeline" overlay listing three
-items with a status each once one fails. Confirm which product the user is in before reading anything below. It is the highest-yield thing to ask
-about, because it has already run the diagnosis the user is asking you to do.
-
-**Always ask for a screenshot of this card before asking anything else.** The step name on it
+There are **three** of them, and they differ in both gates and shape. Live Preview shows one card
+carrying the first failing gate. Visual Editor shows all six of its items, each with its own status,
+but stops evaluating at the first one that fails. Timeline shows a small status card while it checks,
+then a full-pane "Set Up Timeline" overlay listing three items with a status each once one fails.
+Confirm which product the user is in before reading anything below. It is the highest-yield thing to
+ask about, because it has already run the diagnosis the user is asking you to do.
+
+**Always ask for a screenshot of the check before asking anything else.** The failing step name
 localises the problem to one gate, and because of how the check is structured, it also tells you
 everything that already passed.
 
-## The property that makes the Live Preview and Timeline checks powerful
+## The property that makes all three checks powerful
 
-For Live Preview the gates are evaluated as a single ordered chain that stops at the first failure,
-so only one step is ever shown. Timeline's three items are chained the same way, each evaluated only
-after the previous one passed, so on its overlay the first empty circle is the failure and the ones
-below it never ran. **Visual Editor is different**: every item is evaluated
-independently and shown with its own status, so read the whole list rather than one card. The
-inference below applies to the two chained checks, Live Preview and Timeline, not to Visual Editor.
+All three evaluate their gates as an ordered chain that stops at the first failure. They differ only
+in how much they show you. Live Preview renders just the failing step. Timeline and Visual Editor
+render their full item list with a status each, but the items below the first incomplete one were
+never evaluated, so they carry no information. **In every product, read the first failing item and
+ignore what is under it.**
 
 So a card reading "Preview Service Not Enabled" is not just one fact. It proves the website loaded
 in the frame, the SDK initialised, and the SDK version is supported. Three contracts are already
@@ -37,7 +37,7 @@ Five gates, in this order.
 | 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | The frame loaded but no init handshake arrived. `init()` is in server-only code, the enable flag did not parse as a boolean in the deployed build, the init module was tree-shaken out, or init runs after the check window. |
 | 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake arrived from a version below the supported minimum. Upgrade Live Preview Utils. |
 | 4 | Verifying Preview Service | **Preview Service Not Enabled** | The SDK is fine and the site is fine, but content is not coming from the Preview Service. This is the fetch layer never switching host and headers, which is the most common failure of all. |
-| 5 | — | **Default Environment Not Set** | Everything works. Setup is recorded as complete. The stack simply has no default preview environment, set in stack settings. |
+| 5 | — | **Default Environment Not Set** | Everything works. The stack simply has no default preview environment, set in stack settings. |
 | — | — | **Setup Complete** | All gates passed. |
 
 The exact body text is worth quoting back to users, because they often paraphrase it into
@@ -47,18 +47,18 @@ origins." Gate 4 reads "Please enable the Preview Service for a seamless live pr
 ## Visual Editor
 
 Visual Editor runs its own check, not Live Preview's. Six items, shown as a list with a status per
-item. Every item is evaluated independently (`steps.every(isComplete)`), so a partially green list is
-the normal way it looks while something is wrong, and the failing items are the ones to read. Card
-text as observed in the UI; the identifier is the implementation's step id.
+item. Unlike Live Preview it shows the whole list, but evaluation still stops at the first item that
+fails, so a partially green list is the normal way it looks while something is wrong and only the
+**first** incomplete item is diagnostic. Item text as observed in the UI.
 
-| # | Item (card text) | Step id | Passes when |
-|---|---|---|---|
-| 1 | Configure environment | `ENVIRONMENT` | both sub-steps below pass |
-| 1a | Default Environment | `LP_DEFAULT_ENV` | the environment in the preview URL's parameters exists on the stack |
-| 1b | Base URL | `BASE_URL` | that environment has a Base URL for the current locale, and its **origin matches the origin of the page being previewed**. A Base URL on a different host or scheme fails here even though the page loads |
-| 2 | Install SDK | `LP_SDK_VERSION` | Live Preview Utils major version is 3 or higher |
-| 3 | Verify Mode for Live Preview | `LP_SDK_INIT_MODE` | `init()` was called with `mode: "builder"`. **`mode: "preview"` fails this gate.** Edit tags alone do not get you a canvas |
-| 4 | Preview Token | `LP_SERVICE` | after the init handshake, the editor polls the Preview Service and it responds; the site is fetching through the Preview Service, not the delivery CDN |
+| # | Item (card text) | Passes when |
+|---|---|---|
+| 1 | Configure environment | both sub-steps below pass |
+| 1a | Default Environment | the environment in the preview URL's parameters exists on the stack |
+| 1b | Base URL | that environment has a Base URL for the current locale, and its **origin matches the origin of the page being previewed**. A Base URL on a different host or scheme fails here even though the page loads |
+| 2 | Install SDK | Live Preview Utils major version is 3 or higher |
+| 3 | Verify Mode for Live Preview | `init()` was called with `mode: "builder"`. **`mode: "preview"` fails this gate.** Edit tags alone do not get you a canvas |
+| 4 | Preview Token | the site's content requests for the previewed page reach the Preview Service (the REST or GraphQL preview host) instead of the delivery CDN. The check looks for that a handful of times across roughly the first 18 seconds after the SDK's `init()` handshake arrives and items 1-3 pass, so a site that fetches only from the delivery CDN, or fetches nothing in that window, fails here |
 
 Two consequences worth stating:
 
@@ -85,14 +85,14 @@ map any of them onto another table. It has two surfaces:
 |---|---|---|---|
 | 1 | Configure the environment | an environment resolves for the session: the `environment` on the Timeline URL, falling back to the stack's default preview environment (`live_preview.default-env`) | no environment on the URL and no default preview environment in stack settings |
 | 2 | Install the latest Live Preview SDK | item 1 passed and the SDK's `init()` handshake reached Timeline with a major version of 2 or higher | `init()` never ran inside the frame, or the SDK is 1.x |
-| 3 | Generate and use Preview Token | item 2 passed and, inside the polling window, the tracker for this session's hash reports a REST or GraphQL Preview Service version, meaning a content request hit the Preview Service | the site fetched from the delivery CDN, or fetched nothing in time |
+| 3 | Generate and use Preview Token | item 2 passed and, by the end of the check's short window, at least one of the site's content requests (REST or GraphQL) has been served by the Preview Service | the site fetched from the delivery CDN, or fetched nothing in time |
 
 The items are chained: 2 is only evaluated after 1 passes, 3 only after 2. Read the **first** empty
 circle. The ones below it never ran and tell you nothing.
 
 **Timing.** The overlay appears ten seconds after the last status change if anything is still
-unchecked, or after one second when no environment resolves at all. Item 3 polls the tracker up to
-five times, first after one second and then every two, roughly a nine-second window. A site whose
+unchecked, or after one second when no environment resolves at all. Item 3 waits roughly nine seconds for
+the site's first Preview Service request. A site whose
 first preview request lands later than that shows item 3 empty on a correct setup. Have the user
 reopen the panel on a warm cache before believing it.
 
@@ -139,7 +139,7 @@ what an unset value means:
 |---|---|---|
 | Timeline | `timeline.onboarding-setup-visible` | visible |
 | Live Preview | `live_preview.lp-onboarding-setup-visible` | hidden |
-| Visual Editor | `visual_builder.onboarding-setup-visible` | depends on whether the settings object exists |
+| Visual Editor | `visual_builder.onboarding-setup-visible` | visible |
 
 The Visual Experience settings screen renders every one of these as **on** when unset, so a stack
 that never explicitly saved the setting can show the toggle on while the card never appears.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
index 79e9f75..1021d83 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -7,9 +7,9 @@ meaningless.
 ## Before touching the application
 
 1. **Get the Onboarding Check to appear.** It walks the contracts in order and names the first one
-   that fails. Do not assume its default state: each product stores its own setting under
-   Settings → Visual Experience, and an unset value resolves differently per product, so the toggle
-   can read on while the card never appears. Save the setting explicitly for the product in use.
+   that fails. Do not assume its default state: each product has its own toggle under
+   Settings → Visual Experience, and one that has never been saved can read on while the card never
+   appears. Save the setting explicitly for the product in use.
 2. **Live Preview is enabled on the stack**, with a default preview environment set.
 3. **A Preview Token exists**, generated against the Delivery Token the application already uses.
    A management token is not a substitute and must never reach client-side configuration.
@@ -48,8 +48,9 @@ meaningless.
 
 ## Contract 1: init runs
 
-12. **A `POST /live-preview/tracker` returns 2xx** when the preview panel loads. If it never fires,
-    init did not run.
+12. **The Live Preview Onboarding Check gets past "Live Preview SDK Not Initialized"** when the
+    preview panel loads. That item clears only on the SDK's init message, so while it sticks either
+    `init()` never ran on the client or it ran with a falsy `enable` (item 14).
 13. **`init()` runs on the client**, not in server-only code.
 14. **The enable flag parses as a boolean in the deployed build.** A string `"false"` is truthy.
 15. **`ssr` is set explicitly.** The automatic default keys off `stackSdk` and gets it wrong in both
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 5da51f9..4048af7 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -49,6 +49,13 @@ request. Its onboarding overlay links to this page:
 
 - [Set Up Timeline](https://www.contentstack.com/docs/developers/set-up-timeline)
 
+### Preview Sharing
+
+Not an integration task. Once Visual Editor works, sharing a preview link is done from the editor by
+a content manager, and the link is valid for seven days. Nothing on the customer's site changes, so
+send them to the documentation rather than debugging their code:
+[Preview Sharing](https://www.contentstack.com/docs/content-managers/preview-sharing).
+
 ### Starters
 
 [Kickstart Next.js](https://www.contentstack.com/docs/developers/kickstarts/next) and its siblings
diff --git a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
index a4ca859..5edb18e 100644
--- a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
+++ b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
@@ -124,7 +124,7 @@ Onboarding Check, or a failure set.
 | **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
 | **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags **plus** `mode: "builder"` in `init()`. `mode: "preview"` fails its Verify Mode gate even with tags present. Not a separate integration. |
 | **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
-| **Preview Sharing** | Share a preview link externally | Plan-gated. |
+| **Preview Sharing** | Share a preview link externally | Plan-gated, and a content-manager feature rather than an integration. The skill carries no troubleshooting for it; point at [Preview Sharing](https://www.contentstack.com/docs/content-managers/preview-sharing). |
 
 If the user is on Visual Editor, confirm whether plain Live Preview works. If it does not, that is
 the problem, and the Visual Editor symptom is downstream noise.
@@ -171,9 +171,9 @@ so the step shown proves every earlier gate passed:
 | Default Environment Not Set | Setup is fine; no default preview environment on the stack |
 | Setup Complete | Reachability, handshake, version and Preview Service are all fine |
 
-**Visual Editor shows a six-item list, not a card.** Every item is evaluated on its own and carries
-its own status, so read the failing items rather than the first one. Configure environment (Default
-Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
+**Visual Editor shows a six-item list, not a card**, but it still stops evaluating at the first item
+that fails, so read the first incomplete item and ignore the ones under it. Configure environment
+(Default Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
 customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
 Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
 
@@ -185,10 +185,10 @@ is the failure and the ones below it never ran:
 |---|---|
 | Configure the environment | No environment on the Timeline URL and no default preview environment on the stack |
 | Install the latest Live Preview SDK | The `init()` handshake never reached Timeline, or the SDK major version is below 2 |
-| Generate and use Preview Token | No content request hit the Preview Service inside the polling window |
+| Generate and use Preview Token | No content request reached the Preview Service before the check stopped waiting |
 
-The overlay appears ten seconds after the last status change and item 3 polls for about nine, so a
-slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
+The overlay appears ten seconds after the last status change, and item 3 gives up waiting at about
+nine, so a slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
 before believing it.
 
 Two readings that decide the whole branch:
@@ -314,7 +314,7 @@ identically. Name which one is unmet, with the evidence, before proposing anythi
 
 | # | Contract | One-look check |
 |---|---|---|
-| 1 | `init()` runs, on the client, in the deployed build | `POST /live-preview/tracker` returns 2xx when the panel loads |
+| 1 | `init()` runs, on the client, in the deployed build | The Live Preview Onboarding Check moves past "Live Preview SDK Not Initialized" — that item clears only when the SDK's init message reaches the app, which happens only from `init()` |
 | 2 | Edit tags are generated and land on DOM elements | Some rendered element carries `data-cslp` |
 | 3 | The hash reaches the fetch, which switches host plus headers | Content requests hit a `*-preview.contentstack.com` host |
 | 4 | The preview target is reachable in an iframe | The pane renders at all |
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
index 2ec2afb..5283997 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -124,7 +124,7 @@ Onboarding Check, or a failure set.
 | **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
 | **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags **plus** `mode: "builder"` in `init()`. `mode: "preview"` fails its Verify Mode gate even with tags present. Not a separate integration. |
 | **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
-| **Preview Sharing** | Share a preview link externally | Plan-gated. |
+| **Preview Sharing** | Share a preview link externally | Plan-gated, and a content-manager feature rather than an integration. The skill carries no troubleshooting for it; point at [Preview Sharing](https://www.contentstack.com/docs/content-managers/preview-sharing). |
 
 If the user is on Visual Editor, confirm whether plain Live Preview works. If it does not, that is
 the problem, and the Visual Editor symptom is downstream noise.
@@ -171,9 +171,9 @@ so the step shown proves every earlier gate passed:
 | Default Environment Not Set | Setup is fine; no default preview environment on the stack |
 | Setup Complete | Reachability, handshake, version and Preview Service are all fine |
 
-**Visual Editor shows a six-item list, not a card.** Every item is evaluated on its own and carries
-its own status, so read the failing items rather than the first one. Configure environment (Default
-Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
+**Visual Editor shows a six-item list, not a card**, but it still stops evaluating at the first item
+that fails, so read the first incomplete item and ignore the ones under it. Configure environment
+(Default Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
 customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
 Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
 
@@ -185,10 +185,10 @@ is the failure and the ones below it never ran:
 |---|---|
 | Configure the environment | No environment on the Timeline URL and no default preview environment on the stack |
 | Install the latest Live Preview SDK | The `init()` handshake never reached Timeline, or the SDK major version is below 2 |
-| Generate and use Preview Token | No content request hit the Preview Service inside the polling window |
+| Generate and use Preview Token | No content request reached the Preview Service before the check stopped waiting |
 
-The overlay appears ten seconds after the last status change and item 3 polls for about nine, so a
-slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
+The overlay appears ten seconds after the last status change, and item 3 gives up waiting at about
+nine, so a slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
 before believing it.
 
 Two readings that decide the whole branch:
@@ -314,7 +314,7 @@ identically. Name which one is unmet, with the evidence, before proposing anythi
 
 | # | Contract | One-look check |
 |---|---|---|
-| 1 | `init()` runs, on the client, in the deployed build | `POST /live-preview/tracker` returns 2xx when the panel loads |
+| 1 | `init()` runs, on the client, in the deployed build | The Live Preview Onboarding Check moves past "Live Preview SDK Not Initialized" — that item clears only when the SDK's init message reaches the app, which happens only from `init()` |
 | 2 | Edit tags are generated and land on DOM elements | Some rendered element carries `data-cslp` |
 | 3 | The hash reaches the fetch, which switches host plus headers | Content requests hit a `*-preview.contentstack.com` host |
 | 4 | The preview target is reachable in an iframe | The pane renders at all |
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md b/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
index 482347e..2d609f0 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
@@ -19,7 +19,8 @@ Routine. It means a postMessage arrived with no registered listener, which happe
 load and teardown. Appears on working setups.
 
 Never conclude anything from it on its own. It does not affect SSR content, and it is not evidence
-that the handshake failed — check for the tracker POST instead.
+that the handshake failed — read the Live Preview Onboarding Check instead, which sticks on **Live
+Preview SDK Not Initialized** until the SDK's init message arrives.
 
 ### Third-party script errors from ad, consent, or personalisation tags
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md b/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
index f361144..db17626 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
@@ -52,7 +52,7 @@ assumption. Keep it to the fields; a Support or Product Engineer wants the facts
 | Started after | new setup (never worked) / release / dependency bump / settings change / role change / nothing known |
 | Failing request | `METHOD host/path → status` — URL redacted, no tokens |
 | Console or server log | one-line excerpt, redacted |
-| Ruled out | contracts verified and how, e.g. "tracker POST 200; `data-cslp` present; requests hit the preview host" |
+| Ruled out | contracts verified and how, e.g. "Onboarding Check past 'Live Preview SDK Not Initialized'; `data-cslp` present; requests hit the preview host" |
 | Suspected category | provisioning / plan gating / browser policy / other |
 | Workaround applied | what, or "none" |
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
index 3108fea..cf5377a 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -12,7 +12,7 @@ the fixes here will help.
 - **symptom**: Selecting a variant (or switching audience in Audience Preview) in Visual Experience keeps rendering the base entry. The side form shows the correct variant content, but the canvas does not. A manual browser refresh sometimes fixes it. Clicking into the element shows the correct variant value while the rendered page does not.
 - **frameworks**: Next.js, React, framework-agnostic
 - **rendering_modes**: CSR | SSR
-- **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-setup.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the parent Contentstack UI fetches the entry separately over the Management service. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
+- **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-setup.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the Contentstack UI loads the entry on its own, independently of your site's fetch. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
 - **fix**:
   1. First confirm the preview path works at all: change a plain text field and check the canvas updates. If it does not, fix that first — the variant symptom is downstream of it.
   2. Do **not** pass the variant yourself. The Preview Service resolves it from the UI selection; no `variant` query param, no `Entries.variants()`. Do pass `include_applied_variants=true` as a query parameter on the content request (`.addParams({ include_applied_variants: "true" })`), or the variant renders but Highlight Variant and audience mode have nothing to key on; see `highlight-variant-or-audience-mode-does-nothing` in `faq-visual-editor.md`.
@@ -27,7 +27,7 @@ the fixes here will help.
 
 ### cached-response-serves-stale-preview
 - **bucket**: preview-runtime
-- **symptom**: Preview works on localhost but not on a deployed environment with identical code and config — the setup status can even show "Setup Completed" and every edit return `{"notice":"Live Preview entry updated successfully."}` while the rendered page never changes. Or preview stops updating and only recovers in an incognito window or after a hard reload.
+- **symptom**: Preview works on localhost but not on a deployed environment with identical code and config — the setup status can even show "Setup Completed" and edits go through in the entry form while the rendered page never changes. Or preview stops updating and only recovers in an incognito window or after a hard reload.
 - **frameworks**: Next.js, framework-agnostic
 - **rendering_modes**: SSR | SSG/ISR | edge
 - **root_cause**: A cache sits between the browser and the preview service. Whether or not its key includes the `live_preview` hash, preview requests get a stored payload instead of a live one. Seen with a customer CDN in front of the deployed environment, with an app-level fetch cache, and (on the Contentstack side) with stale JS bundles cached in the browser or CDN after a release. The Contentstack SDKs' own cache policies (`IGNORE_CACHE`, `CACHE_THEN_NETWORK`, `CACHE_ELSE_NETWORK`, `NETWORK_ELSE_CACHE`) do **not** switch themselves off for Live Preview — they cache regardless of the preview config.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
index 600d30c..d08f67d 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
@@ -56,13 +56,13 @@ contract tells you which section to read; this file tells you what to do.
   (a sibling variant is `{"error_message":"Please provide live preview hash in request","error_code":382}`). Often appears the moment `mode: "builder"` is set, or when the site is opened directly rather than from inside the Contentstack preview pane. Sometimes reproduces for one developer and not another on "identical" setups.
 - **frameworks**: Next.js, React, framework-agnostic REST/GraphQL clients
 - **rendering_modes**: CSR, SSR
-- **root_cause**: The `live_preview` hash sent on the request has no matching tracker document. Contentstack creates that tracker with a `POST /live-preview/tracker` when the preview session starts inside the CMS. The error means either (a) the app sent a hardcoded, stale, or hand-invented hash, (b) the app sent `live_preview=true` or an empty value instead of the real hash, or (c) the request was made outside any preview session (the site opened directly, or a custom preview tool that has no way to obtain a hash).
+- **root_cause**: The `live_preview` hash on the request is not one Contentstack issued for a live preview session. Contentstack generates the hash when the entry is opened in the preview pane and hands it to the site: as `?live_preview=<hash>` on the URL for SSR (and when the preview is opened in a new tab), or to the SDK running in the pane for CSR, where it surfaces as `ContentstackLivePreview.hash`. A hash from anywhere else is rejected with this error. The error means either (a) the app sent a hardcoded, stale, or hand-invented hash, (b) the app sent `live_preview=true` or an empty value instead of the real hash, or (c) the request was made outside any preview session (the site opened directly, or a custom preview tool that has no way to obtain a hash).
 - **fix**:
   1. Never hardcode or invent a hash. Read it from `?live_preview=` on the request (SSR) or from `ContentstackLivePreview.hash` (CSR), and skip the preview host entirely when it is absent.
-  2. Confirm the tracker call fires: in DevTools → Network, look for `POST /live-preview/tracker` returning 2xx when the preview pane loads. If it never fires, the SDK did not initialize (check `enable`, the `.env` value actually parsing as `true`, and that `init()` runs on the client).
+  2. Confirm the SDK initialised: the Live Preview Onboarding Check must get past **Live Preview SDK Not Initialized**. That item clears only when the SDK's init message reaches the CMS, and the SDK sends it only when `init()` ran on the client with a truthy `enable`. If it sticks there, check `enable`, the `.env` value actually parsing as `true`, and that `init()` runs on the client.
   3. If the app proxies Contentstack through its own backend, forward the hash end to end. The front end must pass the hash it received to the backend, and the backend must put it in the `live_preview` header.
   4. Building a preview tool entirely outside Contentstack is not supported with a Preview Token alone; the hash originates in the CMS session. Use a dedicated publishing environment for an internal preview tool instead.
-- **verification**: With the entry open in Live Preview, the network log shows a successful tracker POST followed by preview reads returning 200 with the same hash value.
+- **verification**: With the entry open in Live Preview, the site's content requests go to the preview host and return 200, and the 382 error is gone.
 
 ---
 
@@ -93,7 +93,7 @@ contract tells you which section to read; this file tells you what to do.
 - **root_cause**: By default the preview URL is `environment Base URL` + the entry's `url` field. That only works when app routing maps 1:1 to the `url` field. Nested paths, custom route prefixes, several content types with different URL shapes, multiple sites served from one stack, or a URL stored in a custom text field instead of the built-in `url` field all break the concatenation.
 - **fix**:
   1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL). This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated. Follow the docs for the pattern syntax, placeholders, Base URL aliases and defaults: [Custom Preview URLs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls).
-  2. With Custom Preview URLs enabled, tell the editor which entry each page is by calling `setPageContext({ entryUid, contentTypeUid })` on every page (Live Preview Utils v4.4.4+). Fallbacks: the `window.__CS_PAGE_CONTEXT__` global, or `<meta name="contentstack:entry-uid">` and `<meta name="contentstack:content-type-uid">`. **This only has an effect when Custom Preview URLs is configured and enabled on the plan.** Without it the editor resolves by URL alone and the call is silently ignored — it does not error, so a missing feature flag looks like `setPageContext` not working.
+  2. With Custom Preview URLs enabled, tell the editor which entry each page is by calling `setPageContext({ entryUid, contentTypeUid })` on every page (Live Preview Utils v4.4.4+). Fallbacks: the `window.__CS_PAGE_CONTEXT__` global, or `<meta name="contentstack:entry-uid">` and `<meta name="contentstack:content-type-uid">`. **This only has an effect when the Custom Preview URLs setting exists for the stack and is configured.** Without it the editor resolves by URL alone and the call is silently ignored — it does not error, so a stack without the feature looks like `setPageContext` not working.
   3. Do not narrow the environment Base URL to one content type's prefix (for example `.../inspiration/articles/`) — that fixes one content type and breaks all others.
   4. Verify the entry's `url` field actually corresponds to a route the app serves, and that the route renders the content type you expect.
 - **verification**: Open entries from several content types (root page, nested page, no-URL page). Each should load its own page in the preview pane, and the URL bar in the pane should show the real route.
@@ -165,7 +165,7 @@ contract tells you which section to read; this file tells you what to do.
 - **symptom**: Two opposite failures from the same mistake. **(A) Hash never arrives:** `init()` succeeds and `ContentstackLivePreview.hash` is populated on the client, but server-rendered pages still return published content. Deterministic, and only the author notices. **(B) Preview state leaks out:** intermittent, user-dependent wrong content, and the **production** site failing with `The Live Preview tracker is invalid or no longer exists. Create a new tracker to continue.` (error_code 382) or `The requested tracker was created for the 'dev' branch. Access using the 'main' branch is not allowed.`; preview stalling after a while; `TypeError: Cannot read properties of undefined (reading 'uid')` after idle hours in production; two editors seeing each other's content; personalization on the public site stopping resolving per visitor because a cached preview render is being served instead. This one reaches real visitors.
 - **frameworks**: Next.js (App Router and Pages Router), Express/Node, Nuxt
 - **rendering_modes**: SSR | edge
-- **root_cause**: In SSR the SDK does not fetch content. It puts `?live_preview=<hash>&content_type_uid=...&entry_uid=...` on the URL and reloads, and preview state lives **on the Stack instance**. Failure (A) is having two instances: a long-lived "default" Stack for page queries plus a second Stack passed only to `init()`, so the hash never lands on the instance that queries. Failure (B) is having one module-level instance shared across requests: once any request puts it into preview mode, unrelated requests inherit it, and ordinary delivery traffic starts hitting the preview service with a hash that has expired (the tracker lasts about a day; the session hash rotates roughly every 30 minutes) or belongs to another branch. Under concurrency requests can also overwrite each other's config mid-flight.
+- **root_cause**: In SSR the SDK does not fetch content. It puts `?live_preview=<hash>&content_type_uid=...&entry_uid=...` on the URL and reloads, and preview state lives **on the Stack instance**. Failure (A) is having two instances: a long-lived "default" Stack for page queries plus a second Stack passed only to `init()`, so the hash never lands on the instance that queries. Failure (B) is having one module-level instance shared across requests: once any request puts it into preview mode, unrelated requests inherit it, and ordinary delivery traffic starts hitting the preview service with a hash that has expired (hashes are session-scoped and time-limited; the preview session issues a fresh one, so a stored or hardcoded hash eventually fails with the tracker-invalid text above) or belongs to another branch. Under concurrency requests can also overwrite each other's config mid-flight.
 - **fix**:
   1. Create a fresh Delivery SDK instance **per request**. Do not share a module-level Stack, and pass the instance down through request-scoped context rather than importing a singleton. This one change fixes both failures.
   2. Read the hash off the incoming request each time and apply it to that instance: `stack.livePreviewQuery({ live_preview: hash, contentTypeUid, entryUid })`.
@@ -183,7 +183,7 @@ contract tells you which section to read; this file tells you what to do.
 - **symptom**: In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit tags render but do nothing, or nothing at all happens when the entry is edited. The same code works in a Pages Router project.
 - **frameworks**: Next.js App Router
 - **rendering_modes**: SSR, CSR
-- **root_cause**: `ContentstackLivePreview.init()` has to run in the browser. In App Router, code placed in a server component or in the root layout module body never executes client-side, so the SDK never installs its postMessage listeners and never advertises SSR mode.
+- **root_cause**: `ContentstackLivePreview.init()` has to run in the browser. In App Router, code placed in a server component or in the root layout module body never executes client-side, so the SDK never installs its postMessage listeners and the Onboarding Check stays on **Live Preview SDK Not Initialized**.
 - **fix**:
   1. Create a dedicated client component and call `init()` from an effect:
      ```tsx
@@ -288,13 +288,13 @@ contract tells you which section to read; this file tells you what to do.
 - **symptom**: A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days later on its own. Conversely, other teams never see the status card at all when they want to diagnose a failing integration.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: any
-- **root_cause**: Each product keeps its own stack setting, and they do not agree on what "unset" means. Timeline treats an unset value as visible. Live Preview treats an unset value as hidden. Visual Editor depends on whether its settings object exists at all. Meanwhile the Visual Experience settings screen renders the toggle as on whenever the value is unset, so a stack that never explicitly saved the setting can show the toggle on while Live Preview behaves as though it is off. Separately, the checks run asynchronously with a timeout, so the card can appear briefly on a correctly configured site whose first preview fetch is slow, then clear itself once the request lands.
+- **root_cause**: Each product keeps its own stack setting, and they do not agree on what "unset" means. Timeline treats an unset value as visible. Live Preview treats an unset value as hidden. Visual Editor treats an unset value as visible, and also treats a stack with no `visual_builder` settings at all as visible. Meanwhile the Visual Experience settings screen renders the toggle as on whenever the value is unset, so a stack that never explicitly saved the setting can show the toggle on while Live Preview behaves as though it is off. Separately, the checks run asynchronously with a timeout, so the card can appear briefly on a correctly configured site whose first preview fetch is slow, then clear itself once the request lands.
 - **fix**:
-  1. Open Settings → Visual Experience and click Save without changing anything. The form always submits all three products' visibility keys, and an unset value arrives in the form as on, so a single save writes an explicit `true` for Live Preview, Visual Editor and Timeline at once. That removes the unset ambiguity and makes all three agree.
+  1. Open Settings → Visual Experience and click Save without changing anything. Saving once stores the state shown for Live Preview, Visual Editor and Timeline together, and a toggle that was never saved still shows as on, so one save records an explicit on for all three. That removes the unset ambiguity and makes all three agree.
   2. Check the setting for the product actually being used. Live Preview, Visual Editor and Timeline each have their own, under Settings → Visual Experience.
   3. Read the one step the card shows. The gates run as an ordered chain that stops at the first failure, so the card names a single gate — that is the configuration gap, and every gate before it has already passed.
   4. If it still does not appear for one user but does for others, that user dismissed it. The suppression is stored per stack in their browser, and no stack-level save clears it — they need to clear site data for the app origin, or use another browser profile.
-  5. If the card flashes then clears on a working site, no action is needed — the first preview request simply arrived after the check timeout.
+  5. If the card flashes then clears on a working site, no action is needed — the first preview request was simply slow to land.
 - **verification**: Open an entry in the product in question and confirm the status card appears. If it does not appear after saving the setting explicitly, it is being suppressed locally rather than by the stack setting.
 
 ---
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
index 53b4f72..b5b5a83 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
@@ -12,12 +12,12 @@ already good.
 - **symptom**: Timeline preview shows the wrong point in time — either the current version regardless of the date picked, or version 1 of the entry for every timestamp. Reference-field changes that render correctly on the live site, in Live Preview, and in Visual Editor do not show in Timeline. Clicking an internal link inside Timeline preview loses the timestamp and the page reloads twice.
 - **frameworks**: Next.js, React, framework-agnostic
 - **rendering_modes**: CSR | SSR
-- **root_cause**: Timeline adds `preview_timestamp` to the iframe URL alongside the `live_preview` hash, and the site must forward **both** to the preview service. Common failures: (a) the app only forwards the hash; (b) the app calls `stack.livePreviewQuery()` manually on the client and passes the hash without `preview_timestamp`, overwriting what the SDK had; (c) client-side internal navigation rewrites the iframe URL and drops the query params, so the next render has no timestamp (the double reload is Timeline re-injecting it); (d) a Timeline tracker is a different tracker type than a Visual Editor tracker, so a hash captured from one context does not work in the other.
+- **root_cause**: Timeline adds `preview_timestamp` to the iframe URL alongside the `live_preview` hash, and the site must forward **both** to the preview service. Common failures: (a) the app only forwards the hash; (b) the app calls `stack.livePreviewQuery()` manually on the client and passes the hash without `preview_timestamp`, overwriting what the SDK had; (c) client-side internal navigation rewrites the iframe URL and drops the query params, so the next render has no timestamp (the double reload is Timeline re-injecting it); (d) a `live_preview` hash is tied to the preview context that issued it, so a hash captured in Visual Editor does not work in Timeline and vice versa.
 - **fix**:
   1. On the server, read `preview_timestamp` from the request URL on every request and pass it with the hash: `stack.livePreviewQuery({ live_preview: hash, preview_timestamp: ts, content_type_uid, entry_uid })`.
   2. On the client, prefer letting the SDK read the params from `document.location` — do not call `livePreviewQuery()` yourself. If you must, always include `preview_timestamp` next to the hash.
   3. Preserve `live_preview` and `preview_timestamp` across client-side route changes, or force a full navigation inside preview. Use Timeline's URL navigation box rather than in-page link clicks when demoing.
-  4. Do not reuse a hash across contexts. A Timeline hash comes from the Timeline preview page's tracker call; a Visual Editor hash comes from Visual Editor.
+  4. Do not reuse a hash across contexts. For Timeline requests use the `live_preview` hash Timeline puts on the iframe URL; for Visual Editor requests use the one Visual Editor puts there.
   5. Append the params correctly when the base URL already carries a query string, rather than overwriting the existing one.
 - **verification**: Pick a future scheduled-publish marker; the request to the preview host should carry both headers and the response `_version` should match the version expected at that timestamp.
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md b/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
index 555a2e5..5ca0f83 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -66,8 +66,7 @@ Initialise once in `_app`, guarded to the client, since `init()` touches `window
 
 There is no page dedicated to the Pages Router in the Contentstack docs. Use the general pages for
 the mode in play — Set Up Live Preview with REST for SSR for `getServerSideProps`, and the SSG page
-for `getStaticProps` — and the same contracts hold. Contentstack's own Live Preview sanity fixture
-runs on the Pages Router.
+for `getStaticProps` — and the same contracts hold.
 
 ## React SPA with Vite
 
@@ -127,7 +126,7 @@ Gatsby uses its own path via `ContentstackGatsby`, which previews without a rebu
 
 Two cautions. The published Gatsby starter is pinned to a Live Preview Utils v1.x release that
 predates Visual Editor, so it is not a valid Visual Editor reference. And whether Visual Editor
-works on a Gatsby static architecture is an open question internally, not a settled yes. Scope
+works on a Gatsby static architecture is undocumented and unverified, not a settled yes. Scope
 Gatsby answers to Live Preview unless the user has verified Visual Editor themselves.
 
 Note that `getGatsbyDataFormat` still appears in the SDK's README and configuration docs but has no
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index 6eba71e..5585428 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -1,24 +1,24 @@
 # The Onboarding Check
 
 Every visual experience product ships a setup check that runs automatically when its panel opens.
-There are **three** of them, and they differ in both gates and shape: Live Preview shows one card
-with the first failing gate; Visual Editor shows a six-item list with a status per item; Timeline
-shows a small status card while it checks, then a full-pane "Set Up Timeline" overlay listing three
-items with a status each once one fails. Confirm which product the user is in before reading anything below. It is the highest-yield thing to ask
-about, because it has already run the diagnosis the user is asking you to do.
-
-**Always ask for a screenshot of this card before asking anything else.** The step name on it
+There are **three** of them, and they differ in both gates and shape. Live Preview shows one card
+carrying the first failing gate. Visual Editor shows all six of its items, each with its own status,
+but stops evaluating at the first one that fails. Timeline shows a small status card while it checks,
+then a full-pane "Set Up Timeline" overlay listing three items with a status each once one fails.
+Confirm which product the user is in before reading anything below. It is the highest-yield thing to
+ask about, because it has already run the diagnosis the user is asking you to do.
+
+**Always ask for a screenshot of the check before asking anything else.** The failing step name
 localises the problem to one gate, and because of how the check is structured, it also tells you
 everything that already passed.
 
-## The property that makes the Live Preview and Timeline checks powerful
+## The property that makes all three checks powerful
 
-For Live Preview the gates are evaluated as a single ordered chain that stops at the first failure,
-so only one step is ever shown. Timeline's three items are chained the same way, each evaluated only
-after the previous one passed, so on its overlay the first empty circle is the failure and the ones
-below it never ran. **Visual Editor is different**: every item is evaluated
-independently and shown with its own status, so read the whole list rather than one card. The
-inference below applies to the two chained checks, Live Preview and Timeline, not to Visual Editor.
+All three evaluate their gates as an ordered chain that stops at the first failure. They differ only
+in how much they show you. Live Preview renders just the failing step. Timeline and Visual Editor
+render their full item list with a status each, but the items below the first incomplete one were
+never evaluated, so they carry no information. **In every product, read the first failing item and
+ignore what is under it.**
 
 So a card reading "Preview Service Not Enabled" is not just one fact. It proves the website loaded
 in the frame, the SDK initialised, and the SDK version is supported. Three contracts are already
@@ -37,7 +37,7 @@ Five gates, in this order.
 | 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | The frame loaded but no init handshake arrived. `init()` is in server-only code, the enable flag did not parse as a boolean in the deployed build, the init module was tree-shaken out, or init runs after the check window. |
 | 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake arrived from a version below the supported minimum. Upgrade Live Preview Utils. |
 | 4 | Verifying Preview Service | **Preview Service Not Enabled** | The SDK is fine and the site is fine, but content is not coming from the Preview Service. This is the fetch layer never switching host and headers, which is the most common failure of all. |
-| 5 | — | **Default Environment Not Set** | Everything works. Setup is recorded as complete. The stack simply has no default preview environment, set in stack settings. |
+| 5 | — | **Default Environment Not Set** | Everything works. The stack simply has no default preview environment, set in stack settings. |
 | — | — | **Setup Complete** | All gates passed. |
 
 The exact body text is worth quoting back to users, because they often paraphrase it into
@@ -47,18 +47,18 @@ origins." Gate 4 reads "Please enable the Preview Service for a seamless live pr
 ## Visual Editor
 
 Visual Editor runs its own check, not Live Preview's. Six items, shown as a list with a status per
-item. Every item is evaluated independently (`steps.every(isComplete)`), so a partially green list is
-the normal way it looks while something is wrong, and the failing items are the ones to read. Card
-text as observed in the UI; the identifier is the implementation's step id.
+item. Unlike Live Preview it shows the whole list, but evaluation still stops at the first item that
+fails, so a partially green list is the normal way it looks while something is wrong and only the
+**first** incomplete item is diagnostic. Item text as observed in the UI.
 
-| # | Item (card text) | Step id | Passes when |
-|---|---|---|---|
-| 1 | Configure environment | `ENVIRONMENT` | both sub-steps below pass |
-| 1a | Default Environment | `LP_DEFAULT_ENV` | the environment in the preview URL's parameters exists on the stack |
-| 1b | Base URL | `BASE_URL` | that environment has a Base URL for the current locale, and its **origin matches the origin of the page being previewed**. A Base URL on a different host or scheme fails here even though the page loads |
-| 2 | Install SDK | `LP_SDK_VERSION` | Live Preview Utils major version is 3 or higher |
-| 3 | Verify Mode for Live Preview | `LP_SDK_INIT_MODE` | `init()` was called with `mode: "builder"`. **`mode: "preview"` fails this gate.** Edit tags alone do not get you a canvas |
-| 4 | Preview Token | `LP_SERVICE` | after the init handshake, the editor polls the Preview Service and it responds; the site is fetching through the Preview Service, not the delivery CDN |
+| # | Item (card text) | Passes when |
+|---|---|---|
+| 1 | Configure environment | both sub-steps below pass |
+| 1a | Default Environment | the environment in the preview URL's parameters exists on the stack |
+| 1b | Base URL | that environment has a Base URL for the current locale, and its **origin matches the origin of the page being previewed**. A Base URL on a different host or scheme fails here even though the page loads |
+| 2 | Install SDK | Live Preview Utils major version is 3 or higher |
+| 3 | Verify Mode for Live Preview | `init()` was called with `mode: "builder"`. **`mode: "preview"` fails this gate.** Edit tags alone do not get you a canvas |
+| 4 | Preview Token | the site's content requests for the previewed page reach the Preview Service (the REST or GraphQL preview host) instead of the delivery CDN. The check looks for that a handful of times across roughly the first 18 seconds after the SDK's `init()` handshake arrives and items 1-3 pass, so a site that fetches only from the delivery CDN, or fetches nothing in that window, fails here |
 
 Two consequences worth stating:
 
@@ -85,14 +85,14 @@ map any of them onto another table. It has two surfaces:
 |---|---|---|---|
 | 1 | Configure the environment | an environment resolves for the session: the `environment` on the Timeline URL, falling back to the stack's default preview environment (`live_preview.default-env`) | no environment on the URL and no default preview environment in stack settings |
 | 2 | Install the latest Live Preview SDK | item 1 passed and the SDK's `init()` handshake reached Timeline with a major version of 2 or higher | `init()` never ran inside the frame, or the SDK is 1.x |
-| 3 | Generate and use Preview Token | item 2 passed and, inside the polling window, the tracker for this session's hash reports a REST or GraphQL Preview Service version, meaning a content request hit the Preview Service | the site fetched from the delivery CDN, or fetched nothing in time |
+| 3 | Generate and use Preview Token | item 2 passed and, by the end of the check's short window, at least one of the site's content requests (REST or GraphQL) has been served by the Preview Service | the site fetched from the delivery CDN, or fetched nothing in time |
 
 The items are chained: 2 is only evaluated after 1 passes, 3 only after 2. Read the **first** empty
 circle. The ones below it never ran and tell you nothing.
 
 **Timing.** The overlay appears ten seconds after the last status change if anything is still
-unchecked, or after one second when no environment resolves at all. Item 3 polls the tracker up to
-five times, first after one second and then every two, roughly a nine-second window. A site whose
+unchecked, or after one second when no environment resolves at all. Item 3 waits roughly nine seconds for
+the site's first Preview Service request. A site whose
 first preview request lands later than that shows item 3 empty on a correct setup. Have the user
 reopen the panel on a warm cache before believing it.
 
@@ -139,7 +139,7 @@ what an unset value means:
 |---|---|---|
 | Timeline | `timeline.onboarding-setup-visible` | visible |
 | Live Preview | `live_preview.lp-onboarding-setup-visible` | hidden |
-| Visual Editor | `visual_builder.onboarding-setup-visible` | depends on whether the settings object exists |
+| Visual Editor | `visual_builder.onboarding-setup-visible` | visible |
 
 The Visual Experience settings screen renders every one of these as **on** when unset, so a stack
 that never explicitly saved the setting can show the toggle on while the card never appears.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
index 79e9f75..1021d83 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
@@ -7,9 +7,9 @@ meaningless.
 ## Before touching the application
 
 1. **Get the Onboarding Check to appear.** It walks the contracts in order and names the first one
-   that fails. Do not assume its default state: each product stores its own setting under
-   Settings → Visual Experience, and an unset value resolves differently per product, so the toggle
-   can read on while the card never appears. Save the setting explicitly for the product in use.
+   that fails. Do not assume its default state: each product has its own toggle under
+   Settings → Visual Experience, and one that has never been saved can read on while the card never
+   appears. Save the setting explicitly for the product in use.
 2. **Live Preview is enabled on the stack**, with a default preview environment set.
 3. **A Preview Token exists**, generated against the Delivery Token the application already uses.
    A management token is not a substitute and must never reach client-side configuration.
@@ -48,8 +48,9 @@ meaningless.
 
 ## Contract 1: init runs
 
-12. **A `POST /live-preview/tracker` returns 2xx** when the preview panel loads. If it never fires,
-    init did not run.
+12. **The Live Preview Onboarding Check gets past "Live Preview SDK Not Initialized"** when the
+    preview panel loads. That item clears only on the SDK's init message, so while it sticks either
+    `init()` never ran on the client or it ran with a falsy `enable` (item 14).
 13. **`init()` runs on the client**, not in server-only code.
 14. **The enable flag parses as a boolean in the deployed build.** A string `"false"` is truthy.
 15. **`ssr` is set explicitly.** The automatic default keys off `stackSdk` and gets it wrong in both
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 5da51f9..4048af7 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -49,6 +49,13 @@ request. Its onboarding overlay links to this page:
 
 - [Set Up Timeline](https://www.contentstack.com/docs/developers/set-up-timeline)
 
+### Preview Sharing
+
+Not an integration task. Once Visual Editor works, sharing a preview link is done from the editor by
+a content manager, and the link is valid for seven days. Nothing on the customer's site changes, so
+send them to the documentation rather than debugging their code:
+[Preview Sharing](https://www.contentstack.com/docs/content-managers/preview-sharing).
+
 ### Starters
 
 [Kickstart Next.js](https://www.contentstack.com/docs/developers/kickstarts/next) and its siblings

From a7fef8af19c53bd1c4cae99df6309e0405fe0474 Mon Sep 17 00:00:00 2001
From: Hitesh Shetty <hitesh.shetty@contentstack.com>
Date: Fri, 11 Sep 2026 16:34:40 +0530
Subject: [PATCH 17/21] fix(skills): update skill inventory for the
 visual-editor rename

manifest.json and README.md still listed the old
cms-live-preview-visual-builder-support-assistant slug after the
directory and router row moved to the visual-editor name, so tooling
that reads the inventory advertised a skill that no longer exists.

Also normalise one "Setup Completed" quote to "Setup Complete" to match
the card text everywhere else, and drop a duplicate horizontal rule in
faq-visual-editor.md. codex/ regenerated from skills/.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                                                     | 2 +-
 .../references/faq-preview-runtime.md                         | 2 +-
 .../references/faq-visual-editor.md                           | 2 --
 manifest.json                                                 | 4 ++--
 .../references/faq-preview-runtime.md                         | 2 +-
 .../references/faq-visual-editor.md                           | 2 --
 6 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index a6cbbbd..c997ae0 100644
--- a/README.md
+++ b/README.md
@@ -57,7 +57,7 @@ npx skills add <this-repo>@<skill-slug>
 | `cms-data-modeling-best-practices` | Contentstack Data Modeling Best Practices | CMS | Content type design, references, global fields, groups, modular blocks, JSON RTE, taxonomy, tags, and model simplification. |
 | `cms-entries` | Entries | CMS | Entry querying, localization, versioning, publishing, CDA usage, reference expansion, pagination, bulk operations, and Sync API patterns. |
 | `cms-environments-publishing` | Contentstack Environments & Publishing | CMS | Environment setup, publishing behavior, delivery and preview tokens, Sync API usage, CDN behavior, and publish queues. |
-| `cms-live-preview-visual-builder-support-assistant` | Live Preview and Visual Builder Support Assistant | Developer Experience | Live Preview and Visual Builder setup or debugging across CSR, SSR, SSG, middleware/BFF, and edit-tag flows. |
+| `cms-live-preview-visual-editor-support-assistant` | Live Preview and Visual Editor Support Assistant | Developer Experience | Live Preview, Visual Editor (also called Visual Builder) and Timeline setup or debugging across CSR, SSR, SSG and GraphQL. |
 | `cms-localization` | Contentstack Localization | CMS | Language setup, fallback chains, localized and unlocalized entries, non-localizable fields, and multi-locale publishing. |
 | `cms-releases` | Releases | CMS | Coordinated content deployment, release scheduling, staged deployment, webhook storm prevention, and CI/CD integration. |
 | `cms-roles-permissions` | Roles & Permissions | CMS | Built-in roles, custom roles, teams, permission merging, token capabilities, and least-privilege access design. |
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
index cf5377a..7262d4c 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -27,7 +27,7 @@ the fixes here will help.
 
 ### cached-response-serves-stale-preview
 - **bucket**: preview-runtime
-- **symptom**: Preview works on localhost but not on a deployed environment with identical code and config — the setup status can even show "Setup Completed" and edits go through in the entry form while the rendered page never changes. Or preview stops updating and only recovers in an incognito window or after a hard reload.
+- **symptom**: Preview works on localhost but not on a deployed environment with identical code and config — the setup status can even show "Setup Complete" and edits go through in the entry form while the rendered page never changes. Or preview stops updating and only recovers in an incognito window or after a hard reload.
 - **frameworks**: Next.js, framework-agnostic
 - **rendering_modes**: SSR | SSG/ISR | edge
 - **root_cause**: A cache sits between the browser and the preview service. Whether or not its key includes the `live_preview` hash, preview requests get a stored payload instead of a live one. Seen with a customer CDN in front of the deployed environment, with an app-level fetch cache, and (on the Contentstack side) with stale JS bundles cached in the browser or CDN after a release. The Contentstack SDKs' own cache policies (`IGNORE_CACHE`, `CACHE_THEN_NETWORK`, `CACHE_ELSE_NETWORK`, `NETWORK_ELSE_CACHE`) do **not** switch themselves off for Live Preview — they cache regardless of the preview config.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
index 7296df6..19212bc 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -54,8 +54,6 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 
 ---
 
----
-
 ### empty-block-add-button-not-appearing-or-failing
 - **bucket**: visual-editor
 - **symptom**: A page or component with an empty modular-block / multiple field shows no "+ Add Component" affordance, so authors have to go to the form panel to add the first block.
diff --git a/manifest.json b/manifest.json
index 564e68e..eb51d70 100644
--- a/manifest.json
+++ b/manifest.json
@@ -33,8 +33,8 @@
       "product": "CMS"
     },
     {
-      "slug": "cms-live-preview-visual-builder-support-assistant",
-      "title": "Live Preview and Visual Builder Support Assistant",
+      "slug": "cms-live-preview-visual-editor-support-assistant",
+      "title": "Live Preview and Visual Editor Support Assistant",
       "product": "Developer Experience"
     },
     {
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
index cf5377a..7262d4c 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -27,7 +27,7 @@ the fixes here will help.
 
 ### cached-response-serves-stale-preview
 - **bucket**: preview-runtime
-- **symptom**: Preview works on localhost but not on a deployed environment with identical code and config — the setup status can even show "Setup Completed" and edits go through in the entry form while the rendered page never changes. Or preview stops updating and only recovers in an incognito window or after a hard reload.
+- **symptom**: Preview works on localhost but not on a deployed environment with identical code and config — the setup status can even show "Setup Complete" and edits go through in the entry form while the rendered page never changes. Or preview stops updating and only recovers in an incognito window or after a hard reload.
 - **frameworks**: Next.js, framework-agnostic
 - **rendering_modes**: SSR | SSG/ISR | edge
 - **root_cause**: A cache sits between the browser and the preview service. Whether or not its key includes the `live_preview` hash, preview requests get a stored payload instead of a live one. Seen with a customer CDN in front of the deployed environment, with an app-level fetch cache, and (on the Contentstack side) with stale JS bundles cached in the browser or CDN after a release. The Contentstack SDKs' own cache policies (`IGNORE_CACHE`, `CACHE_THEN_NETWORK`, `CACHE_ELSE_NETWORK`, `NETWORK_ELSE_CACHE`) do **not** switch themselves off for Live Preview — they cache regardless of the preview config.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
index 7296df6..19212bc 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -54,8 +54,6 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 
 ---
 
----
-
 ### empty-block-add-button-not-appearing-or-failing
 - **bucket**: visual-editor
 - **symptom**: A page or component with an empty modular-block / multiple field shows no "+ Add Component" affordance, so authors have to go to the form panel to add the first block.

From ae24426480a0c72b41c4ed80e6f5be326ef49141 Mon Sep 17 00:00:00 2001
From: Hitesh Shetty <hitesh.shetty@contentstack.com>
Date: Wed, 7 Oct 2026 17:27:19 +0530
Subject: [PATCH 18/21] fix(skills): correct SDK and onboarding claims, slim
 the live-preview skill

Checked every SDK and Onboarding Check claim against the Live Preview SDK,
@contentstack/utils, @contentstack/delivery-sdk and the editor source, and
fixed the ones that were wrong:

- Could Not Connect is a no-cors HEAD, so it fails only on network errors.
  Frame headers and auth screens show as SDK Not Initialized.
- Visual Editor shows a status card, then a "Set Up Visual Editor" overlay;
  item text is now verbatim. Minimum SDK per check: 1.4.0, major 2, major 3.
- GraphQL references are never rebased automatically; system keys must be
  lifted to top-level uid and _content_type_uid.
- onEntryChange never fires on edits under ssr: true (it still runs at load).
- Stack live_preview.ssr overrides init({ ssr }).
- cleanCslpOnProduction only strips tags when enable is false.
- The Edit button renders on any page by default; add
  includeByQueryParameter: false.
- Locale precedence, Edit button vs edit tags, Visual Editor unset setting,
  dismissal persistence, region hosts, version wording, console messages.

Restructure:

- The skill now routes any Visual Experience question: how features work,
  setup, configuration and debugging. Step 2 answers plain questions from
  the references without a diagnostic intake.
- SKILL.md is roughly half the size. One seven-step flow; a new integration
  is a branch of step 2 that links the docs and the requirements that apply,
  then verifies at step 3.
- setup-docs.md covers new integrations: docs per framework and mode, the
  requirements the docs make easy to miss, and verification.
- faq-setup.md renamed to faq-integration.md. preflight-checklist.md removed;
  it repeated the four contracts.
- Dropped the FAQ entry that asserted a fixed service-side bug.
- Doc links moved to their canonical /docs/headless-cms/ paths.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                                     |   2 +-
 codex/AGENTS.md                               |   2 +-
 .../SKILL.md                                  | 552 +++++++----------
 .../references/console-noise.md               |  12 +-
 .../references/contact-support.md             |   2 +-
 .../references/edit-tags.md                   |  19 +-
 .../{faq-setup.md => faq-integration.md}      | 101 ++--
 .../references/faq-preview-runtime.md         |  35 +-
 .../references/faq-timeline.md                |   2 +-
 .../references/faq-visual-editor.md           |  13 +-
 .../references/frameworks.md                  |  47 +-
 .../references/onboarding-check.md            | 208 +++----
 .../references/preflight-checklist.md         | 105 ----
 .../references/rendering-modes.md             |  34 +-
 .../references/setup-docs.md                  | 203 +++++--
 .../references/symptom-index.md               |  50 +-
 cursor/rules/00-router.mdc                    |   2 +-
 ...review-visual-editor-support-assistant.mdc | 554 +++++++-----------
 skills/CLAUDE.md                              |   2 +-
 .../SKILL.md                                  | 554 +++++++-----------
 .../references/console-noise.md               |  12 +-
 .../references/contact-support.md             |   2 +-
 .../references/edit-tags.md                   |  19 +-
 .../{faq-setup.md => faq-integration.md}      | 101 ++--
 .../references/faq-preview-runtime.md         |  35 +-
 .../references/faq-timeline.md                |   2 +-
 .../references/faq-visual-editor.md           |  13 +-
 .../references/frameworks.md                  |  47 +-
 .../references/onboarding-check.md            | 208 +++----
 .../references/preflight-checklist.md         | 105 ----
 .../references/rendering-modes.md             |  34 +-
 .../references/setup-docs.md                  | 203 +++++--
 .../references/symptom-index.md               |  50 +-
 33 files changed, 1406 insertions(+), 1924 deletions(-)
 rename codex/cms-live-preview-visual-editor-support-assistant/references/{faq-setup.md => faq-integration.md} (84%)
 delete mode 100644 codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
 rename skills/cms-live-preview-visual-editor-support-assistant/references/{faq-setup.md => faq-integration.md} (84%)
 delete mode 100644 skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md

diff --git a/README.md b/README.md
index c997ae0..bf8abc1 100644
--- a/README.md
+++ b/README.md
@@ -57,7 +57,7 @@ npx skills add <this-repo>@<skill-slug>
 | `cms-data-modeling-best-practices` | Contentstack Data Modeling Best Practices | CMS | Content type design, references, global fields, groups, modular blocks, JSON RTE, taxonomy, tags, and model simplification. |
 | `cms-entries` | Entries | CMS | Entry querying, localization, versioning, publishing, CDA usage, reference expansion, pagination, bulk operations, and Sync API patterns. |
 | `cms-environments-publishing` | Contentstack Environments & Publishing | CMS | Environment setup, publishing behavior, delivery and preview tokens, Sync API usage, CDN behavior, and publish queues. |
-| `cms-live-preview-visual-editor-support-assistant` | Live Preview and Visual Editor Support Assistant | Developer Experience | Live Preview, Visual Editor (also called Visual Builder) and Timeline setup or debugging across CSR, SSR, SSG and GraphQL. |
+| `cms-live-preview-visual-editor-support-assistant` | Live Preview and Visual Editor Support Assistant | Developer Experience | Any Visual Experience question: how Live Preview, Visual Editor (also called Visual Builder) and Timeline work, setting them up, and debugging them across CSR, SSR, SSG and GraphQL. |
 | `cms-localization` | Contentstack Localization | CMS | Language setup, fallback chains, localized and unlocalized entries, non-localizable fields, and multi-locale publishing. |
 | `cms-releases` | Releases | CMS | Coordinated content deployment, release scheduling, staged deployment, webhook storm prevention, and CI/CD integration. |
 | `cms-roles-permissions` | Roles & Permissions | CMS | Built-in roles, custom roles, teams, permission merging, token capabilities, and least-privilege access design. |
diff --git a/codex/AGENTS.md b/codex/AGENTS.md
index 69f4fef..9996622 100644
--- a/codex/AGENTS.md
+++ b/codex/AGENTS.md
@@ -8,7 +8,7 @@ Use the table below to route a user request to the right skill. Each row maps a
 | Use when users want to migrate, move, switch, port, or re-platform from Contentful to Contentstack, including content models, content, assets, locales, application integrations, website code, migration prerequisites, migration progress checks, or post-migration validation. | [contentstack-migration-companion](./migration-companion/SKILL.md) |
 | Use when a user wants to migrate Contentstack Delivery SDK code from JavaScript to TypeScript. | [dx-migrate-js-to-ts-sdk](./dx-migrate-js-to-ts-sdk/SKILL.md) |
 | Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, Live Preview setup, Visual Builder support, SSR preview handling, or debugging SDK query chains. | [dx-delivery-sdk](./dx-delivery-sdk/SKILL.md) |
-| Use for any Contentstack Live Preview, Visual Editor or Visual Builder question (Visual Editor and Visual Builder are the same product), whether setting it up or debugging it: first-time integration in any framework, SDK upgrades, the SDK installed but nothing happening, a blank preview pane, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, canvas or edit-tag resolution failures, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](./cms-live-preview-visual-editor-support-assistant/SKILL.md) |
+| Use for any Contentstack Visual Experience question: Live Preview, Visual Editor or Visual Builder (the same product), Timeline, the Onboarding Check, edit tags, preview tokens and hosts, and Visual Experience settings. Covers how they work, setting them up in any framework, configuration, and debugging: the SDK installed but nothing happening, a blank or unreachable preview pane, a stuck Onboarding Check, edits that never appear, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, nothing editable on the canvas, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](./cms-live-preview-visual-editor-support-assistant/SKILL.md) |
 | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](./cms-data-modeling-best-practices/SKILL.md) |
 | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](./cms-entries/SKILL.md) |
 | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](./cms-assets/SKILL.md) |
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
index a5c846b..b5cf392 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -5,431 +5,279 @@
 
 ## Description
 
-Systematically set up and debug Contentstack Live Preview, Visual Editor (also called Visual Builder), and Timeline. Setup follows the official documentation. Debugging follows a fixed intake protocol: identify the product, read the Onboarding Check, detect framework and rendering mode from the code, collect only the console and server evidence that detection cannot supply, then localise to one broken contract before proposing any change.
+Answer any question about Contentstack Visual Experience: Live Preview, Visual Editor (also called
+Visual Builder) and Timeline. One flow covers all of it. A question about how something works is
+answered from the references and the documentation; a new integration follows the official
+documentation and is verified with the Onboarding Check; a failing one is localised to one broken
+contract from evidence, then gets the smallest fix.
 
 ## When to Use
 
-Use for any Contentstack Live Preview, Visual Editor, or Timeline question, whether the integration has never worked or works and misbehaves.
+Use for any Visual Experience question: how a feature works or behaves, what a setting or check
+means, setting up an integration, or an integration that misbehaves.
 
-`dx-delivery-sdk` is the neighbouring skill. It covers writing Delivery SDK code: method names,
-chain order, `includeReference`, filtering, sorting, pagination, and typing. Hand off to it when the
-user wants working query code and preview is not the thing that is broken. Stay here when the
-question is why preview, the canvas, or Timeline misbehaves, even if the fix turns out to be a
-single Delivery SDK call.
-
-Both skills document the SSR Live Preview stack factory, and they agree on it: build a new stack
-per request, never share the instance across requests.
+Hand off to `dx-delivery-sdk` when the user wants Delivery SDK query code and preview is not involved.
+Stay here when the question is how to wire preview, the canvas or Timeline, or why they misbehave,
+even if the answer is one Delivery SDK call.
 
 ## Terminology
 
-**Visual Builder and Visual Editor are the same product.** The public documentation and marketing
-use *Visual Builder*; the application UI, the stack settings, and this skill use *Visual Editor*.
-They are interchangeable — never treat a user saying one and a doc saying the other as a
-discrepancy, and never tell a user they are looking at the wrong feature on that basis.
-
-Mirror whichever term the user used. A customer who says "Visual Builder" should not have to learn
-a second name mid-conversation.
-
-Two related names worth keeping straight:
+**Visual Builder and Visual Editor are the same product.** Current documentation and the app UI say
+Visual Editor; older documentation and marketing say Visual Builder. Never treat the two names as a
+discrepancy. Mirror the term the user used.
 
-- **Visual Experience** is the umbrella covering Live Preview, Visual Editor and Timeline. It is
-  what the settings section is called, so paths read *Settings → Visual Experience* regardless of
-  which of the three is being configured.
-- **`mode: "builder"`** is an SDK option and keeps its name. So does the
-  `visual_builder.onboarding-setup-visible` stack setting. Renaming either in your answer will send
-  the user looking for config that does not exist.
+- **Visual Experience** is the umbrella for Live Preview, Visual Editor and Timeline, and the name of
+  the settings section: *Settings → Visual Experience*.
+- **`mode: "builder"`** (SDK option) and **`visual_builder.onboarding-setup-visible`** (stack
+  setting) keep their names. Do not rename them in an answer.
 
 ## User Problem
 
-The same complaint has many unrelated causes. "Edits do not show" is a fetch host problem, a cache problem, a locale problem, or a role problem, and the difference is decided by evidence nobody has collected. Guessing produces a long thread of speculative fixes.
-
-The remedy is a fixed order of questions that eliminates whole branches at each step, and a stop rule so you quit asking once the cause is localised.
+Setup instructions reconstructed from memory drift from the documentation and miss the requirements
+that differ per rendering mode. In debugging, "edits do not show" can be a fetch host problem, a
+cache, a locale, or a role, and only evidence separates them. Guessing produces a long thread of
+speculative fixes.
 
 ## Success Criteria
 
-- Works the intake protocol in order rather than jumping to a plausible cause
-- Establishes the product first, because the three do not share a setup or a check
-- Asks for the Onboarding Check before anything else, and uses what its result already proves
-- Never asks a question the evidence has already answered
-- Stops collecting once one contract is localised
-- Uses the documentation for setup and the failure catalogue for debugging
-- Recognises causes outside the user's application and points the user to Contentstack Support instead of debugging
+- Works the steps in order and reports the checklist back ticked
+- For a new integration, links the documentation page for the framework and mode instead of
+  inventing steps, and does not ask diagnostic questions about code that does not exist yet
+- Reads the Onboarding Check before any other diagnostic question
+- Never asks for what the code or earlier evidence already answers
+- Names one broken contract, with evidence, before proposing a change
+- Recognises causes outside the application and hands them to Contentstack Support
 
 ## Expected Inputs
 
-Collected in the order set out below, not all at once. Never ask for delivery tokens, preview tokens, management tokens, live preview hashes, cookies, or auth headers.
+Collected step by step, never all at once. Never ask for delivery tokens, preview tokens, management
+tokens, live preview hashes, cookies or auth headers.
 
 ## Expected Outputs
 
-- The broken contract or mechanism, and the evidence for it
+- For a new integration: the documentation page, the requirements that apply, and how to verify
+- For a failing one: the broken contract and the evidence for it
 - The smallest correct change, or a plain statement that no application-side fix exists
-- A verification the user runs themselves
-- What to send Contentstack Support, when the cause sits outside the user's code
+- One verification the user runs
+- A Support handover note when the cause is outside the application
+
+## Example User Requests
+
+- "What does the Onboarding Check actually verify?"
+- "How do I set up Live Preview in our Next.js App Router site?"
+- "We have Live Preview working. What do we add for Visual Builder?"
+- "Live Preview loads but my edits never show up."
+- "The preview pane is blank / says it could not connect."
+- "Visual Builder shows Setup Complete but I can't click anything."
+- "Preview worked yesterday and now shows published content."
+- "Timeline always shows the current version."
+
+## Rules
+
+Follow these on every turn that diagnoses a failure.
+
+1. **Stop rule.** Once one contract is localised, stop collecting evidence and move to the fix.
+2. **Observed beats intended.** The Onboarding Check reports what the deployed build did; the code
+   reports what it intends. When they disagree, the check wins.
+3. **Falsification rule.** Before acting on a diagnosis, name the one artifact that would contradict
+   it, and get it.
+4. **Reproduction rule.** No code change without a reproduced failure. State the contract, the
+   evidence, and the action that reproduces it. No reproduction means a hypothesis: keep collecting.
+5. **Transition rule.** Worked then broke, a gate that advanced then regressed, a new error replacing
+   an old one: restart at step 2 and ask what changed, including your own edits this session.
+6. **No resilience while diagnosing.** Add no fallbacks, retries or caches. A fallback to published
+   content hides the exact signal being debugged.
 
 ## Workflow Summary
 
-Work these as a checklist and report it back ticked. An unticked step is a visible gap the user
-can see and question; a silently skipped step is how a wrong diagnosis gets past both of you.
+Report this back ticked. An unticked step is a visible gap.
 
 - [ ] 1. Identify the product.
-- [ ] 2. Setup or regression.
-- [ ] 3. Read the Onboarding Check. Not skippable whenever a preview pane renders.
-- [ ] 4. Detect framework and rendering mode from the code.
-- [ ] 5. Collect only the evidence detection could not supply.
+- [ ] 2. Question, new integration, never worked, or regression? Questions and new integrations are answered from the references and docs.
+- [ ] 3. Read the Onboarding Check.
+- [ ] 4. Detect framework, rendering mode and fetch layer from the code.
+- [ ] 5. Collect only the evidence steps 3 and 4 did not settle.
 - [ ] 6. Localise to one contract.
-- [ ] 7. Fix, verify, or hand to Contentstack Support.
+- [ ] 7. Fix and verify, or hand to Contentstack Support.
 
 ## Instructions
 
-Work these in order. Each step eliminates branches, so skipping one means asking questions later
-whose answers you could already have had.
-
-**Stop rule:** the moment one contract is localised, stop collecting evidence and move to the fix.
-Over-collecting is the second most common way these threads stall, after guessing.
-
-**Falsification rule:** before acting on a diagnosis, name the one artifact that would contradict
-it, and go get it. Confidence is the cue to do this, not the excuse to skip it. The commonest miss is
-a mode assumption: the code reads one way, and the Onboarding Check card or the network tab says
-otherwise. When they disagree, the observed behaviour wins over the intended one.
-
-**Reproduction rule:** no code change without a reproduced failure. Before editing application code,
-state the contract you believe is broken, the evidence for it, and the command or action that
-reproduces the failure. If you cannot reproduce it, you have a hypothesis, not a diagnosis. Keep
-collecting. A fix that "works" without a reproduced baseline may be working for a reason you have not
-identified, and you will not know which.
-
-**Transition rule:** any transition restarts at step 2. Worked then broke, a gate that advanced then
-regressed, a new error replacing an old one: each is a regression from a known state, and the first
-question is what changed since it last worked. Include your own edits in that question, not only the
-user's. Mid-session, the change most likely to have caused a transition is the one you just made, and
-it is also the one you are least likely to suspect. An Onboarding Check gate that goes backwards is
-information, not flakiness; do not answer it with a reload.
-
-**No-resilience rule:** while diagnosing, add no fallbacks, retries, caches, or optimisations.
-Falling back to published content when the preview fetch fails shows an editor published content
-while they believe they are looking at their edit, and hides the very signal being debugged. Fail
-visibly. If SDK-prescribed behaviour looks improvable, find the guard the SDK already has for that
-concern before changing anything; it usually exists.
-
 ### Step 1. Which product?
 
-Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
-Onboarding Check, or a failure set.
-
-| Product | What it is | Notes |
-|---|---|---|
-| **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
-| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags **plus** `mode: "builder"` in `init()`. `mode: "preview"` fails its Verify Mode gate even with tags present. Not a separate integration. |
-| **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
-| **Preview Sharing** | Share a preview link externally | Plan-gated, and a content-manager feature rather than an integration. The skill carries no troubleshooting for it; point at [Preview Sharing](https://www.contentstack.com/docs/content-managers/preview-sharing). |
-
-If the user is on Visual Editor, confirm whether plain Live Preview works. If it does not, that is
-the problem, and the Visual Editor symptom is downstream noise.
+Ask explicitly. Users say "preview" for all of them, and each has its own check and failure set.
 
-### Step 2. Setup, or regression?
-
-Ask: has this ever worked correctly, for anyone, on any route?
-
-**Never worked** goes to [references/setup-docs.md](references/setup-docs.md). Follow the official
-documentation for the framework and mode. Do not reconstruct setup steps from memory. Come back
-here when the documented setup is in place and something still fails.
-
-**Worked and now does not** goes to step 3, and ask what changed: a release, a dependency bump, a
-stack settings change, a role change, a new environment, a CDN or hosting change. This question is not
-only for intake. Every transition during the session, such as a gate that advanced and then regressed
-or a new error replacing the old one, comes back here, and the list of changes must include every
-edit you made since the last known-good state, not only the user's.
+| Product | What it is |
+|---|---|
+| **Live Preview** | Preview pane with content refresh. Everything else builds on it. |
+| **Visual Editor** | Live Preview plus on-canvas editing. Needs edit tags **and** `mode: "builder"` in `init()`. |
+| **Timeline** | Preview at a point in time. Needs `preview_timestamp` forwarded with the hash. |
+
+On Visual Editor or Timeline, confirm plain Live Preview works. If it does not, that is the problem.
+
+### Step 2. Question, new, never worked, or regression?
+
+- **A question about how something works, not a failure** ("what does the Onboarding Check
+  verify?", "does Timeline need anything extra?", "what is the difference between Live Preview and
+  Visual Builder?"): answer it from the relevant reference file and link the documentation page.
+  No diagnostic intake. If the answer reveals a failure, continue at step 3.
+- **Nothing integrated yet, or adding Visual Editor or Timeline:** read the framework and rendering
+  mode from the code, give the matching documentation page and the requirements that apply from
+  [references/setup-docs.md](references/setup-docs.md), and stop there. Do not ask diagnostic
+  questions about code that does not exist yet. When the user has it in place, continue at step 3 to
+  verify.
+- **Integrated, never worked:** continue at step 3.
+- **Worked, now broken:** ask what changed (release, dependency bump, settings, role, environment,
+  CDN or hosting), then continue at step 3.
 
 ### Step 3. Read the Onboarding Check
 
-Ask for a **screenshot** of the floating status card in the preview panel. Do this before any other
-diagnostic question. The product already ran the check you are about to run by hand.
+Ask for a **screenshot** of the check in the preview panel, before any other diagnostic question.
+Code access does not excuse this step. Users paraphrase step names, and each name maps to one gate.
+If the user already quoted a card or item name that matches the tables below word for word, use it
+and skip the screenshot.
 
-**This step is not skippable when a pane renders at all, and repository access does not excuse it.**
-Step 4 reads the code and tells you what the integration *intends*; the card tells you what the editor
-*observed* on the actual deployed build. They can disagree, most often on rendering mode, and when
-they do the card is the one that reflects reality. Do step 3 first, then let step 4 explain it.
+All three products evaluate their gates as a chain that stops at the first failure. **Read the first
+failing item. Everything before it passed; everything after it never ran.**
 
-Ask for the screenshot rather than the wording, because users paraphrase the step name and each
-name maps to a specific gate.
-
-Three products, three different checks. Confirm the product first. Full gate lists and meanings are
-in [references/onboarding-check.md](references/onboarding-check.md).
-
-**Live Preview** shows one card. The gates run as one ordered chain that stops at the first failure,
-so the step shown proves every earlier gate passed:
+Live Preview shows one card:
 
 | Card | Localises to |
 |---|---|
-| Could Not Connect to Website | Frame headers, auth gate, Base URL, certificate, browser blocking localhost |
-| Live Preview SDK Not Initialized | `init()` never ran on the client in the deployed build |
-| Outdated Live Preview SDK Version | Version below the supported minimum |
-| Preview Service Not Enabled | The fetch never switched host and headers |
-| Default Environment Not Set | Setup is fine; no default preview environment on the stack |
-| Setup Complete | Reachability, handshake, version and Preview Service are all fine |
-
-**Visual Editor shows a six-item list, not a card**, but it still stops evaluating at the first item
-that fails, so read the first incomplete item and ignore the ones under it. Configure environment
-(Default Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
-customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
-Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
-
-**Timeline runs a third check.** A small status card while it runs, then a full-pane "Set Up
-Timeline" overlay with three items once one fails. The items are chained, so the first empty circle
-is the failure and the ones below it never ran:
-
-| Overlay item | Localises to |
-|---|---|
-| Configure the environment | No environment on the Timeline URL and no default preview environment on the stack |
-| Install the latest Live Preview SDK | The `init()` handshake never reached Timeline, or the SDK major version is below 2 |
-| Generate and use Preview Token | No content request reached the Preview Service before the check stopped waiting |
+| Could Not Connect to Website | Network-level failure only: wrong or unreachable Base URL, DNS, bad certificate, mixed content, the browser blocking localhost |
+| Live Preview SDK Not Initialized | No init handshake: `init()` never ran on the client, `enable` not truthy, **or the frame is blank** (frame headers, an auth or password screen) |
+| Outdated Live Preview SDK Version | SDK below 1.4.0 |
+| Preview Service Not Enabled | Content fetch never switched to the preview host and headers |
+| Default Environment Not Set | Integration fine; the stack has no default preview environment |
+| Setup Complete | Reachability, handshake, version and Preview Service all fine |
 
-The overlay appears ten seconds after the last status change, and item 3 gives up waiting at about
-nine, so a slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
-before believing it.
+Visual Editor and Timeline show a status card while checking, then a full-pane overlay ("Set Up
+Visual Editor", "Set Up Timeline") listing their items. Gates, verbatim item text and timing are in
+[references/onboarding-check.md](references/onboarding-check.md). The two Visual Editor items that
+catch users coming from a Live Preview guide: **Verify Mode for Live Preview** fails on
+`mode: "preview"`, and **Validate the Base URL** needs the Base URL origin to match the previewed page
+exactly.
 
-Two readings that decide the whole branch:
+Two readings decide the branch:
 
-- **Setup Complete, but nothing is editable.** The check never inspects `data-cslp`. This is edit
-  tags, every time. Go to contract 2 in step 6.
-- **No card at all.** Absence is not a pass. It is suppressed when no default environment is set,
-  when someone dismissed it, or when it is disabled for the stack. Verify the contracts by hand.
+- **Setup Complete, nothing editable.** The check never inspects `data-cslp`. Go to contract 2.
+- **Setup Complete, only fields from referenced entries not editable.** Tags are not rebased to the
+  referenced entry: `cslp-not-rebased-to-referenced-entry` in faq-visual-editor.md.
+- **No check at all.** Absence is not a pass. See "When the check does not appear" in
+  onboarding-check.md, then verify the contracts by hand.
 
-### Step 4. Establish framework and rendering mode
+### Step 4. Detect framework, mode and fetch layer
 
-**Detect this, do not ask for it.** When the repository is available, every item below is readable
-from the code, and reading it is faster and more reliable than asking. Detection does not replace
-step 3: the card still comes first, because it reports the deployed build rather than the branch you
-are reading. Developers routinely answer
-"Next.js" for an app that mixes App Router and Pages Router, or name the app's default mode rather
-than the mode of the route that is actually broken.
+Read the code instead of asking. State what you found and ask only for confirmation.
 
-Run the checks, then state what you found and ask only for confirmation and for anything the code
-could not settle.
-
-| Question | Where to look | What it tells you |
+| Check | Where | Why |
 |---|---|---|
-| Framework and version | `package.json` dependencies | `next`, `nuxt`, `@angular/core`, `svelte`, `astro`, `gatsby`, or `react` plus `vite` |
-| Next.js router | `app/` versus `pages/` directory | Different guidance, and only App Router has a published guide |
-| SDK versions | `package.json`, lockfile | Against the minimums in Tooling Notes |
-| One SDK copy | lockfile, plus any `<script type="module">` in the HTML | An npm install alongside a CDN import of another version behaves like a config bug |
-| Rendering mode of the route | `export const dynamic`, `revalidate`, `getStaticProps`, `getServerSideProps`, `output: "export"` | The mode of that route, which is what matters |
-| `ssr` setting | the `init(` call site | Explicit value, or absent and therefore inferred |
-| `stackSdk` passed | the `init(` call site | Mandatory in CSR, and what the SDK uses to default `ssr` |
-| Init placement | the file containing `init(`, and whether it is `"use client"` | Contract 1. Server-only placement is the most common Next.js miss |
-| Edit tags | `addEditableTags` | Contract 2. Absent means Visual Editor cannot work, whatever else is true |
-| Fetch layer | `@contentstack/delivery-sdk` import, raw `fetch`, or a GraphQL client | Decides which form of contract 3 applies |
-| Preview host wiring | `preview_token`, `live_preview`, any hostname constant | Contract 3 |
-| Cache posture | `fetch` cache options, `revalidate`, CDN or middleware config | The "works locally, fails deployed" class |
-
-That sweep usually settles contracts 1, 2 and 3 in step 6 before you ask the user anything, and it
-often makes step 5 unnecessary.
-
-Two things the repository cannot tell you. Ask for these:
-
-1. **Where it is served**: localhost, a preview deployment, or production.
-2. **Whether the deployed build matches the branch you are reading.** An environment variable that
-   does not parse as a boolean, or a stale deploy, makes correct-looking code behave as if init
-   never ran.
-
-Without repository access, ask for the same list, in this order: framework and version, the mode of
-the affected route, the fetch layer, and the `init()` call site.
-
-The SDK ships no framework adapters, no framework peer dependencies, and no per-framework code
-paths. Framework choice decides only where `init()` may run and whether hydration preserves edit
-tags. Everything else follows from mode and fetch layer.
-
-| Mode | `ssr` | Hash travels via | Updates arrive as |
+| Framework, router | `package.json`; `app/` vs `pages/` | Decides where `init()` may run |
+| SDK versions, one copy | `package.json`, lockfile, any `<script type="module">` | Two copies behave like a config bug |
+| Route's rendering mode | `dynamic`, `revalidate`, `getStaticProps`, `getServerSideProps`, `output: "export"` | The broken route's mode, not the app default |
+| `ssr` | `init(` call site **and** the Stack's `live_preview.ssr` | Stack config overrides `init({ ssr })` |
+| `stackSdk`, `mode` | `init(` call site | `stackSdk` absent defaults `ssr` to `true` |
+| Init placement | file containing `init(`, `"use client"` | Contract 1 |
+| Edit tags | `addEditableTags` | Contract 2 |
+| Fetch layer, host wiring | Delivery SDK, raw `fetch`, GraphQL client; `preview_token`, `live_preview`, hosts | Contract 3 |
+| Cache | fetch cache options, `revalidate`, CDN or middleware | "Works locally, fails deployed" |
+
+The code cannot tell you where the site is served or whether the deployed build matches the branch.
+Ask for both.
+
+Mode decides how updates arrive:
+
+| Mode | `ssr` | Hash reaches the fetch via | Updates |
 |---|---|---|---|
-| CSR + REST | `false` | postMessage, into `stackSdk` | `onEntryChange` refetch, no reload |
-| SSR + REST | `true` | `live_preview` query parameter | full iframe reload, driven by the parent. `onEntryChange` subscribers **never fire** in this mode |
-| CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch, manual host swap |
-| SSR + GraphQL | `true` | `request.query.live_preview` | full reload, manual host swap |
-| SSG | `false` | postMessage | runs as CSR at runtime |
-
-**`onEntryChange` is inert under `ssr: true`.** The SDK guards its entry-change dispatch on `!ssr`,
-so any subscriber registered in an SSR app never runs. Registering one to trigger a refetch or
-`router.refresh()` produces a callback that looks correct and does nothing. Under `ssr: true` the
-update path is the parent reloading the iframe with the new hash; the app's only job is to read the
-hash off that request. If you want client-driven refresh, the route has to be CSR (`ssr: false`).
-
-`stackSdk` is mandatory in CSR and is what the SDK uses to default `ssr`. A CSR app that omits it
-silently gets SSR behaviour; an SSG site initialised with `ssr: true` gives blank screens rather
-than an error. Two mode traps to check before prescribing: **SSR** needs a per-request Stack
-instance, because a module-level one leaks one editor's draft into other users' responses; **SSG** is
-supported, but only in CSR mode: a prerendered page never sees the `live_preview` query parameter,
-so the documented setup is `ssr: false` with `stackSdk`, where the hash arrives by postMessage
-instead. **ISR** is the harder case: a regenerated page is still a cached page, and caching has to be off
-on the preview path. There is no published recipe for combining ISR with Live Preview.
-
-Detail and the framework coverage table are in
-[references/rendering-modes.md](references/rendering-modes.md); init placement per framework is in
+| CSR (incl. SSG at runtime) | `false` | postMessage into `stackSdk`; `ContentstackLivePreview.hash` for GraphQL | `onEntryChange` refetch |
+| SSR | `true` | `live_preview` query parameter on the request | Parent reloads the iframe; `onEntryChange` never fires on edits |
+
+Detail per mode, including SSG, ISR and GraphQL, is in
+[references/rendering-modes.md](references/rendering-modes.md). Init placement per framework is in
 [references/frameworks.md](references/frameworks.md).
 
-### Step 5. Collect logs and one request
-
-Only for what step 4 could not settle. With repository access the contracts are often already
-localised, and the single most valuable item left is the request host. Skip whatever you can
-already answer, and ask for the rest in one pass rather than one at a time.
-
-1. **Browser console, with the preview panel open.** Look for the init handshake, CSP or frame
-   refusals, CORS failures, and framework hydration errors. Ask them to reproduce with the console
-   open, because most of these fire once at load. Read it against the noise list below before
-   drawing any conclusion.
-2. **Server-side logs**, for SSR, middleware, BFF, or proxy setups. This is where a swallowed
-   preview fetch error lives, and it is invisible in the browser. Skip for pure CSR.
-3. **One failing request from the Network tab**: full request URL and host, response status, and
-   response headers. Redacted.
-
-**Check the console output against [references/console-noise.md](references/console-noise.md)
-before concluding anything from it.** Preview runs the site in an iframe with postMessage between
-two apps, so a healthy setup still produces console chatter — `NO_REQUEST_LISTENER_FOUND` and third-party script errors both appear on working
-integrations. If one of those is the only thing in the console, you have no console evidence, not
-evidence of a problem.
-
-The request host alone settles the most common failure of all. During an active preview
-session, content coming from `cdn.contentstack.io` or `graphql.contentstack.com` means the hash is
-not reaching the fetch, regardless of the reported symptom.
-
-Also ask, in one line each, the questions that separate causes:
-
-- **One user or everyone?** One user points at their role. Preview runs as that user and applies
-  their full ACL — content types, entries, fields, locales, assets — so anything they cannot read
-  comes back empty. Delivery uses a delivery token and applies none, which is why the published
-  page looks fine. This is by design: the fix is usually defensive rendering on the site, not a
-  product issue.
-- **Localhost or deployed?** Working locally and failing deployed is a cache on the preview path,
-  or a frame header.
-- **Consistent or intermittent?** Intermittent and user-dependent under SSR is a shared
-  module-level Stack instance. That one reaches public traffic.
-- **Which locale, and which variant?** Both change the fetch, and both are common false leads.
+### Step 5. Collect what is still open
 
-### Step 6. Localise to one contract
+Ask for the rest in one message, skipping anything already settled:
+
+1. **Browser console** with the preview panel open, reproduced after a reload. Check it against
+   [references/console-noise.md](references/console-noise.md) first: some messages appear on
+   healthy setups and are not evidence.
+2. **Server logs**, for SSR, middleware, BFF or proxy setups. A swallowed preview fetch error lives
+   here.
+3. **One content request from the Network tab**: host, status, response headers, redacted. A
+   delivery CDN host for the stack's region during a preview session means the hash is not reaching
+   the fetch, whatever the symptom.
 
-A working integration needs four independent contracts. They fail separately and complain
-identically. Name which one is unmet, with the evidence, before proposing anything.
+And, one line each: one user or everyone (one user points at their role), localhost or deployed
+(deployed-only points at a cache or frame header), consistent or intermittent (intermittent under SSR
+points at a shared Stack instance), which locale and variant.
+
+### Step 6. Localise to one contract
 
 | # | Contract | One-look check |
 |---|---|---|
-| 1 | `init()` runs, on the client, in the deployed build | The Live Preview Onboarding Check moves past "Live Preview SDK Not Initialized" — that item clears only when the SDK's init message reaches the app, which happens only from `init()` |
-| 2 | Edit tags are generated and land on DOM elements | Some rendered element carries `data-cslp` |
-| 3 | The hash reaches the fetch, which switches host plus headers | Content requests hit a `*-preview.contentstack.com` host |
-| 4 | The preview target is reachable in an iframe | The pane renders at all |
-
-Contract 1 gates 2 and 3. Contract 4 gates everything. Steps 3, 4 and 5 have usually already decided
-this; if they have, do not re-derive it.
-
-For contract 2, the one the Onboarding Check cannot see:
-
-```jsx
-addEditableTags(entry, contentTypeUid, true, locale);
-<h1 {...data.$?.title}>{data.title}</h1>
-```
-
-`mode: "builder"` does not generate tags; only `addEditableTags()` does. (`mode: "builder"` is
-still required, because Visual Editor's Verify Mode gate fails on `mode: "preview"`.) The call
-mutates the entry and returns nothing, and the third argument must be `true` for React and JSX.
-Call it once per top-level entry: references resolved with `includeReference()` or `include[]`
-carry `uid` and `_content_type_uid`, and their tags are rebased to the referenced entry
-automatically. A separate call is needed only for references merged by hand, or GraphQL nodes
-fetched without `system`. Mirror the data path exactly, because references come back as arrays:
-`post.author[0].$?.name`, not `post.$?.author.name`.
-
-Tag leaves **and** containers. A scalar takes `entry.$.field` on the element that renders the value.
-Multiple fields, references and modular blocks take `entry.$.field` on the wrapper plus
-`entry.$["field__" + i]` on each instance; the canvas attaches add and reorder controls only when
-an instance sits inside an element carrying the container tag. An empty multiple or block field
-keeps its wrapper in the DOM while previewing, marked with `VB_EmptyBlockParentClass` and the
-container tag, or the canvas has nothing to draw its add button on.
-
-Enumerate fields from `Object.keys(entry.$)` and diff against what the page renders. Do not eyeball
-the JSX. The full key convention and a per-field-kind checklist are in
-[references/edit-tags.md](references/edit-tags.md).
-
-For contract 3:
-
-```js
-// SSR reads it from the request. CSR uses ContentstackLivePreview.hash.
-const livePreviewHash = request.query.live_preview;
-
-if (livePreviewHash) {
-  headers.append("live_preview", livePreviewHash);
-  headers.append("preview_token", PREVIEW_TOKEN);
-  url.hostname = LIVE_PREVIEW_HOST;   // rest-preview.contentstack.com
-} else {
-  url.hostname = CONTENTSTACK_CDN_HOST; // cdn.contentstack.io
-}
-```
-
-If the symptom is behavioural rather than a failed contract, look it up in
-[references/symptom-index.md](references/symptom-index.md), which routes to
-[faq-setup.md](references/faq-setup.md),
-[faq-preview-runtime.md](references/faq-preview-runtime.md),
-[faq-visual-editor.md](references/faq-visual-editor.md), and
-[faq-timeline.md](references/faq-timeline.md).
-
-For a first-time setup or an end-to-end sweep,
-[references/preflight-checklist.md](references/preflight-checklist.md) runs the contracts as 34
-ordered checks.
-
-### Step 7. Fix, verify, or hand to Contentstack Support
-
-Before proposing any change, satisfy the reproduction rule: contract, evidence, and the action that
-reproduces the failure, stated in that order. Then propose the smallest correct change at the right
-layer: init, tagging, fetch, cache boundary, routing, or stack configuration, and give one verification
-the user runs themselves. The verification is the reproduction step run again with the opposite
-result.
-
-Some causes sit outside the user's application entirely: stack provisioning, plan gating, and
-browser policy. Recognising one early beats any workaround, because no change to the site can
-resolve it. See [references/contact-support.md](references/contact-support.md) for the list, and
-**produce the handover note it defines** — filled from what steps 1–6 already collected — for the
-user to paste into their ticket to Contentstack Support.
+| 1 | `init()` runs on the client in the deployed build | Live Preview check gets past "Live Preview SDK Not Initialized" |
+| 2 | Edit tags are generated and land on DOM elements | Rendered elements carry `data-cslp` |
+| 3 | The hash reaches the fetch, which switches host and headers | Content requests hit the region's `*-preview` host |
+| 4 | The site is reachable in an iframe | The pane renders at all |
+
+Contract 4 gates everything; contract 1 gates 2 and 3. Name the unmet one with its evidence.
+
+- Contract 2 detail, key conventions and the empty-block contract:
+  [references/edit-tags.md](references/edit-tags.md).
+- Behavioural symptoms: look them up in [references/symptom-index.md](references/symptom-index.md),
+  which routes to [faq-integration.md](references/faq-integration.md),
+  [faq-preview-runtime.md](references/faq-preview-runtime.md),
+  [faq-visual-editor.md](references/faq-visual-editor.md) and
+  [faq-timeline.md](references/faq-timeline.md).
+
+### Step 7. Fix and verify, or hand over
+
+State contract, evidence and reproduction, then the smallest change at the right layer: init, tags,
+fetch, cache, routing, or stack configuration. The verification is the reproduction run again with
+the opposite result.
+
+Some causes sit outside the application: provisioning, plan gating, browser policy. No site change
+fixes them. See [references/contact-support.md](references/contact-support.md) and produce its
+handover note from what steps 1 to 6 already collected.
 
 ## Output Format
 
-Lead with the broken contract or mechanism and the evidence for it. Then the smallest correct
-change, as a snippet or diff, or a plain statement that no application-side fix exists. Then one
-verification. Attach mode-specific caveats to the step they affect.
+New integration: follow "Reply shape" in [references/setup-docs.md](references/setup-docs.md).
+
+Failing integration: lead with the broken contract and its evidence. Then the smallest change as a snippet or diff, or a
+plain statement that no application-side fix exists. Then one verification.
 
-When you still need evidence, ask for the specific artifact that separates the remaining
-candidates, and say what each possible answer would mean. Do not send a generic list of requests.
+When evidence is still missing, ask for the one artifact that separates the remaining candidates and
+say what each answer would mean.
 
-Say when a behaviour applies only to preview and not production, and say the reverse too, because
-preview output reaching real visitors is a production incident rather than an authoring annoyance.
+Say whether a behaviour applies to preview only or to production too. Preview output reaching real
+visitors is a production incident.
 
 ## Tooling Notes
 
-Read-only inspection first, with Read, Grep and Glob when the repository is available. Useful
-greps: the `init(` call site, `addEditableTags`, `onEntryChange`, `live_preview`, `preview_token`,
-any hostname constant, and cache configuration on the preview route.
+Read-only inspection with Read, Grep and Glob. Useful greps: `init(`, `addEditableTags`,
+`onEntryChange`, `live_preview`, `preview_token`, hostname constants, cache configuration.
 
-Minimum versions: Live Preview Utils v3.0+ and Delivery SDK v3.20.3+ for Visual Editor, and Live
-Preview Utils v4.4.4+ for `setPageContext()`. Confirm exactly one copy of the preview SDK is
-loaded.
+Minimum versions: Live Preview Utils v3.0+ for Visual Editor (legacy `contentstack` JavaScript SDK
+v3.20.3+); Live Preview Utils v4.4.4+ for `setPageContext()`.
 
-When the repository is not available, run the same protocol against described code and screenshots.
-Do not pretend to have inspected code.
+Without repository access, run the same steps against described code and screenshots. Do not claim
+to have inspected code.
 
 ## Security
 
 ### Defaults
 
-- Never expose delivery tokens, preview tokens, management tokens, or environment secrets.
-- Treat preview tokens and live preview hashes as credentials. Do not ask users to paste them, and
-  redact them if they appear. Ask for redacted logs and screenshots.
-- A management token in client-side Live Preview configuration is an exposure.
+- Never ask for, echo or reconstruct tokens or live preview hashes. Ask for redacted logs and
+  screenshots. If a secret appears, tell the user to rotate it.
+- A management token in client-side configuration is an exposure.
 - Do not recommend enabling Live Preview in production builds. An edit button on a public site is a
   symptom of exactly that.
-- Preview output served to real visitors is a production data-exposure issue, not a cosmetic bug.
-- Validate preview target hosts before suggesting header or CSP changes.
+- Validate preview target hosts before suggesting header or CSP changes, and scope any relaxation to
+  the preview deployment.
 
 ### Destructive Actions
 
-Do not change stack settings, roles, tokens, cache configuration, or environment configuration
-automatically. Propose the change, state the blast radius, and require confirmation.
-
-### Secrets
-
-Never reveal, echo, or reconstruct tokens or hashes. If a secret appears in provided input, tell
-the user to rotate it.
+Do not change stack settings, roles, tokens, cache or environment configuration automatically.
+Propose the change, state the blast radius, and require confirmation.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md b/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
index 2d609f0..c629387 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
@@ -13,12 +13,16 @@ problem.** Say so and move to the network tab.
 
 ## The list
 
-### `NO_REQUEST_LISTENER_FOUND` / `No ack listener found`
+### `NO_REQUEST_LISTENER_FOUND` and `No ack listener found`
 
-Routine. It means a postMessage arrived with no registered listener, which happens normally during
-load and teardown. Appears on working setups.
+Two different postMessage errors from the same library, both routine:
 
-Never conclude anything from it on its own. It does not affect SSR content, and it is not evidence
+- `NO_REQUEST_LISTENER_FOUND` ("No request listener found for event …"): one side sent a request
+  the other side has no handler for, for example a `scroll` event during load.
+- `No ack listener found`: an acknowledgement arrived after its sender stopped waiting, typically
+  during load or teardown.
+
+Both appear on working setups. Never conclude anything from either on its own. It does not affect SSR content, and it is not evidence
 that the handshake failed — read the Live Preview Onboarding Check instead, which sticks on **Live
 Preview SDK Not Initialized** until the SDK's init message arrives.
 
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md b/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
index db17626..b0ba0b4 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
@@ -20,7 +20,7 @@ with Contentstack Support.
 | Symptom | What it actually is |
 |---|---|
 | A previously working `localhost` preview stops working, console shows a local network access error | Chrome's Local Network Access policy now blocks the app origin from framing localhost. Only the user can grant the permission, in the browser. |
-| Preview pane blank, and the site sits behind platform password protection or third-party SSO | Those screens set `X-Frame-Options: DENY` on themselves. Contentstack cannot inject headers into a browser-originated iframe request. Workarounds, cheapest first: enable **Open in New Tab**, which renders the site outside the iframe so frame headers stop applying; otherwise disable protection on the preview deployment, put a bypass token in the Base URL, or front it with a server-side proxy that strips the header. |
+| Preview pane blank, and the site sits behind platform password protection or third-party SSO | Those screens set `X-Frame-Options: DENY` on themselves. Contentstack cannot inject headers into a browser-originated iframe request. Workarounds, cheapest first: enable **Open in New Tab**, which renders the site outside the iframe so frame headers stop applying; otherwise disable protection on the preview deployment, put a bypass token in the Base URL (scoped to the preview deployment and rotated, since every stack user can read it), or front it with a server-side proxy that strips the header. |
 | Ad slots, consent widgets, or other host-dependent third-party scripts misbehave in the pane | Those scripts key off the top-level origin, which is the Contentstack app inside an iframe. Expected, not a preview defect. |
 
 ## How to hand it over
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md b/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
index f045012..2a5d030 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
@@ -12,12 +12,15 @@ addEditableTags(entry, contentTypeUid, true, locale /*, { useLowerCaseLocale: fa
 
 - Mutates the entry and returns nothing. It attaches a `$` object at every level: the entry, each
   group, each block instance, and each resolved reference.
-- Call it **once per top-level entry**. A resolved reference that carries `uid` and
+- Call it **once per top-level entry**. A resolved reference that carries top-level `uid` and
   `_content_type_uid` (which `includeReference()` and REST `include[]` preserve) gets its own `$`,
   rebased to the referenced entry: `author.<author_uid>.<locale>.title`, not
-  `blog_post.<post_uid>.<locale>.author.0.title`. A separate call per referenced entry is needed
-  only when references were fetched separately and merged by hand, or when a GraphQL query omitted
-  `system { uid content_type_uid locale }`.
+  `blog_post.<post_uid>.<locale>.author.0.title`. The locale segment is the reference's own
+  `locale` when it has one. A separate call per referenced entry is needed when references were
+  fetched separately and merged by hand.
+- **GraphQL never rebases on its own.** A GraphQL node nests `uid` and `content_type_uid` under
+  `system`, and references sit under `edges[].node`, so the rebase condition is never met. Normalise
+  the response first (see `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md`).
 - The third argument must be `true` in React and JSX so the values are objects you can spread.
 - `locale` and `contentTypeUid` are lowercased; pass `{ useLowerCaseLocale: false }` for stacks with
   mixed-case locale codes.
@@ -104,9 +107,11 @@ Hover and click on the marked wrapper draw no outline; the button is the afforda
 ## Variants
 
 Highlight Variant and audience mode key on v2 tags:
-`v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>`. `addEditableTags()` emits them only for fields
-listed in the entry's `_applied_variants`, and the response includes that map only when the request
-carries `include_applied_variants=true`. Pass it as a query parameter on the content request:
+`v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>`. `addEditableTags()` emits them for fields
+listed in the entry's applied-variants map (`_applied_variants`, or `system.applied_variants`) and
+for fields nested under a listed path. Each referenced entry uses its own map, not the parent's. The
+response includes the map only when the request carries `include_applied_variants=true`. Pass it as
+a query parameter on the content request:
 
 ```js
 // Honoured: a query parameter on the request itself
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
similarity index 84%
rename from codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
rename to codex/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
index d08f67d..36bde9a 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
@@ -1,14 +1,14 @@
-# Setup FAQ
+# Integration FAQ
 
-Setup and first-integration failures, ordered by how often they come up in practice. Each entry
-gives the symptom as users actually report it, the mechanism behind it, the fix, and a
-verification step.
+Failures in an existing integration's wiring: reachability, init, edit tags, the fetch, hosts and
+stack configuration. Ordered by how often they come up. Each entry gives the symptom as users report
+it, the mechanism, the fix, and a verification step.
 
-Read this after localising the problem to one of the four contracts in the parent skill. The
-contract tells you which section to read; this file tells you what to do.
+Read this after localising the problem to one of the four contracts in SKILL.md. For first-time
+setup, use `setup-docs.md` instead.
 
 ### app-fetches-from-delivery-cdn-instead-of-preview-service
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Live Preview / Visual Editor loads the site fine, but edits made in the entry form or the right-hand panel never appear in the preview. Content only changes after the entry is published. The Onboarding Check gets past the site-loading and SDK gates and then stops on **Preview Service Not Enabled**. Variant selection in Visual Editor also shows the base entry.
 - **frameworks**: Next.js (Pages + App Router), React, Angular, Gatsby, Vue/Nuxt, Java/Spring, framework-agnostic REST/GraphQL clients
 - **rendering_modes**: any
@@ -35,22 +35,23 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### iframe-blocked-by-x-frame-options-or-csp-frame-ancestors
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: The Live Preview / Visual Editor pane is blank or shows "`<your-host>` refused to connect". Console shows `Refused to display '<url>' in a frame because it set 'X-Frame-Options' to 'sameorigin'` (or `deny`), or a `frame-ancestors` CSP violation. Frequently paired with a `401` on a `HEAD`/`GET` of the site root. Works on localhost, fails on the deployed dev/QA/staging host.
 - **frameworks**: framework-agnostic (server / CDN / hosting-platform header config)
 - **rendering_modes**: any
 - **root_cause**: Contentstack renders the site inside an iframe on the app origin. Any `X-Frame-Options: SAMEORIGIN|DENY` or a CSP `frame-ancestors` directive that does not include the Contentstack app origin makes the browser refuse the frame before the page can run. Platform-level deployment protection (for example a hosting provider's password protection) adds `X-Frame-Options: DENY` to the password screen itself, so even the auth prompt cannot render.
 - **fix**:
-  1. Remove `X-Frame-Options` for the preview host and use CSP instead: `Content-Security-Policy: frame-ancestors 'self' https://*.contentstack.com https://*.contentstack.io;` (`X-Frame-Options` has no allowlist syntax; a bare `SAMEORIGIN` always wins).
+  1. Remove `X-Frame-Options` for the preview host and use CSP instead, allowing the Contentstack app origin for the stack's region: `Content-Security-Policy: frame-ancestors 'self' https://app.contentstack.com;` (for example `https://eu-app.contentstack.com` in EU). `https://*.contentstack.com` is the broader fallback. `X-Frame-Options` has no allowlist syntax; a bare `SAMEORIGIN` always wins.
   2. Apply the header on every route, not just the site root. A route that redirects to a different hostname than the configured Base URL will also fail.
-  3. If the deployment sits behind platform password protection, note that no header or query parameter can be injected into a browser-originated iframe request from Contentstack. Options: disable protection on the preview deployment, use a bypass token embedded in the Base URL, put a server-side proxy in front that injects the header, or use Live Preview → Open in New Tab (a plan-gated feature that renders outside the iframe).
+  3. If the deployment sits behind platform password protection, note that no header or query parameter can be injected into a browser-originated iframe request from Contentstack. Options: disable protection on the preview deployment, use a bypass token embedded in the Base URL (every stack user can read the Base URL, so scope the token to the preview deployment and rotate it), put a server-side proxy in front that injects the header, or use Live Preview → Open in New Tab (a plan-gated feature that renders outside the iframe).
   4. Third-party SSO screens that themselves set `X-Frame-Options: DENY` cannot render in the iframe at all. Use Open in New Tab, which renders the preview outside the iframe so those screens can load.
+  5. On the Live Preview Onboarding Check this shows as **Live Preview SDK Not Initialized**, not "Could Not Connect to Website". The reachability gate is a `no-cors` request, which succeeds on any HTTP response, so frame headers and auth screens pass it.
 - **verification**: `curl -I https://<preview-host>/<some-deep-route>` and confirm no `X-Frame-Options` and a `frame-ancestors` value that includes the Contentstack app origin. Reload Live Preview; the pane should render.
 
 ---
 
 ### error-382-create-tracker-before-starting-live-preview-session
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Preview API requests fail with
   `{"error_message":"Please create tracker before starting live preview session","error_code":382,"status":400}`
   (a sibling variant is `{"error_message":"Please provide live preview hash in request","error_code":382}`). Often appears the moment `mode: "builder"` is set, or when the site is opened directly rather than from inside the Contentstack preview pane. Sometimes reproduces for one developer and not another on "identical" setups.
@@ -67,18 +68,18 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### edit-tags-not-generated-or-not-spread
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar. Clicking the canvas does nothing, or selects the wrong (parent) element. `entry.$` / `post.$` is `undefined` in the app, or `data-cslp` renders as literal text instead of an attribute. Live Preview auto-refresh often still works, which makes it look like a Visual Editor bug.
 - **frameworks**: React, Next.js, Vue, Angular, Gatsby, Blazor/.NET, jQuery
 - **rendering_modes**: any
 - **root_cause**: Tags need two independent things and teams usually do only one: `addEditableTags()` must run on every fetched entry, **and** the generated `$` attributes must be spread onto the DOM elements that render each field. `mode: "builder"` does not generate tags, but it is still required: Visual Editor's Verify Mode gate fails on `mode: "preview"`, so tags alone do not produce a canvas. Four ways this goes wrong: the call is missing entirely (commonly commented out during a migration); `tagsAsObject` is `false` or omitted, producing a `data-cslp` string React cannot spread; the content type **title** is passed instead of its **uid**; or the call is correct but nothing spreads the result into the markup.
 - **fix**:
-  1. Call it on every entry right after fetching, including referenced entries: `addEditableTags(entry, contentTypeUid, true, locale)`. The third argument must be `true` for React and JSX.
+  1. Call it once per top-level entry right after fetching: `addEditableTags(entry, contentTypeUid, true, locale)`. The third argument must be `true` for React and JSX. References resolved with `includeReference()` or `include[]` are tagged in the same call; only hand-merged references need their own call.
   2. Pass the content type **uid**, not its display title.
   3. Spread onto the element that renders the value: `<h1 {...post.$?.title}>{post.title}</h1>`.
   4. Mirror the data path exactly. References come back as arrays, so it is `post.author[0].$?.name`, not `post.$?.author.name`.
-  5. Tag the leaf element that holds the value, one `data-cslp` per element. Tagging a wrapper group instead of the field makes Visual Editor select the wrong field.
-  6. Check nothing strips them at build time: `cleanCslpOnProduction: true` removes `data-cslp` from the DOM, and `PURGE_PREVIEW_SDK=true` no-ops the whole SDK.
+  5. Put a scalar field's tag on the element that renders its value, not on a surrounding wrapper, or Visual Editor selects the wrong field. Multiple, reference and modular-block fields are the exception: their container tag goes on the wrapper and each instance gets its own `field__<index>` tag. See `edit-tags.md`.
+  6. Check nothing strips them: with `enable: false`, the default `cleanCslpOnProduction: true` removes `data-cslp` from the DOM, and `PURGE_PREVIEW_SDK=true` no-ops the whole SDK. A build that evaluates `enable` as false on the preview deployment loses its tags this way.
   7. For GraphQL, the response shape itself breaks tag paths — see `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md` for the normalizer that has to run before `addEditableTags()`.
   8. If you only want auto-refresh and not in-context editing, use `mode: "preview"` rather than `mode: "builder"` with no tags.
 - **verification**: In DevTools on the previewed page, `document.querySelectorAll('[data-cslp]').length` must be greater than 0, and a rendered field must carry `data-cslp="<content_type_uid>.<entry_uid>.<locale>.<field_path>"`. Hovering it in the canvas should highlight it, and clicking should focus the matching field in the form panel.
@@ -86,13 +87,13 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### preview-url-does-not-resolve-to-the-app-route
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited. Navigating inside the preview 404s. Sometimes the pane says "You are currently previewing a different webpage". Affects entries whose real URL is nested, taxonomy-driven, multi-tenant, or has no `url` field at all.
 - **frameworks**: Next.js, React, framework-agnostic
 - **rendering_modes**: any
 - **root_cause**: By default the preview URL is `environment Base URL` + the entry's `url` field. That only works when app routing maps 1:1 to the `url` field. Nested paths, custom route prefixes, several content types with different URL shapes, multiple sites served from one stack, or a URL stored in a custom text field instead of the built-in `url` field all break the concatenation.
 - **fix**:
-  1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL). This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated. Follow the docs for the pattern syntax, placeholders, Base URL aliases and defaults: [Custom Preview URLs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls).
+  1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL). This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated. Follow the docs for the pattern syntax, placeholders, Base URL aliases and defaults: [Custom Preview URLs](https://www.contentstack.com/docs/headless-cms/custom-preview-urls).
   2. With Custom Preview URLs enabled, tell the editor which entry each page is by calling `setPageContext({ entryUid, contentTypeUid })` on every page (Live Preview Utils v4.4.4+). Fallbacks: the `window.__CS_PAGE_CONTEXT__` global, or `<meta name="contentstack:entry-uid">` and `<meta name="contentstack:content-type-uid">`. **This only has an effect when the Custom Preview URLs setting exists for the stack and is configured.** Without it the editor resolves by URL alone and the call is silently ignored — it does not error, so a stack without the feature looks like `setPageContext` not working.
   3. Do not narrow the environment Base URL to one content type's prefix (for example `.../inspiration/articles/`) — that fixes one content type and breaks all others.
   4. Verify the entry's `url` field actually corresponds to a route the app serves, and that the route renders the content type you expect.
@@ -101,14 +102,14 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade
-- **bucket**: setup
-- **symptom**: Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump breaks a previously working integration — `setConfigFromParams` disappears, `ReferenceError: window is not defined` in server code, the Edit button suddenly renders in production, or `Live_Preview_SDK: To use edit tags, you must provide the stack API key`.
+- **bucket**: integration
+- **symptom**: Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump breaks a previously working integration: `setConfigFromParams` is no longer callable, `ReferenceError: window is not defined` in server code, the Edit button suddenly renders in production, or `Live_Preview_SDK: To use edit tags, you must provide the stack API key`.
 - **frameworks**: Next.js, React, Gatsby, Angular
 - **rendering_modes**: any
-- **root_cause**: Feature availability is version-gated and majors carry breaking changes that were not always documented. Pinned-old dependency policies (auto-update disabled) leave teams on v1.x where the required callbacks do not exist. The v2 → v3 jump removed `setConfigFromParams` (its replacement reads `window`, which throws in SSR) and made `stackDetails.apiKey` mandatory for edit tags.
+- **root_cause**: Feature availability is version-gated and majors carry breaking changes. Pinned-old dependency policies (auto-update disabled) leave teams on v1.x where builder mode does not exist; it arrived in v3. `setConfigFromParams` is no longer part of the public API, and code that replaced it with a helper reading `window` throws in SSR. `stackDetails.apiKey` is required for edit tags and builder mode.
 - **fix**:
-  1. Meet the minimums: Live Preview Utils **v3.0+** and Delivery SDK **v3.20.3+** for Visual Editor; **v4.4.4+** if you use `setPageContext()`.
-  2. Pass `stackDetails: { apiKey, environment }` explicitly in `init()` — v2+ no longer derives the API key from the Stack object for edit tags.
+  1. Meet the minimums: Live Preview Utils **v3.0+** for Visual Editor (legacy `contentstack` JavaScript SDK **v3.20.3+**; every `@contentstack/delivery-sdk` release qualifies); **v4.4.4+** if you use `setPageContext()`.
+  2. Pass `stackDetails: { apiKey, environment }` explicitly in `init()`. Builder mode throws without them.
   3. In SSR, stop calling `setConfigFromParams`. Read the query parameters from the request and apply them with `livePreviewQuery()` instead of relying on any SDK helper that touches `window`.
   4. Pin one delivery method for the SDK. Mixing an npm install with an ESM/CDN `<script type="module">` import of a different version produces version-specific behaviour differences (for example the Edit button appearing after a CDN bump).
   5. Read the SDK release notes before a major bump rather than the setup docs alone.
@@ -117,7 +118,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### environment-base-url-misconfigured-or-missing-for-a-locale
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wrong path or the site root; a specific locale cannot be previewed at all while others work; the preview pane keeps showing the previous environment's URL after switching.
 - **frameworks**: framework-agnostic (stack configuration)
 - **rendering_modes**: any
@@ -133,27 +134,27 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### edit-button-rendered-outside-a-live-preview-session
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or the `#cslp-tooltip` button element is injected into `document.body` on production even when not visible (usually caught in an accessibility audit). Sometimes intermittent, correlating with client-side route changes rather than fresh page loads.
 - **frameworks**: Next.js (App Router especially), React
 - **rendering_modes**: CSR, SSR
-- **root_cause**: With `editButton.enable: true`, the SDK gates the button on `enable` + `inIframe()` + the `cslp-buttons` query parameter. It never checks the `live_preview` hash or any active-session signal, so a normally loaded page with the SDK initialized renders the button by design. Teams that gate `init()` on a server-read hash also get bitten by App Router soft navigation, which does not re-run that server-side gate while the SDK's button instance persists across route changes.
+- **root_cause**: With `editButton.enable: true` and no `exclude`, the SDK renders the button on any page where it is initialized, inside the iframe or not. It never checks the `live_preview` hash or any session signal. `inIframe()` only matters when `exclude` is set, and a `?cslp-buttons=` query parameter overrides `exclude` unless `includeByQueryParameter: false`. Teams that gate `init()` on a server-read hash also get bitten by App Router soft navigation, which does not re-run that server-side gate while the SDK's button instance persists across route changes.
 - **fix**:
-  1. Add `editButton: { enable: true, exclude: ['outsideLivePreviewPortal'] }`. Outside the iframe `inIframe()` is false, so the button will not render, while Live Preview inside the pane keeps working.
-  2. If Live Preview is not used on production at all, strip it from the production build: `cleanCslpOnProduction: true` removes `data-cslp` from the DOM, and the `PURGE_PREVIEW_SDK=true` build flag no-ops the SDK entirely.
+  1. Add `editButton: { enable: true, exclude: ['outsideLivePreviewPortal'], includeByQueryParameter: false }`. Outside the iframe the button no longer renders, a query parameter cannot bring it back, and Live Preview inside the pane keeps working.
+  2. If Live Preview is not used on production at all, do not initialize it there: `enable: false` (with the default `cleanCslpOnProduction: true`, which then strips `data-cslp`), or the `PURGE_PREVIEW_SDK=true` build flag, which no-ops the SDK entirely.
   3. Do not rely on a server-side hash check alone in an App Router app; soft navigation will not re-evaluate it.
-- **verification**: Load the production URL in a normal tab with DevTools open. `document.getElementById('cslp-tooltip')` should be absent, and no `data-cslp` attributes should be present if `cleanCslpOnProduction` is set.
+- **verification**: Load the production URL in a normal tab with DevTools open. `document.getElementById('cslp-tooltip')` should be absent, and no `data-cslp` attributes should be present if the SDK runs with `enable: false`.
 
 ---
 
 ### cors-blocked-on-preview-api-requests
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: `Access to fetch at 'https://<region>-rest-preview.contentstack.com/v3/...' from origin '<site origin>' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource`, frequently alongside a `401 (Unauthorized)` on the same request. Works on localhost, fails on the deployed dev/staging host.
 - **frameworks**: Gatsby, Angular, Next.js, React
 - **rendering_modes**: CSR mainly
 - **root_cause**: Two distinct problems that surface as one console message. (1) The site's own Content Security Policy (`connect-src` / `default-src`) does not allow calls to Contentstack hosts, which most frameworks restrict by default in production but not in local dev. (2) The preview request is genuinely rejected (bad or wrong-type token), and the error response carries no CORS headers, so the browser reports it as a CORS failure instead of a 401. There is no per-stack "CORS allowlist" on the Contentstack side to add origins to.
 - **fix**:
-  1. Widen the site's CSP to the whole Contentstack domain rather than individual hosts. Listing only `app.contentstack.com` and `rest-preview.contentstack.com` has repeatedly been insufficient; `https://*.contentstack.com` (and `https://*.contentstack.io` where delivery/asset hosts are used) is what worked.
+  1. Allow every Contentstack host the page calls in the site's `connect-src`: the region's delivery, preview, GraphQL and asset hosts as well as the app host. Listing only the app and REST preview hosts usually misses one. `https://*.contentstack.com https://*.contentstack.io` is the simple form when listing hosts individually keeps failing.
   2. Fix the 401 separately: confirm you are sending a valid **Preview Token** (not a Delivery Token, not a Management Token) in the `preview_token` header, and regenerate it if in doubt. Resolve the CSP first, or the server error stays masked.
   3. Recheck env vars after a stack migration or API key change — a stale API key produces the same 401-behind-CORS shape.
 - **verification**: `curl` the same preview URL with the same headers from a terminal. A 200 proves the token is valid and the remaining problem is browser-side CSP. In the browser, the request should complete with `Access-Control-Allow-Origin` present.
@@ -161,7 +162,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### ssr-stack-instance-shared-or-duplicated
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Two opposite failures from the same mistake. **(A) Hash never arrives:** `init()` succeeds and `ContentstackLivePreview.hash` is populated on the client, but server-rendered pages still return published content. Deterministic, and only the author notices. **(B) Preview state leaks out:** intermittent, user-dependent wrong content, and the **production** site failing with `The Live Preview tracker is invalid or no longer exists. Create a new tracker to continue.` (error_code 382) or `The requested tracker was created for the 'dev' branch. Access using the 'main' branch is not allowed.`; preview stalling after a while; `TypeError: Cannot read properties of undefined (reading 'uid')` after idle hours in production; two editors seeing each other's content; personalization on the public site stopping resolving per visitor because a cached preview render is being served instead. This one reaches real visitors.
 - **frameworks**: Next.js (App Router and Pages Router), Express/Node, Nuxt
 - **rendering_modes**: SSR | edge
@@ -179,7 +180,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### nextjs-app-router-init-must-run-in-a-client-component
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit tags render but do nothing, or nothing at all happens when the entry is edited. The same code works in a Pages Router project.
 - **frameworks**: Next.js App Router
 - **rendering_modes**: SSR, CSR
@@ -203,7 +204,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### legacy-management-token-setup-not-migrated-to-preview-token
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: "Preview Service Not Enabled" shows in the preview panel on a setup that otherwise works. Or a setup copied from older docs / an older starter app passes a `management_token` to `live_preview` and fails with 401/422 after tokens were rotated.
 - **frameworks**: Next.js, Gatsby, React, framework-agnostic
 - **rendering_modes**: any
@@ -212,13 +213,13 @@ contract tells you which section to read; this file tells you what to do.
   1. Generate a Preview Token on the Delivery Token you already use.
   2. Replace `live_preview.management_token` with `live_preview.preview_token` and point `live_preview.host` at the region's `*-rest-preview.contentstack.com`.
   3. Update any framework source plugin to a version whose build output actually reads `preview_token` (some releases had source and build output disagreeing).
-  4. Remove the Management Token from client-side code entirely. Stack API Key, Delivery Token, and Preview Token are read-only and safe to ship to the browser; a Management Token has write access and is not.
+  4. Remove the Management Token from client-side code entirely; it has write access. The Stack API Key, Delivery Token and Preview Token are read-only and acceptable client-side, but still treat them as credentials: do not paste them into tickets or logs.
 - **verification**: No Management Token appears in any client bundle or preview request; the "Preview Service Not Enabled" card is gone and the Onboarding Check reaches Setup Complete.
 
 ---
 
 ### branch-or-alias-mismatch-between-app-token-and-entry
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Preview opens for pages that already exist on the main branch but never shows updates, and any page that exists only on the working branch 404s. Or: `error_code: 901, "Access denied. You have insufficient permissions to perform operation on this branch"`.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: any
@@ -232,7 +233,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### wrong-region-hosts-in-sdk-and-preview-config
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Live Preview never activates or the preview panel reports the service is not enabled, even though the stack settings look correct. Requests in the network tab go to the default North America hosts while the stack lives in another region.
 - **frameworks**: Next.js, Angular, React
 - **rendering_modes**: any
@@ -243,18 +244,18 @@ contract tells you which section to read; this file tells you what to do.
      - preview: `rest-preview.contentstack.com` → e.g. `eu-rest-preview.contentstack.com`, `azure-na-rest-preview.contentstack.com`, `gcp-eu-rest-preview.contentstack.com`
      - GraphQL preview: `graphql-preview.contentstack.com` → the region-prefixed equivalent
      - app host (`clientUrlParams.host`): `app.contentstack.com` → e.g. `eu-app.contentstack.com`, `gcp-na-app.contentstack.com`
-  2. Use the SDK's `region` option where available rather than hand-writing hosts, and make sure a hardcoded `host` does not override it.
+  2. On the Delivery SDK, use its `region` option rather than hand-writing hosts, and make sure a hardcoded `host` does not override it. Live Preview Utils has no `region` option: set `clientUrlParams.host` to the region's app host by hand.
   3. Re-check every host after a stack migration; the API key changes too.
 - **verification**: In DevTools → Network, every Contentstack request goes to a host carrying the correct region prefix, and returns 200.
 
 ---
 
 ### locale-defaults-to-en-us-in-init
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Start Editing / the Edit button opens Visual Editor or the entry editor with `locale=en-us` even though the stack has no `en-us` language, producing a 404 or a "Language not found" toast. Works on one deployment and not another with identical code.
 - **frameworks**: React, Angular, framework-agnostic
 - **rendering_modes**: any
-- **root_cause**: When `stackDetails.locale` is not set in `init()`, the SDK tries to infer the locale by finding an element with `data-cslp` in the DOM and reading the locale out of it. If no tagged element is present at that moment, it falls back to `en-us`. That fallback is invalid on stacks whose master language is something else, and it explains why the same code behaves differently on two deployments (one happens to have tagged content in the DOM, the other does not).
+- **root_cause**: The SDK picks the locale for the editor URL in this order: a valid `data-cslp` tag found in the DOM, then `stackDetails.locale` from `init()`, then the default `en-us`. With no tagged element in the DOM at that moment and no configured locale, it lands on `en-us`, which is invalid on stacks whose master language is something else. That is why the same code behaves differently on two deployments: one happens to have tagged content in the DOM, the other does not.
 - **fix**:
   1. Set the locale explicitly:
      `ContentstackLivePreview.init({ stackDetails: { apiKey, environment, locale: '<your-locale>' } })`.
@@ -265,11 +266,11 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### start-editing-button-cannot-be-hidden-in-editor-mode
-- **bucket**: setup
-- **symptom**: The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `mode: "builder"` is set, including production. Setting `editButton.enable: false` removes the per-field edit tags but not this button.
+- **bucket**: integration
+- **symptom**: The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `mode: "builder"` is set, including production. Setting `editButton.enable: false` removes the per-field Edit button but not this one.
 - **frameworks**: React, Next.js, Gatsby
 - **rendering_modes**: any
-- **root_cause**: "Start Editing" is a separate control from the per-field edit tags. It is enabled implicitly by `mode: "builder"` and has its own config key, which was not obvious from the setup docs. `editButton` governs only the field-level tags.
+- **root_cause**: "Start Editing" is a separate control from the per-field Edit button. It is enabled implicitly by `mode: "builder"` and has its own config key. `editButton` governs only the per-field button.
 - **fix**:
   1. Disable it explicitly:
      ```js
@@ -278,17 +279,17 @@ contract tells you which section to read; this file tells you what to do.
        editInVisualBuilderButton: { enable: false },
      });
      ```
-  2. Better for production builds: do not initialize the SDK there at all, or use `PURGE_PREVIEW_SDK=true` / `cleanCslpOnProduction: true`.
+  2. Better for production builds: do not initialize the SDK there at all (`enable: false`), or use `PURGE_PREVIEW_SDK=true`.
 - **verification**: Load the production URL; no floating Start Editing button. Load the preview environment; the button is present when you want it.
 
 ---
 
 ### onboarding-check-card-not-visible-or-appears-unexpectedly
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days later on its own. Conversely, other teams never see the status card at all when they want to diagnose a failing integration.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: any
-- **root_cause**: Each product keeps its own stack setting, and they do not agree on what "unset" means. Timeline treats an unset value as visible. Live Preview treats an unset value as hidden. Visual Editor treats an unset value as visible, and also treats a stack with no `visual_builder` settings at all as visible. Meanwhile the Visual Experience settings screen renders the toggle as on whenever the value is unset, so a stack that never explicitly saved the setting can show the toggle on while Live Preview behaves as though it is off. Separately, the checks run asynchronously with a timeout, so the card can appear briefly on a correctly configured site whose first preview fetch is slow, then clear itself once the request lands.
+- **root_cause**: Each product keeps its own stack setting, and they do not agree on what "unset" means. Timeline treats an unset value as visible. Live Preview treats an unset value as hidden. Visual Editor treats a stack with no `visual_builder` settings at all as visible, but a stack that has `visual_builder` settings without this key as hidden. Meanwhile the Visual Experience settings screen renders the toggle as on whenever the value is unset, so a stack that never explicitly saved the setting can show the toggle on while Live Preview behaves as though it is off. Separately, the checks run asynchronously with a timeout, so the card can appear briefly on a correctly configured site whose first preview fetch is slow, then clear itself once the request lands.
 - **fix**:
   1. Open Settings → Visual Experience and click Save without changing anything. Saving once stores the state shown for Live Preview, Visual Editor and Timeline together, and a toggle that was never saved still shows as on, so one save records an explicit on for all three. That removes the unset ambiguity and makes all three agree.
   2. Check the setting for the product actually being used. Live Preview, Visual Editor and Timeline each have their own, under Settings → Visual Experience.
@@ -300,7 +301,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### visual-experience-navigation-missing-for-the-stack
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: The "Visual Experience" / builder-mode option does not appear in the Contentstack navigation at all, so the team cannot open the builder and assumes their integration is wrong.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: any
@@ -313,7 +314,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### third-party-cookies-blocked-inside-the-preview-iframe
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: The site renders in the preview pane but behaves as if logged out, or without personalization, locale or currency preferences. Anything driven by the site's own cookies is lost.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: any
@@ -328,7 +329,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### chrome-local-network-access-blocks-preview-of-localhost
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: A previously working local Live Preview setup breaks with
   `Access to fetch at 'http://localhost:5173/' from origin 'https://<region>-app.contentstack.com' has been blocked by CORS policy: Permission was denied for this request to access the 'unknown' address space`.
   Chrome only; Safari unaffected. Downgrading the SDK does not help.
@@ -343,7 +344,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### cslp-tags-contain-the-literal-string-undefined
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: `data-cslp` attributes in the DOM contain `undefined` where the entry uid should be. Inline editing does not work and edit mapping silently fails on those elements.
 - **frameworks**: Next.js
 - **rendering_modes**: SSR
@@ -362,7 +363,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### ssg-preview-needs-csr-mode
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Live Preview on a statically generated site is unreliable or simply shows build-time content: blank or black screens, flicker, an auth prompt on reload, or edits that never appear no matter what. The hash is on the URL and never reaches the fetch.
 - **frameworks**: Next.js, Gatsby, Astro, framework-agnostic
 - **rendering_modes**: SSG/ISR
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
index 7262d4c..c80ccb7 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -1,9 +1,9 @@
 # Preview runtime FAQ
 
 Content correctness once the integration is confirmed wired up: staleness, lost preview context,
-caching, locale, variants, and Timeline.
+caching, locale, variants and roles. Timeline is in `faq-timeline.md`.
 
-If the integration itself is not confirmed, work the four setup contracts in SKILL.md first. A
+If the integration itself is not confirmed, work the four contracts in SKILL.md first. A
 fetch that never switched to the Preview Service produces most of the symptoms below and none of
 the fixes here will help.
 
@@ -12,15 +12,14 @@ the fixes here will help.
 - **symptom**: Selecting a variant (or switching audience in Audience Preview) in Visual Experience keeps rendering the base entry. The side form shows the correct variant content, but the canvas does not. A manual browser refresh sometimes fixes it. Clicking into the element shows the correct variant value while the rendered page does not.
 - **frameworks**: Next.js, React, framework-agnostic
 - **rendering_modes**: CSR | SSR
-- **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-setup.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the Contentstack UI loads the entry on its own, independently of your site's fetch. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
+- **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-integration.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the Contentstack UI loads the entry on its own, independently of your site's fetch. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
 - **fix**:
   1. First confirm the preview path works at all: change a plain text field and check the canvas updates. If it does not, fix that first — the variant symptom is downstream of it.
   2. Do **not** pass the variant yourself. The Preview Service resolves it from the UI selection; no `variant` query param, no `Entries.variants()`. Do pass `include_applied_variants=true` as a query parameter on the content request (`.addParams({ include_applied_variants: "true" })`), or the variant renders but Highlight Variant and audience mode have nothing to key on; see `highlight-variant-or-audience-mode-does-nothing` in `faq-visual-editor.md`.
   3. Confirm the Preview Service is actually configured: a preview token on the Stack's `live_preview` config, and content requests going to a `*-preview.contentstack.com` host during the session. This is the most common cause.
   4. Register `ContentstackLivePreview.onEntryChange(fetchFn)` and make `fetchFn` re-query through the preview-configured Stack. This is the second most common cause. Confirm `ssr` matches the route's actual rendering mode while you are there.
-  5. Check the cache layer. If preview responses are cached under a key that ignores the `live_preview` hash, the base content is served no matter what. Bypass caching entirely for preview requests.
+  5. Check the cache layer. A cache on the preview path serves the base content, or one variant's response for another, no matter what the UI selects. Do not key it by hash or variant: bypass it for preview requests entirely.
   6. Variants on referenced entries: the referenced content type must be linked to the variant group for its variant content to resolve in preview, and that reference field must be in the `includeReference()` / `referenceFieldPath` list used for the page.
-  7. If a cache sits in front, it must not serve one variant's response for another. Do not key it by variant — bypass it for preview requests entirely.
 - **verification**: Switch variants; the network tab should show a fresh request to the preview host, and the rendered canvas should change without a manual refresh.
 
 ---
@@ -44,7 +43,7 @@ the fixes here will help.
 - **symptom**: A page that renders fine in the entry editor and on the live site comes back blank in Visual Experience for a non-master locale. Or preview opens with a locale that does not exist in the stack (e.g. `en-us` on a stack that only has `fr-fr`) and 404s. Or one modular block referencing another entry renders empty in an unlocalized locale.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: CSR | SSR | SSG/ISR
-- **root_cause**: The Delivery API falls back to the master locale automatically; the Preview service does not. If the request to the preview service omits `include_fallback=true` (REST) or `fallback_locale: true` (GraphQL), an unlocalized entry — including an unlocalized *referenced* entry inside a modular block — returns nothing and the page renders empty. Separately, Visual Experience needs a base URL configured per locale in the environment; a locale with no base URL cannot load an iframe, and the preview URL falls back to a default locale that may not exist in the stack.
+- **root_cause**: If the request to the preview service omits `include_fallback=true` (REST) or `fallback_locale: true` (GraphQL), an unlocalized entry — including an unlocalized *referenced* entry inside a modular block — returns nothing and the page renders empty. Separately, Visual Experience needs a base URL configured per locale in the environment; a locale with no base URL cannot load an iframe, and the preview URL falls back to a default locale that may not exist in the stack.
 - **fix**:
   1. Add `include_fallback=true` (REST) / `fallback_locale: true` (GraphQL) to every preview fetch, and to nested reference includes.
   2. Configure a base URL for every locale you want to author in, under the environment's Live Preview settings. A missing URL for one locale can disable the whole environment selector for that locale.
@@ -77,8 +76,8 @@ the fixes here will help.
 - **root_cause**: The SDK keeps the preview params on the URL by one mechanism only: a click listener that finds the clicked `<a>` and rewrites its `href` to include `live_preview` before the browser follows it. It does not patch the History API, so any navigation that does not go through a real anchor href — `router.push()`, `useNavigate()`, `history.pushState` — carries no params and the preview context is lost. Framework `<Link>` components are the common trap: they render an `<a>`, so the href is rewritten, but the router calls `preventDefault()` and pushes its own URL, so the rewrite is never used. Separately, if the app's routing does not map 1:1 to the entry's `url` field, the preview URL that Contentstack constructs (environment base URL + entry `url`) points at a route that does not exist. App Router soft navigation also does not re-run server-side hash gating.
 - **fix**:
   1. Preserve `live_preview`, `content_type_uid`, `entry_uid`, and `preview_timestamp` in the URL across programmatic navigations, or trigger a hard navigation inside the preview.
-  2. For routes that cannot be derived from the entry `url` field, enable **Custom Preview URLs** and then call `setPageContext({ entryUid, contentTypeUid })` on each page (Live Preview Utils v4.4.4+). The call only takes effect when Custom Preview URLs is configured and enabled on the plan; otherwise it is silently ignored and the editor keeps resolving by URL.
-  3. For non-trivial URL structures, configure **Custom Preview URLs** in Settings → Visual Experience → Preview URL, following [the docs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls) for patterns and Base URL aliases.
+  2. For routes that cannot be derived from the entry `url` field, enable **Custom Preview URLs** and then call `setPageContext({ entryUid, contentTypeUid })` on each page (Live Preview Utils v4.4.4+). The call only takes effect when Custom Preview URLs is enabled for the stack; otherwise it is silently ignored and the editor keeps resolving by URL.
+  3. For non-trivial URL structures, configure **Custom Preview URLs** in Settings → Visual Experience → Preview URL, following [the docs](https://www.contentstack.com/docs/headless-cms/custom-preview-urls) for patterns and Base URL aliases.
   4. Confirm every route allows iframe embedding, not just the root — an `X-Frame-Options` or CSP `frame-ancestors` header, or a hard redirect to a different host, on a deep route will break navigation inside the panel.
 - **verification**: Click through the site's own nav inside the preview panel; the URL keeps its preview params and edits still apply on the new page.
 
@@ -99,20 +98,6 @@ the fixes here will help.
 
 ---
 
-### stale-first-fetch-when-editing-a-referenced-entry
-- **bucket**: preview-runtime
-- **symptom**: The very first `onEntryChange` fetch after opening the preview returns published data even though the entry was already modified. Every subsequent keystroke-triggered fetch returns the correct draft data.
-- **frameworks**: Next.js (Pages Router), GraphQL
-- **rendering_modes**: CSR (on an SSG/ISR site)
-- **root_cause**: Service-side. It reproduced only when the entry being edited is a **referenced** entry and the site fetches the **parent** entry through a reference connection — the first preview response did not yet include the referenced entry's draft state.
-- **fix**:
-  1. Confirm the shape: are you editing a child/referenced entry while the page queries the parent through a reference connection? If so this is the known case and was fixed service-side.
-  2. Confirm the first request really is going to the preview host (the Onboarding Check reports this too) before assuming this issue — a first request to the delivery host looks identical from the outside.
-  3. Update to a current Live Preview Utils version.
-- **verification**: Modify a referenced entry, open the preview fresh, and confirm the draft value is present on the first render with no keystroke.
-
----
-
 ### legacy-management-token-preview-breaks-on-references
 - **bucket**: preview-runtime
 - **symptom**: Live Preview works for top-level fields but an edit to an entry that is referenced inside another entry does not update. Setup status reports "Preview Service Not Enabled" even though Live Preview is on for the stack. Migrating to preview tokens returns `401 Unauthorized` on the first attempt.
@@ -123,7 +108,7 @@ the fixes here will help.
   1. Migrate to the Preview Service: generate a Preview Token tied to your Delivery Token and replace `management_token` with `preview_token` in `live_preview`, and point `host` at the region's preview host.
   2. Remove the CMA host override and any `setHost` calls left over from the old setup.
   3. If preview requests 401 after the swap, confirm the Preview Token is tied to the Delivery Token you are actually using and that the token is sent as the `preview_token` header (not `authorization`).
-  4. Minimum versions for Visual Editor: Live Preview Utils v3.0+, Delivery SDK v3.20.3+ (v4.4.4+ of Live Preview Utils if you use `setPageContext`).
+  4. Minimum versions for Visual Editor: Live Preview Utils v3.0+, legacy `contentstack` JavaScript SDK v3.20.3+ (v4.4.4+ of Live Preview Utils if you use `setPageContext`).
 - **verification**: Setup status stops reporting "Preview Service Not Enabled"; edits to a referenced entry appear in the parent page's preview.
 
 ---
@@ -141,7 +126,7 @@ the fixes here will help.
   4. Grant read on the content type itself, not only on its entries. Granting entry access alone leaves the 422 in place.
   5. Do not work around it by granting broader edit rights. Read access on the environment and the content types is the correct fix.
   6. After changing the role, have the user sign out and back in before retesting. Role changes do not always apply to an existing session.
-  7. **Everyone** seeing "No environments available", not just one user, is a different problem: a missing Base URL — see `environment-base-url-misconfigured-or-missing-for-a-locale` in `faq-setup.md`.
+  7. **Everyone** seeing "No environments available", not just one user, is a different problem: a missing Base URL — see `environment-base-url-misconfigured-or-missing-for-a-locale` in `faq-integration.md`.
 - **verification**: The restricted user's preview renders without gaps or errors, showing graceful fallbacks where access is limited; no `422 Content Type ... not found` in their preview requests. The environment dropdown lists the preview environment for their role.
 
 ---
@@ -154,7 +139,7 @@ the fixes here will help.
 - **root_cause**: The preview renders inside a cross-origin iframe. Third-party scripts whose targeting or delivery logic depends on the top-level host, referrer, or first-party storage see the iframe context instead of the real site and behave differently. Not a Contentstack request failure: the calls fire and fail at the third party's delivery stage. This is inherent to rendering the site in an iframe and there is no product-side fix for it.
 - **fix**:
   1. Where the third party allows it, add the Contentstack app origin to its allowed-referrer or allowed-domain configuration.
-  2. Use **Open in New Tab**, which renders the preview outside the iframe so the third party sees the real host. This is an existing feature, not something to request.
+  2. Use **Open in New Tab**, which renders the preview outside the iframe so the third party sees the real host. It is plan-gated; if it is missing, see `contact-support.md`.
   3. Where neither is possible, exclude those third-party scripts when the preview parameters are present, so authors preview content without them rather than with a broken version of them.
 - **verification**: Use Open in New Tab rather than the preview panel and confirm the third-party content renders. That difference confirms the iframe context is the trigger.
 
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
index b5b5a83..7299acc 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
@@ -30,7 +30,7 @@ already good.
 - **rendering_modes**: any
 - **root_cause**: Highlight Differences works by matching changed fields to DOM elements through their `data-cslp` attributes. It needs live edit tags enabled on the site **and** a `data-cslp` physically present on the element that renders the changed field. Where the tag coverage is thin, or the specific field that changed carries no tag, the diff has nothing to attach the highlight to and the comparison looks empty even though both versions rendered.
 - **fix**:
-  1. Confirm live edit tags are enabled and rendered — see `edit-tags-not-generated-or-not-spread` in `faq-setup.md`.
+  1. Confirm live edit tags are enabled and rendered — see `edit-tags-not-generated-or-not-spread` in `faq-integration.md`.
   2. In the Timeline iframe, run
      `[...document.querySelectorAll('[data-cslp]')].map(el => ({tag: el.tagName, cslp: el.getAttribute('data-cslp')}))`
      and confirm the **specific field you changed** appears in that list.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
index 19212bc..083688a 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -5,18 +5,18 @@ affordance, and what the canvas does with the site's own clicks. Live Preview re
 the canvas misbehaves points here.
 
 If nothing on the canvas is editable at all, start with `edit-tags-not-generated-or-not-spread` in
-`faq-setup.md` — that is setup contract 2, and everything here assumes it is met.
+`faq-integration.md` — that is contract 2, and everything here assumes it is met.
 
 ### cslp-not-rebased-to-referenced-entry
 - **bucket**: visual-editor
 - **symptom**: Edit tags on fields that come from a **referenced** entry do nothing when clicked. Tags on the page's own fields work. Console may show `{code: 'NO_REQUEST_LISTENER_FOUND', message: 'contentstack-adv-post-message: No request listener found for event "scroll"'}`, but that message is routine and appears on healthy setups too — treat it as incidental, not as the identifying evidence. Diagnose from the tags themselves.
 - **frameworks**: React, Next.js, framework-agnostic
 - **rendering_modes**: CSR, SSR
-- **root_cause**: `addEditableTags()` rebases a tag onto the referenced entry only when the resolved reference object carries both `uid` and `_content_type_uid`. Without them the tag stays anchored to the parent entry (`product.<parent_entry_uid>.<locale>.<reference_field>.<index>.<field>`), so there is no entry to navigate to. Common causes: references fetched separately and merged by hand (which drops those keys), or a GraphQL query that omits `system`. Hardcoding `data-cslp` by hand is a related failure — the referenced entry's uid and content type uid are not the ones being edited.
+- **root_cause**: `addEditableTags()` rebases a tag onto the referenced entry only when the resolved reference object carries both `uid` and `_content_type_uid`. Without them the tag stays anchored to the parent entry (`product.<parent_entry_uid>.<locale>.<reference_field>.<index>.<field>`), so there is no entry to navigate to. Common causes: references fetched separately and merged by hand (which drops those keys), or any GraphQL response, where those keys sit under `system` instead of at the top level. Hardcoding `data-cslp` by hand is a related failure — the referenced entry's uid and content type uid are not the ones being edited.
 - **fix**:
   1. Inspect the referenced field in DevTools. Working shape is `<referenced_ct_uid>.<referenced_entry_uid>.<locale>.<field>`. If you see the parent entry's uid, this is the bug.
   2. REST / Delivery SDK: resolve references with `includeReference()` / `include[]` so resolved objects keep `uid` and `_content_type_uid`.
-  3. GraphQL: request `system { uid, content_type_uid, locale }` on every reference.
+  3. GraphQL: request `system { uid, content_type_uid, locale }` on every reference, then normalise each node so `uid` and `_content_type_uid` sit at its top level. See `graphql-connection-wrappers-break-cslp`.
   4. If references are fetched separately, either preserve those two keys when merging, or call `addEditableTags()` on each referenced entry with its own content type uid.
   5. Never hardcode `data-cslp` — always read the value the SDK put on the entry object.
 - **verification**: Click the edit tag on a referenced field; the CMS should open the referenced entry's editor and scroll to that field.
@@ -76,10 +76,11 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 - **rendering_modes**: any
 - **root_cause**: `addEditableTags()` walks the response object and bakes every traversed layer into the `data-cslp` path. A GraphQL response nests values under `Connection -> edges -> node`, so those wrapper layers end up in the path and no field path resolves against the entry. This is by design — the SDK has no knowledge of GraphQL response shapes — so it needs a normalizer on the application side.
 - **fix**:
-  1. Request `system { uid, content_type_uid }` on every node the page renders, including referenced entries. Without those the tags cannot be attributed to an entry at all.
+  1. Request `system { uid, content_type_uid, locale }` on every node the page renders, including referenced entries. Without those the tags cannot be attributed to an entry at all.
   2. Flatten the response before tagging: collapse each `Connection -> edges -> node` into the plain object or array the REST shape would have produced, so a reference is an array of entries and a field is a direct property.
-  3. Call `addEditableTags()` on the flattened object, never on the raw GraphQL response.
-  4. Confirm the resulting `data-cslp` values contain no `edges` or `node` segments.
+  3. On every entry and referenced entry, copy `system.uid` to `uid` and `system.content_type_uid` to `_content_type_uid`. `addEditableTags()` reads only the top-level keys, so without this references are never rebased and their tags point at the parent entry.
+  4. Call `addEditableTags()` on the normalised object, never on the raw GraphQL response.
+  5. Confirm the resulting `data-cslp` values contain no `edges` or `node` segments.
 - **verification**: Inspect a tagged element. Its `data-cslp` reads `<content_type_uid>.<entry_uid>.<locale>.<field_path>` with no connection segments, and clicking it focuses the field in the form panel.
 
 ---
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md b/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
index 5ca0f83..16f028e 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -9,11 +9,14 @@ needs to be previewable.
 
 ## Next.js, App Router
 
-The most common setup mistake in this framework, and the one that produces "the SDK is installed
-and nothing happens" with no error anywhere.
+The most common mistake in this framework, and the one that produces "the SDK is installed and
+nothing happens" with no error in the browser. On the server, `init()` logs "The SDK is not
+initialized in the browser." and returns.
 
 `init()` cannot run in a server component. Put it in a client component and import that into the
-layout so it runs once per app load:
+layout so it runs once per app load. The options differ by mode.
+
+CSR (content fetched in the browser):
 
 ```tsx
 "use client";
@@ -35,6 +38,35 @@ export function LivePreviewInit() {
 }
 ```
 
+SSR (server components fetch at request time). `init()` takes no `stackSdk`; the server applies
+the hash per request instead:
+
+```tsx
+// LivePreviewInit.tsx
+"use client";
+import { useEffect } from "react";
+import ContentstackLivePreview from "@contentstack/live-preview-utils";
+
+export function LivePreviewInit() {
+  useEffect(() => {
+    ContentstackLivePreview.init({
+      ssr: true,
+      mode: "builder",
+      stackDetails: { apiKey: API_KEY, environment: ENVIRONMENT },
+    });
+  }, []);
+  return null;
+}
+
+// app/[...slug]/page.tsx
+export default async function Page({ searchParams }) {
+  const params = await searchParams; // a Promise since Next.js 15
+  const stack = createStack();       // new Delivery SDK instance per request
+  stack.livePreviewQuery(params);    // reads live_preview, content_type_uid, entry_uid, preview_timestamp
+  // fetch through `stack` ...
+}
+```
+
 Watch for three things here:
 
 - Soft navigation does not re-run server-side gating, and the SDK's module-level state persists
@@ -42,8 +74,9 @@ Watch for three things here:
   will appear on production pages after a client-side navigation.
 - App Router metadata is produced by `generateMetadata()`, which has no hook for injecting window
   globals. If you are using the `window.__CS_PAGE_CONTEXT__` route for page context, set it from a
-  client component, or use the `<meta>` tag form instead. Page context is only honoured when
-  **Custom Preview URLs** is configured and enabled on the plan; without that it is silently ignored.
+  client component, or use the `<meta>` tag form instead. The SDK always sends page context, but
+  Visual Editor uses it only when **Custom Preview URLs** is enabled for the stack; otherwise it is
+  silently ignored.
 - Reading `searchParams` opts the route out of static rendering. Expect that when you add the SSR
   hash path.
 
@@ -93,8 +126,8 @@ route.
 
 Init in a client-only plugin. For page context, `useHead()` is the natural place to emit the
 `<meta>` tags, since Nuxt produces head tags natively and has no built-in hook for injecting window
-globals. As everywhere, page context only takes effect with **Custom Preview URLs** configured and
-enabled on the plan.
+globals. As everywhere, page context only takes effect when **Custom Preview URLs** is enabled for
+the stack.
 
 The Nuxt CSR and SSR stories differ on whether Visual Editor overlays appear, and Contentstack's
 own material is inconsistent on this point. Verify against the actual app before promising overlay
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index 5585428..75dfeb6 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -1,165 +1,131 @@
 # The Onboarding Check
 
-Every visual experience product ships a setup check that runs automatically when its panel opens.
-There are **three** of them, and they differ in both gates and shape. Live Preview shows one card
-carrying the first failing gate. Visual Editor shows all six of its items, each with its own status,
-but stops evaluating at the first one that fails. Timeline shows a small status card while it checks,
-then a full-pane "Set Up Timeline" overlay listing three items with a status each once one fails.
-Confirm which product the user is in before reading anything below. It is the highest-yield thing to
-ask about, because it has already run the diagnosis the user is asking you to do.
+Each Visual Experience product runs its own setup check when its panel opens. There are **three**,
+with different gates, different minimum SDK versions, and different surfaces. Confirm the product
+before reading anything below.
 
-**Always ask for a screenshot of the check before asking anything else.** The failing step name
-localises the problem to one gate, and because of how the check is structured, it also tells you
-everything that already passed.
+**Ask for a screenshot before anything else.** The first failing item localises the problem to one
+gate and proves every earlier gate passed.
 
-## The property that makes all three checks powerful
+## The chain property
 
-All three evaluate their gates as an ordered chain that stops at the first failure. They differ only
-in how much they show you. Live Preview renders just the failing step. Timeline and Visual Editor
-render their full item list with a status each, but the items below the first incomplete one were
-never evaluated, so they carry no information. **In every product, read the first failing item and
-ignore what is under it.**
+All three checks evaluate their gates in order and stop at the first failure. Read the **first**
+failing item. Items after it never ran and carry no information.
 
-So a card reading "Preview Service Not Enabled" is not just one fact. It proves the website loaded
-in the frame, the SDK initialised, and the SDK version is supported. Three contracts are already
-ruled out. Do not re-ask about them.
+So "Preview Service Not Enabled" proves the site was reachable, the SDK initialised, and its version
+is supported. Do not re-ask about those. The inverse holds too: a check stuck on its first gate says
+nothing about the SDK, because the SDK gate never ran.
 
-The inverse also holds. A card stuck on the first gate tells you nothing about any later gate,
-because none of them ran. Do not theorise about the SDK when the site never loaded.
+## Live Preview
 
-## Live Preview and Visual Editor
-
-Five gates, in this order.
+One card, showing the gate under test while checking and the first failure when one fails.
 
 | # | Card while checking | Card on failure | What the failure means |
 |---|---|---|---|
-| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, a non-localhost `http://` host (mixed content; allow insecure content for the app origin) or an untrusted certificate (open the URL in its own tab, accept the warning, reload the pane), or the browser blocking localhost. Nothing after this ran. |
-| 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | The frame loaded but no init handshake arrived. `init()` is in server-only code, the enable flag did not parse as a boolean in the deployed build, the init module was tree-shaken out, or init runs after the check window. |
-| 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake arrived from a version below the supported minimum. Upgrade Live Preview Utils. |
-| 4 | Verifying Preview Service | **Preview Service Not Enabled** | The SDK is fine and the site is fine, but content is not coming from the Preview Service. This is the fetch layer never switching host and headers, which is the most common failure of all. |
-| 5 | — | **Default Environment Not Set** | Everything works. The stack simply has no default preview environment, set in stack settings. |
+| 1 | Website Loading | **Could Not Connect to Website** | A `no-cors` `HEAD` request to the preview URL failed at the network level: a wrong or unreachable Base URL, DNS, connection refused, an untrusted certificate (open the URL in its own tab, accept the warning, reload the pane), a non-localhost `http://` host (mixed content), or the browser blocking localhost. Frame headers and auth screens do **not** fail this gate, because a `no-cors` request succeeds on any HTTP response. |
+| 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | No init handshake arrived within about 12 seconds. Either the frame rendered nothing (`X-Frame-Options`, CSP `frame-ancestors`, a password, auth or SSO screen) or the page loaded and `init()` never ran on the client: server-only placement, `enable` not truthy in the deployed build, the init module tree-shaken out, or init running late. |
+| 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake reported a version below 1.4.0, or an unparseable one. Upgrade Live Preview Utils. |
+| 4 | Verifying Preview Service | **Preview Service Not Enabled** | Site and SDK are fine, but content is not coming from the Preview Service. The fetch layer never switched host and headers. The most common failure. |
+| 5 | — | **Default Environment Not Set** | Integration fine. The stack has no default preview environment. |
 | — | — | **Setup Complete** | All gates passed. |
 
-The exact body text is worth quoting back to users, because they often paraphrase it into
-something ambiguous. Gate 1 reads "Ensure the website is live and accessible via Contentstack
+To tell the two gate-2 causes apart, look at the pane: blank or a browser error page means frame
+headers or an auth screen; the site visibly rendered means `init()`.
+
+Body text worth quoting back: gate 1 reads "Ensure the website is live and accessible via Contentstack
 origins." Gate 4 reads "Please enable the Preview Service for a seamless live preview experience."
 
 ## Visual Editor
 
-Visual Editor runs its own check, not Live Preview's. Six items, shown as a list with a status per
-item. Unlike Live Preview it shows the whole list, but evaluation still stops at the first item that
-fails, so a partially green list is the normal way it looks while something is wrong and only the
-**first** incomplete item is diagnostic. Item text as observed in the UI.
+Its own check, not Live Preview's. A small status card runs first, its header naming the gate under
+test: "Live Preview SDK", "Live Preview SDK Init Mode", "API Key / Preview Token", then "All Set!".
+If a gate is still incomplete 18 seconds after the last change, a full-pane **"Set Up Visual Editor"**
+overlay replaces it. If the environment gate fails, the overlay appears at once. Ask for the overlay
+screenshot.
+
+Overlay items, verbatim:
 
-| # | Item (card text) | Passes when |
+| # | Overlay item | Passes when |
 |---|---|---|
-| 1 | Configure environment | both sub-steps below pass |
-| 1a | Default Environment | the environment in the preview URL's parameters exists on the stack |
-| 1b | Base URL | that environment has a Base URL for the current locale, and its **origin matches the origin of the page being previewed**. A Base URL on a different host or scheme fails here even though the page loads |
-| 2 | Install SDK | Live Preview Utils major version is 3 or higher |
-| 3 | Verify Mode for Live Preview | `init()` was called with `mode: "builder"`. **`mode: "preview"` fails this gate.** Edit tags alone do not get you a canvas |
-| 4 | Preview Token | the site's content requests for the previewed page reach the Preview Service (the REST or GraphQL preview host) instead of the delivery CDN. The check looks for that a handful of times across roughly the first 18 seconds after the SDK's `init()` handshake arrives and items 1-3 pass, so a site that fetches only from the delivery CDN, or fetches nothing in that window, fails here |
-
-Two consequences worth stating:
-
-- **Visual Editor needs three things, not two.** Working Live Preview, edit tags, and `mode: "builder"`
-  in `init()`. The product table in SKILL.md says so; a customer who followed a Live Preview guide has
-  `mode: "preview"` and will fail item 3 with everything else green.
-- **Item 1b is origin-exact.** The Base URL must match the previewed page's scheme and host. A Base
-  URL of `https://www.example.com` with the site served at `https://example.com`, or `http` versus
-  `https`, fails the check while the frame still renders.
+| 1 | Configure the environment | both sub-checks pass |
+| 1a | Validate the Default Environment | the `environment` in the preview URL exists on the stack |
+| 1b | Validate the Base URL | that environment has a Base URL for the current locale, and its **origin equals the previewed page's origin** |
+| 2 | Install the Latest Live Preview SDK | Live Preview Utils major version is 3 or higher |
+| 3 | Verify Mode for Live Preview | `init()` was called with `mode: "builder"`. `mode: "preview"` fails here |
+| 4 | Validate the Preview Token / API Key | after items 1 to 3 pass and the handshake arrives, a content request reaches the REST or GraphQL Preview Service. Polled 5 times over about 18 seconds |
 
-## Timeline
+Two consequences:
+
+- **Visual Editor needs three things.** Working Live Preview, edit tags, and `mode: "builder"`. A setup
+  copied from a Live Preview guide has `mode: "preview"` and fails item 3 with everything else green.
+- **Item 1b is origin-exact.** `https://www.example.com` against a page on `https://example.com`, or
+  `http` against `https`, fails while the frame still renders.
 
-Timeline runs its own check with three items, not Live Preview's five or Visual Editor's six. Do not
-map any of them onto another table. It has two surfaces:
+## Timeline
 
-1. **A small status card** at the bottom of the pane while the check runs. Its header names the item
-   under test: "Default Environment", then "Live Preview SDK", then "Preview Token", then "All Set!".
-   When everything passes it shows All Set! and disappears about two seconds later.
-2. **A full-pane "Set Up Timeline" overlay** that replaces the card when an item fails. It lists all
-   three items under "Get Started", each with a filled or empty circle. This is the screenshot to ask
-   for.
+Its own check, three items. A small status card runs first ("Default Environment", "Live Preview
+SDK", "Preview Token", then "All Set!", which hides after about two seconds). If an item is still
+unchecked ten seconds after the last status change, or one second after when no environment resolves,
+a full-pane **"Set Up Timeline"** overlay lists the items under "Get Started", each with a filled or
+empty circle.
 
 | # | Overlay item | Passes when | Empty circle means |
 |---|---|---|---|
-| 1 | Configure the environment | an environment resolves for the session: the `environment` on the Timeline URL, falling back to the stack's default preview environment (`live_preview.default-env`) | no environment on the URL and no default preview environment in stack settings |
-| 2 | Install the latest Live Preview SDK | item 1 passed and the SDK's `init()` handshake reached Timeline with a major version of 2 or higher | `init()` never ran inside the frame, or the SDK is 1.x |
-| 3 | Generate and use Preview Token | item 2 passed and, by the end of the check's short window, at least one of the site's content requests (REST or GraphQL) has been served by the Preview Service | the site fetched from the delivery CDN, or fetched nothing in time |
+| 1 | Configure the environment | an environment resolves: `environment` on the Timeline URL, else the stack's default preview environment | none on the URL and no default set |
+| 2 | Install the latest Live Preview SDK | item 1 passed and the `init()` handshake reached Timeline with major version 2 or higher | `init()` never ran in the frame, or SDK 1.x |
+| 3 | Generate and use Preview Token | item 2 passed and a content request reached the Preview Service within about nine seconds | the site fetched from the delivery CDN, or fetched nothing in time |
 
-The items are chained: 2 is only evaluated after 1 passes, 3 only after 2. Read the **first** empty
-circle. The ones below it never ran and tell you nothing.
+A slow site can show item 3 empty on a correct setup. Have the user reopen the panel on a warm cache
+before believing it.
 
-**Timing.** The overlay appears ten seconds after the last status change if anything is still
-unchecked, or after one second when no environment resolves at all. Item 3 waits roughly nine seconds for
-the site's first Preview Service request. A site whose
-first preview request lands later than that shows item 3 empty on a correct setup. Have the user
-reopen the panel on a warm cache before believing it.
+"Configure" opens the stack's Live Preview settings page. The footer links to the Set Up Timeline
+documentation.
 
-**Links on the overlay.** "Configure" opens Settings → Live Preview for the stack. "Install" and
-"Preview Token" open help articles. The footer links to the Set Up Timeline documentation page.
+## Minimum SDK versions differ
 
-**Closing it.** The X on the full overlay hides it for the current view only; nothing is stored. The
-X on the small status card is where suppression happens: owners, admins and developers get a modal
-offering "this session" (browser storage, per stack) or "for everyone" (writes
-`timeline.onboarding-setup-visible: false` to stack settings); any other role gets the session
-suppression silently.
+| Product | The check fails below |
+|---|---|
+| Live Preview | 1.4.0 |
+| Timeline | major version 2 |
+| Visual Editor | major version 3 |
 
-## What the check does not cover
+So an SDK can pass Live Preview's check and fail Visual Editor's.
 
-This is where the check earns its keep as a diagnostic, and where people over-trust it. "Setup
-Complete" and a broken experience is a real and informative combination.
+## What the checks do not cover
 
-The check verifies reachability, the SDK handshake, SDK version, and that the Preview Service is in
-use. It does not look at any of the following:
+"Setup Complete" with a broken experience is a real and informative combination. None of the three
+checks looks at:
 
-- **Edit tags.** Nothing in the chain inspects `data-cslp`. If the card says Setup Complete and
-  nothing on the canvas is editable, the answer is edit-tag generation, every time. This is the
-  single most useful inference the check supports.
-- **Preview URL resolution.** The site loading is not the same as the correct entry loading. A card
-  reading Setup Complete on the wrong page is a routing problem.
-- **Locale, variants, and Timeline timestamps.**
-- **Caching.** Any cache on the preview path can serve published content while every gate passes.
-- **Roles.** The check runs as the signed-in user but does not report permission gaps, which is why
-  a role problem looks like "works for everyone except one person" rather than a failed gate.
+- **Edit tags.** Nothing inspects `data-cslp`. Setup Complete with nothing editable is edit-tag
+  generation, every time.
+- **Preview URL resolution.** The site loading is not the right entry loading.
+- **Locale, variants and Timeline timestamps.**
+- **Caching.** A cache can serve published content while every gate passes.
+- **Roles.** The check runs as the signed-in user but reports no permission gaps.
 
-## When the card does not appear at all
+## When the check does not appear
 
-Absence is not a pass. Before treating a missing card as "the check succeeded", rule out:
+Absence is not a pass. Rule out:
 
-- No default environment is set and none is remembered locally for that locale, in which case the
-  overlay is deliberately not shown.
-- The user, or someone on their team, dismissed it. The preference persists per stack.
-- The stack setting suppresses it.
+- **Live Preview:** no default environment is set and none is remembered locally for the locale.
+- **Visual Editor:** the check already completed for this user and preview URL, or every gate passed.
+- **Dismissed.** Each product stores a per-stack dismissal in the user's browser storage. It
+  persists until site data is cleared, whatever the dismissal dialog says about "next login".
+- **Turned off in stack settings.**
 
-**Do not reason about the default.** Each product keeps its own stack setting, and they disagree on
-what an unset value means:
+The stack settings disagree on what an unset value means:
 
 | Product | Setting | Unset resolves to |
 |---|---|---|
-| Timeline | `timeline.onboarding-setup-visible` | visible |
 | Live Preview | `live_preview.lp-onboarding-setup-visible` | hidden |
-| Visual Editor | `visual_builder.onboarding-setup-visible` | visible |
-
-The Visual Experience settings screen renders every one of these as **on** when unset, so a stack
-that never explicitly saved the setting can show the toggle on while the card never appears.
-
-The fix is one action: open Settings → Visual Experience and Save, without changing anything. That
-form submits all three products' keys together and an unset value arrives as on, so one save writes
-an explicit value for all three and they stop disagreeing.
-
-If it then appears for colleagues but not for the reporter, they dismissed it. That suppression
-lives per stack in their own browser storage and no stack-level save clears it.
-
-If the user cannot produce the card, fall back to the four contracts in SKILL.md and verify them by
-hand.
+| Timeline | `timeline.onboarding-setup-visible` | visible |
+| Visual Editor | `visual_builder.onboarding-setup-visible` | visible if the stack has no `visual_builder` settings at all; **hidden** if it has them without this key |
 
-## How to ask for it
+The settings screen shows every one of these as **on** when unset, so the toggle can read on while
+the check never appears. The fix is one action: open Settings → Visual Experience and Save without
+changing anything. That writes an explicit value for all three.
 
-Ask for the screenshot rather than the wording. Users paraphrase the step name into a different
-one, and since each name maps to a specific gate, a paraphrase can send you down the wrong branch.
+If the check then appears for colleagues but not the reporter, the reporter dismissed it. No stack
+save clears that; they clear site data for the app origin or use another browser profile.
 
-If they cannot screenshot it, ask for the exact step name and body text as displayed, and confirm
-which product they are in. Live Preview shows one card, Timeline a three-item overlay, Visual Editor
-a six-item list, and none of them share gates; a paraphrased step name from the wrong product sends
-you down the wrong branch.
+If the user cannot produce the check, verify the four contracts in SKILL.md by hand.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
deleted file mode 100644
index 1021d83..0000000
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ /dev/null
@@ -1,105 +0,0 @@
-# Preflight checklist
-
-Run in order. Each step either passes or localises the problem to one contract. Stop at the first
-failure and fix it before continuing, because a failure upstream makes every downstream check
-meaningless.
-
-## Before touching the application
-
-1. **Get the Onboarding Check to appear.** It walks the contracts in order and names the first one
-   that fails. Do not assume its default state: each product has its own toggle under
-   Settings → Visual Experience, and one that has never been saved can read on while the card never
-   appears. Save the setting explicitly for the product in use.
-2. **Live Preview is enabled on the stack**, with a default preview environment set.
-3. **A Preview Token exists**, generated against the Delivery Token the application already uses.
-   A management token is not a substitute and must never reach client-side configuration.
-4. **The environment has a Base URL**, and one for each locale being previewed. A missing Base URL
-   presents as a greyed-out environment selector or "No environments available".
-5. **The signed-in user's role can read everything the page uses.** Preview runs as that user and
-   applies their full ACL — content types, entries, fields, locales, assets — so anything they
-   cannot read comes back empty. Delivery uses a delivery token and applies none. Expect preview
-   to differ per user, and make the site render missing data gracefully.
-
-## Reachability
-
-6. **The preview host is HTTPS, or it is `localhost`.** Browsers treat `http://localhost` as a secure
-   context, so a plain-HTTP dev server loads in the pane. Any other `http://` host inside the HTTPS app
-   is mixed content and the browser blocks the frame; the user can allow it for the Contentstack app
-   origin (Chrome: the shield icon, or Site settings → Insecure content → Allow). An untrusted
-   certificate (self-signed, corporate CA) blanks the frame too, with its own bypass: open the preview
-   URL in its own tab, accept the certificate warning, reload the pane. The browser keeps that
-   exception for the origin.
-7. **`curl -I https://<preview-host>/<a-deep-route>`** returns no `X-Frame-Options`, and a CSP
-   `frame-ancestors` that includes the Contentstack app origin. Test a deep route, not the site
-   root, and confirm it holds after any redirect.
-8. **Nothing sits in front of the site that cannot render in a frame**: platform password
-   protection, an SSO screen setting `X-Frame-Options: DENY`, or basic auth.
-9. **If previewing `http://localhost`**, confirm the browser is not blocking it. Chrome's Local
-    Network Access policy blocks the app origin from framing localhost and only the user can grant
-    the permission.
-
-## Versions
-
-10. **Live Preview Utils v3.0+ and Delivery SDK v3.20.3+** for Visual Editor. **v4.4.4+** if using
-    `setPageContext()`.
-11. **Exactly one copy of the preview SDK is loaded.** An npm install plus an ESM or CDN
-    `<script type="module">` import of a different version produces behaviour differences that look
-    like configuration bugs.
-
-## Contract 1: init runs
-
-12. **The Live Preview Onboarding Check gets past "Live Preview SDK Not Initialized"** when the
-    preview panel loads. That item clears only on the SDK's init message, so while it sticks either
-    `init()` never ran on the client or it ran with a falsy `enable` (item 14).
-13. **`init()` runs on the client**, not in server-only code.
-14. **The enable flag parses as a boolean in the deployed build.** A string `"false"` is truthy.
-15. **`ssr` is set explicitly.** The automatic default keys off `stackSdk` and gets it wrong in both
-    directions: a CSR app without `stackSdk` silently becomes SSR, and an SSG site with `ssr: true`
-    produces blank screens rather than an error.
-16. **`stackDetails: { apiKey, environment }` is passed explicitly.** Since v2 the SDK no longer
-    derives the API key from the Stack object for edit tags.
-17. **`mode: "builder"` is set if Visual Editor is the target.** Visual Editor's own onboarding check
-    has a Verify Mode item that fails on `mode: "preview"`. Edit tags alone do not produce a canvas.
-
-## Contract 2: edit tags reach the DOM
-
-18. **A rendered field carries `data-cslp`**, formed as
-    `<content_type_uid>.<entry_uid>.<locale>.<field_path>`.
-19. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called once on every fetched
-    top-level entry. The third argument must be `true` for React and JSX. References resolved with
-    `includeReference()` are rebased automatically; a separate call is only for hand-merged ones.
-20. **`$` keys are spread onto leaves and containers.** Scalars: the element rendering the value.
-    Multiple, reference and block fields: `entry.$.field` on the wrapper plus `entry.$["field__" + i]`
-    per instance, and an empty one keeps the wrapper with `VB_EmptyBlockParentClass`. Enumerate from
-    `Object.keys(entry.$)`, not from the JSX. See [edit-tags.md](edit-tags.md).
-21. **Reference paths mirror the data shape.** References come back as arrays:
-    `post.author[0].$?.name`, not `post.$?.author.name`.
-22. **For GraphQL**, connection wrappers are flattened and `system { uid, content_type_uid }` is
-    requested on every node, before `addEditableTags()` runs.
-
-## Contract 3: the hash reaches the fetch
-
-23. **Content requests hit a `*-preview.contentstack.com` host** during an active preview session.
-    Seeing `cdn.contentstack.io` or `graphql.contentstack.com` here is the single most common setup
-    failure, whatever the reported symptom was.
-24. **Those requests carry `live_preview` and `preview_token` headers** and return 200.
-25. **Every fetch path uses the initialized Stack instance.** A second instance, a hand-rolled
-    wrapper, or a BFF that bypasses it will keep serving published content.
-26. **The hash is never hardcoded or invented.** An unrecognised hash returns
-    `error_code 382, Please create tracker before starting live preview session`.
-27. **If the app proxies Contentstack through its own backend**, the hash is forwarded end to end.
-28. **SSR only: the Stack instance is built per request.** A module-level instance leaks one
-    editor's draft into other users' responses, including public traffic.
-29. **Caching is bypassed for preview requests.** Any cache on the preview path serves published
-    content after the host switch is already correct, and can serve preview output to real visitors.
-
-## Behaviour
-
-30. **Edit a field without saving.** The preview updates.
-31. **Hover a tagged element in Visual Editor.** It highlights, and clicking focuses the matching
-    field in the form panel.
-32. **Open entries from several content types**, including a nested route and one with no `url`
-    field. Each loads its own page.
-33. **Navigate inside the preview pane.** Preview context survives the navigation.
-34. **Load the public site in a normal browser tab.** No edit button, no `#cslp-tooltip` in the DOM,
-    and no preview response served from cache.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
index 46a4016..df318b1 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -11,29 +11,31 @@ Diagnose against this file. Use `frameworks.md` only for where `init()` is allow
 | Mode | `ssr` | How the hash travels | How updates arrive | Hard requirement |
 |---|---|---|---|---|
 | CSR + REST | `false` | postMessage; the SDK injects it into `stackSdk` | `onEntryChange` / `onLiveEdit` refetch, no reload | `stackSdk` is mandatory |
-| SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload, parent-driven; `onEntryChange` subscribers never fire | a fresh Delivery SDK instance per request |
+| SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload, parent-driven; `onEntryChange` never fires on edits | a fresh Delivery SDK instance per request |
 | CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch | manual host swap plus headers |
 | SSR + GraphQL | `true` | `request.query.live_preview` | full iframe reload | manual host swap plus headers |
 | SSG | `false` | postMessage | runs in CSR mode at runtime | `stackSdk`, and `init()` must be browser-only |
 
-## `onEntryChange` does not fire under `ssr: true`
+## `onEntryChange` does not fire on edits under `ssr: true`
 
-The SDK dispatches entry-change events only when `ssr` is `false`. In SSR mode the parent reloads
-the iframe with the new hash and the app never receives a client-side event. A subscriber registered
-in an SSR app is silently inert, so a `router.refresh()` or refetch wired into it never runs, and the
-integration looks correct while doing nothing on edit. Drive SSR updates from the request, not from a
-subscriber; if client-driven refresh is wanted, the route must be CSR.
+The SDK dispatches edit events to subscribers only when `ssr` is `false`. In SSR mode the parent
+reloads the iframe with the new hash instead. A subscriber registered in an SSR app still runs once at
+page load, which makes it look wired up, and then never runs again on an edit. A `router.refresh()` or
+refetch wired into it does nothing. Drive SSR updates from the request; if client-driven refresh is
+wanted, the route must be CSR.
 
 ## How `ssr` is resolved
 
 Precedence is `stackSdk.live_preview.ssr`, then `init({ ssr })`, then the automatic default.
 
-The automatic default keys off `stackSdk`: present means `ssr: false`, absent means `ssr: true`.
-This is the trap behind several setup failures. A CSR app that omits `stackSdk` silently gets SSR
-behaviour, and an SSG site initialized with `ssr: true` produces blank and black screens rather
-than a clean error.
+- An `ssr` in the Delivery SDK's `live_preview` config silently overrides `init({ ssr })`. Check
+  both places before trusting either.
+- The automatic default keys off `stackSdk`: present means `ssr: false`, absent means `ssr: true`.
+  A CSR app that omits `stackSdk` silently gets SSR behaviour.
+- An SSG site running with `ssr: true` reloads on every edit and re-serves its prerendered HTML, so
+  edits never appear. Users report it as blank screens, flicker or "nothing happens".
 
-Set it explicitly. Do not rely on the default.
+Set `ssr` explicitly, in one place.
 
 ## Mode-specific failures worth knowing before you prescribe
 
@@ -56,19 +58,19 @@ parameter, and a prerendered page never sees a query parameter, so the fetch is
 The documented answer is not to fight that, it is to run the preview path in **CSR mode**, where
 the hash arrives by postMessage instead and never needs the URL.
 
-Per [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-static-site-generator-ssg):
+Per [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/headless-cms/set-up-live-preview-for-static-site-generator-ssg):
 
 - Initialise Live Preview Utils with `ssr: false`
 - Pass `stackSdk`, which is mandatory in CSR mode
 - Configure the Delivery SDK with
-  `live_preview: { preview_token, enable: true, host: "rest-preview.contentstack.com" }`
+  `live_preview: { preview_token, enable: true, host: <region preview host> }`
 - Refresh through `onLiveEdit()`, so the browser refetches on each edit
 
 So an SSG site previews without a rebuild. The static build serves the shell, and the preview
 content is fetched client-side during the session.
 
-The common failure here is not SSG itself, it is an SSG site initialised with `ssr: true`. That
-produces blank and black screens rather than a clean error.
+The common failure here is not SSG itself, it is an SSG site running with `ssr: true`, which
+reloads into the same prerendered HTML on every edit.
 
 ### ISR: the genuinely hard case
 
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 4048af7..7192bd0 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -1,91 +1,170 @@
-# Setup: the documentation is the source of truth
+# New integrations
 
-For setup, follow the official Contentstack documentation. Do not reconstruct setup steps from
-memory and do not invent a procedure. Identify the framework and rendering mode, open the matching
-page, and follow it.
+SKILL.md step 2 sends new integrations here: nothing integrated yet, or Visual Editor or Timeline
+being added to a working Live Preview site.
 
-The rest of this skill exists for when the documented setup has been followed and something still
-does not work. That is a different job, and it is where the mined failure catalogue earns its keep.
+The official documentation is the source of truth. Link the right page and check the requirements
+below against it. Do not write setup procedures from memory.
 
-## Pick the page
+## Steps
 
-Establish framework and rendering mode first, then route.
+1. **Product.** Live Preview, Visual Editor, Timeline, or more than one. Visual Editor and Timeline
+   both build on a working Live Preview, so set that up first.
+2. **Framework and rendering mode.** Read them from the code when it is available (`package.json`,
+   `app/` vs `pages/`, how each route fetches). If the mode is not decided yet, as on a new site,
+   give both candidate pages with one line on how to choose, and ask nothing else.
+3. **Documentation page.** Pick it from the tables below.
+4. **Requirements for that mode.** Walk the matching sections under "Requirements the docs make easy
+   to miss" and confirm each one, in the code or with the user.
+5. **Verify.** Use the checks under "Verify". If verification fails, continue at step 3 of
+   SKILL.md with the check result you already have.
 
-### Start here regardless
+## Documentation pages
 
-- [Set Up Live Preview for your Website](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-your-website) — the setup hub
-- [How Live Preview Works](https://www.contentstack.com/docs/developers/set-up-live-preview/how-live-preview-works) — the model to reason from
-- [How Live Preview Works with SDK](https://www.contentstack.com/docs/headless-cms/how-live-preview-works-with-sdk) — how `ssr` is resolved and how the hash travels
+### Start here
+
+- [Set Up Live Preview for Your Website](https://www.contentstack.com/docs/headless-cms/set-up-live-preview-for-your-website), the setup hub
+- [How Live Preview Works](https://www.contentstack.com/docs/headless-cms/how-live-preview-works)
+- [How Live Preview Works with SDK](https://www.contentstack.com/docs/headless-cms/how-live-preview-works-with-sdk), how `ssr` is resolved and how the hash travels
 
 ### By framework and mode
 
 | Framework and mode | Page |
 |---|---|
-| Next.js App Router, CSR | [Live Preview Implementation for Next.js CSR App Router](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-nextjs-csr-app-router) |
-| Next.js App Router, SSR | [Live Preview Implementation for Next.js SSR App Router](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-nextjs-ssr-app-router) |
-| React, CSR | [Live Preview Implementation for ReactJS CSR Website](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-reactjs-csr-website) |
-| Any framework, SSG | [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-static-site-generator-ssg) — runs in CSR mode, `ssr: false` |
-| Any framework, SSR over REST | [Set Up Live Preview with REST for Server-Side Rendering](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-with-rest-for-server-side-rendering) |
+| Next.js App Router, CSR | [Live Preview Implementation for Next.js CSR App Router](https://www.contentstack.com/docs/headless-cms/live-preview-implementation-for-nextjs-csr-app-router) |
+| Next.js App Router, SSR | [Live Preview Implementation for Next.js SSR App Router](https://www.contentstack.com/docs/headless-cms/live-preview-implementation-for-nextjs-ssr-app-router) |
+| React, CSR | [Live Preview Implementation for ReactJS CSR Website](https://www.contentstack.com/docs/headless-cms/live-preview-implementation-for-reactjs-csr-website) |
+| Any framework, SSG | [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/headless-cms/set-up-live-preview-for-static-site-generator-ssg), which runs in CSR mode with `ssr: false` |
+| Any framework, SSR over REST | [Set Up Live Preview with REST for Server-Side Rendering](https://www.contentstack.com/docs/headless-cms/set-up-live-preview-with-rest-for-server-side-rendering) |
+| Next.js Pages Router | No dedicated page. Use the SSR page for `getServerSideProps` and the SSG page for `getStaticProps` |
+| .NET | [Get Started with .Net SDK and Live Preview](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/dot-net/get-started-with-dot-net-sdk-and-live-preview); edit tags come from `Contentstack.Utils` |
 
-When app routing does not map 1:1 onto `Base URL + entry.url`, or `setPageContext()` is in play, the
-relevant page is [Custom Preview URLs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls). Point to it rather than
-restating its pattern syntax; it is plan-gated and the page carries the current placeholder list.
+Where `init()` goes in each framework: [frameworks.md](frameworks.md).
 
-### Visual Editor, on top of a working Live Preview
+Routing that does not map 1:1 onto `Base URL + entry.url`, or `setPageContext()`:
+[Custom Preview URLs](https://www.contentstack.com/docs/headless-cms/custom-preview-urls). It is
+plan-gated; point to it rather than restating its pattern syntax.
 
-Visual Editor is not a separate integration. It is Live Preview plus edit tags plus `mode: "builder"`
-in `init()`, so Live Preview must work first, and a setup copied from a Live Preview guide will still
-fail Visual Editor's Verify Mode gate until the mode is changed from `"preview"`.
+### Visual Editor
 
-- [Set Up Visual Builder for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-builder/set-up-visual-builder-for-your-website)
-- [Set Up Visual Editor for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-editor/set-up-visual-editor-for-your-website)
-- [Set Up Live Edit Tags for Entries with REST](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-edit-tags-for-entries-with-rest) — the `addEditableTags()` reference
+- [Set Up Visual Editor for Your Website](https://www.contentstack.com/docs/headless-cms/set-up-visual-editor-for-your-website)
+- [Set Up Live Edit Tags for Entries with REST](https://www.contentstack.com/docs/headless-cms/set-up-live-edit-tags-for-entries-with-rest), the `addEditableTags()` reference
 
 ### Timeline
 
-Timeline sits on the same Live Preview integration: `init()` in the frame and the Preview Service on
-the fetch. On top of that the site has to forward `preview_timestamp` next to the hash on every
-request. Its onboarding overlay links to this page:
+- [Set Up Timeline for Your Website](https://www.contentstack.com/docs/headless-cms/set-up-timeline-for-your-website)
+
+### Other
+
+- **Preview Sharing** is not an integration task. A content manager shares the link from the editor;
+  nothing on the site changes. [About Preview Sharing](https://www.contentstack.com/docs/headless-cms/about-preview-sharing).
+- **Starters.** [Kickstart Next.js](https://www.contentstack.com/docs/headless-cms/next) and its
+  siblings are working references. When a user's setup disagrees with a kickstart, the kickstart is
+  right.
+
+## Requirements the docs make easy to miss
+
+Confirm only the sections that apply.
+
+### Stack settings (every product)
+
+- Live Preview enabled under Settings → Visual Experience, with a default preview environment.
+- A Preview Token generated against the Delivery Token the site already uses. Never a management
+  token in client code.
+- Every environment and locale to preview has a Base URL, including the scheme (`https://`) and any
+  locale path segment.
+- Versions: Live Preview Utils v3.0+ for Visual Editor, v4.4.4+ for `setPageContext()`. On the legacy
+  `contentstack` JavaScript SDK, v3.20.3+; `@contentstack/delivery-sdk` releases are all newer. One
+  copy of the preview SDK on the page.
+
+### Every rendering mode
+
+- `init()` runs in the browser, once. In Next.js App Router that means a `"use client"` component.
+- Every content fetch goes through the Stack instance configured with `live_preview: { enable: true,
+  preview_token, host: <region preview host> }`. No second instance, no fetch helper that bypasses it.
+- Hosts match the stack's region: delivery, preview, GraphQL and the app host
+  (`clientUrlParams.host`). Region host names are in `wrong-region-hosts-in-sdk-and-preview-config`
+  in [faq-integration.md](faq-integration.md#wrong-region-hosts-in-sdk-and-preview-config).
+- No cache on the preview path: no CDN caching for the preview deployment, `cache: "no-store"` on
+  preview fetches.
+- Set `ssr` in one place. An `ssr` in the Stack's `live_preview` config overrides `init({ ssr })`.
+
+### CSR and SSG
+
+- `ssr: false` and `stackSdk` passed to `init()`. Without `stackSdk` the SDK defaults to SSR.
+- Refetch on edit with `ContentstackLivePreview.onEntryChange(fetchFn)`. Read the current route
+  inside the callback, not from a value captured at mount.
+
+### SSR
+
+- `ssr: true`. Updates arrive as a parent-driven reload, so do not rely on `onEntryChange`.
+- Build the Stack instance **per request**. A module-level instance leaks one editor's draft into
+  other visitors' responses.
+- Read `live_preview` (and `content_type_uid`, `entry_uid`, `preview_timestamp`) from each request
+  and call `stack.livePreviewQuery(query)` on every request, even when there is no hash, so the
+  instance resets. In Next.js 15, `searchParams` is a Promise: await it first. Snippet:
+  [frameworks.md](frameworks.md#nextjs-app-router).
+- `init()` takes `ssr: true` and no `stackSdk`.
+
+### GraphQL or a custom fetch layer
 
-- [Set Up Timeline](https://www.contentstack.com/docs/developers/set-up-timeline)
+- When the hash is present, switch to the region's preview host and add the `live_preview` and
+  `preview_token` headers. Otherwise use the delivery host. In a BFF or proxy, forward the hash end to
+  end.
 
-### Preview Sharing
+### Visual Editor (on top of Live Preview)
 
-Not an integration task. Once Visual Editor works, sharing a preview link is done from the editor by
-a content manager, and the link is valid for seven days. Nothing on the customer's site changes, so
-send them to the documentation rather than debugging their code:
-[Preview Sharing](https://www.contentstack.com/docs/content-managers/preview-sharing).
+- `mode: "builder"` and `stackDetails: { apiKey, environment }` in `init()`, where `environment` is
+  the environment being previewed. `mode` defaults to `"preview"`, which fails Visual Editor's Verify
+  Mode check, so a Live Preview config without `mode` needs it added. Builder mode throws without
+  `stackDetails`.
+- The environment's Base URL origin matches the previewed site exactly: scheme, `www` and port.
+  Visual Editor checks this; Live Preview does not.
+- `addEditableTags(entry, contentTypeUid, true, locale)` from `@contentstack/utils`, once per
+  top-level entry and after every refetch; `true` for React and JSX. GraphQL responses need
+  normalising first.
+- Spread `entry.$.field` onto the element that renders each value, plus container tags on multiple,
+  reference and block fields, or add and reorder controls never appear. Read
+  [edit-tags.md](edit-tags.md) before answering: it has the key conventions and the empty-block
+  contract.
+- Pass `include_applied_variants=true` on content requests if the stack uses variants.
 
-### Starters
+### Timeline (on top of Live Preview)
 
-[Kickstart Next.js](https://www.contentstack.com/docs/developers/kickstarts/next) and its siblings
-are working references. When a user's setup disagrees with a kickstart, the kickstart is right.
+- Forward `preview_timestamp` next to the hash on every request, and keep both on the URL across
+  client-side navigation.
 
-## What the documentation will not settle
+### Production
 
-These come up constantly and are not answered by any setup page. Say so plainly rather than
-guessing, and reach for `rendering-modes.md` and `faq-setup.md`.
+- Do not initialize preview on the production build (`enable: false`), or add
+  `editButton: { exclude: ["outsideLivePreviewPortal"], includeByQueryParameter: false }`, or the
+  Edit button renders for visitors.
 
-- **Next.js Pages Router.** Supported, but has no dedicated page. Use the SSR-over-REST page for
-  `getServerSideProps` and the SSG page for `getStaticProps`; the contracts are identical.
-- **ISR and framework cache or draft modes.** SSG *is* documented (see the table above). ISR is
-  not. Caching must be off for preview routes, and integrating with a framework's own
-  cache-invalidation or draft feature is out of scope.
-- **Edge runtimes.** No coverage anywhere. Untested rather than unsupported. Say that.
-- **GraphQL with edit tags.** Connection wrappers break `data-cslp` paths and need a
-  customer-side response normalizer. By design; see `graphql-connection-wrappers-break-cslp` in
-  `faq-visual-editor.md`.
-- **Frameworks with a starter but no support history.** A starter existing is not evidence the
-  combination is proven.
+## Reply shape
 
-## Two things worth stating before a user starts
+Docs link first, then only the requirements that apply to the user's framework, mode and product,
+each with a one-line reason, then the verification. Skip requirements the user already showed they
+meet. Snippets only where the docs make the shape easy to get wrong (`init()` options, tag spreading).
 
-**Version minimums.** Live Preview Utils v3.0+ and Delivery SDK v3.20.3+ for Visual Editor, and
-Live Preview Utils v4.4.4+ for `setPageContext()`. Load exactly one copy of the preview SDK; mixing
-an npm install with an ESM or CDN import of a different version produces behaviour that looks like
-a configuration bug.
+## Verify
 
-**`addEditableTags()` mutates and returns nothing.** It updates the entry passed as its first
-argument in place. Assigning its result gives you `undefined`, which is a common first-timer
-mistake. For React and JSX, `tagsAsObject` must be `true`; it defaults to `false`, which produces a
-string that React cannot spread.
+- **Live Preview:** the Onboarding Check card reads **Setup Complete**, and editing a field without
+  saving updates the pane.
+- **Visual Editor:** its check reaches **All Set!**, and hovering a field outlines it; clicking it
+  focuses that field in the form.
+- **Timeline:** its check reaches **All Set!**, and picking a future date shows the scheduled
+  content.
+- **Production:** the public site shows no Edit button and no `data-cslp` attributes when preview is
+  disabled there.
+
+Any failure here continues at SKILL.md step 3 with the check result.
+
+## Not covered by any setup page
+
+Say so plainly rather than guessing:
+
+- **ISR and framework draft or cache modes.** Caching must be off on preview routes; no official
+  hybrid recipe exists. See [rendering-modes.md](rendering-modes.md).
+- **Edge runtimes.** Untested rather than unsupported.
+- **GraphQL with edit tags.** Needs an application-side response normaliser. See
+  `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md`.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md b/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
index 1da6105..35728c5 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
@@ -3,37 +3,36 @@
 Find the reported symptom, go to the entry. Symptoms are worded the way users report them, not the
 way the underlying cause would be described.
 
-Setup entries come first because an unmet setup contract produces a large share of what gets
+Integration entries come first because an unmet contract produces a large share of what gets
 reported as behavioural. If the integration has never fully worked, work the four contracts in
 SKILL.md before reading anything below.
 
-
-## Setup and first integration
+## Integration
 
 | Symptom | Entry |
 |---|---|
-| Live Preview / Visual Editor loads the site fine, but edits made in the entry form or the right-hand panel nev… | [app-fetches-from-delivery-cdn-instead-of-preview-service](faq-setup.md#app-fetches-from-delivery-cdn-instead-of-preview-service) |
-| The Live Preview / Visual Editor pane is blank or shows "`<your-host>` refused to connect" | [iframe-blocked-by-x-frame-options-or-csp-frame-ancestors](faq-setup.md#iframe-blocked-by-x-frame-options-or-csp-frame-ancestors) |
-| Preview API requests fail with `{"error_message":"Please create tracker before starting live preview session",… | [error-382-create-tracker-before-starting-live-preview-session](faq-setup.md#error-382-create-tracker-before-starting-live-preview-session) |
-| Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar | [edit-tags-not-generated-or-not-spread](faq-setup.md#edit-tags-not-generated-or-not-spread) |
-| Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited | [preview-url-does-not-resolve-to-the-app-route](faq-setup.md#preview-url-does-not-resolve-to-the-app-route) |
-| Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump break… | [sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade](faq-setup.md#sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade) |
-| The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wr… | [environment-base-url-misconfigured-or-missing-for-a-locale](faq-setup.md#environment-base-url-misconfigured-or-missing-for-a-locale) |
-| The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or t… | [edit-button-rendered-outside-a-live-preview-session](faq-setup.md#edit-button-rendered-outside-a-live-preview-session) |
-| `Access to fetch at 'https://<region>-rest-preview.contentstack.com/v3/...' from origin '<site origin>' has be… | [cors-blocked-on-preview-api-requests](faq-setup.md#cors-blocked-on-preview-api-requests) |
-| Two opposite failures from the same mistake | [ssr-stack-instance-shared-or-duplicated](faq-setup.md#ssr-stack-instance-shared-or-duplicated) |
-| In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit… | [nextjs-app-router-init-must-run-in-a-client-component](faq-setup.md#nextjs-app-router-init-must-run-in-a-client-component) |
-| "Preview Service Not Enabled" shows in the preview panel on a setup that otherwise works | [legacy-management-token-setup-not-migrated-to-preview-token](faq-setup.md#legacy-management-token-setup-not-migrated-to-preview-token) |
-| Preview opens for pages that already exist on the main branch but never shows updates, and any page that exist… | [branch-or-alias-mismatch-between-app-token-and-entry](faq-setup.md#branch-or-alias-mismatch-between-app-token-and-entry) |
-| Live Preview never activates or the preview panel reports the service is not enabled, even though the stack se… | [wrong-region-hosts-in-sdk-and-preview-config](faq-setup.md#wrong-region-hosts-in-sdk-and-preview-config) |
-| Start Editing / the Edit button opens Visual Editor or the entry editor with `locale=en-us` even though the st… | [locale-defaults-to-en-us-in-init](faq-setup.md#locale-defaults-to-en-us-in-init) |
-| The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `… | [start-editing-button-cannot-be-hidden-in-editor-mode](faq-setup.md#start-editing-button-cannot-be-hidden-in-editor-mode) |
-| A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days… | [onboarding-check-card-not-visible-or-appears-unexpectedly](faq-setup.md#onboarding-check-card-not-visible-or-appears-unexpectedly) |
-| The "Visual Experience" / builder-mode option does not appear in the Contentstack navigation at all, so the te… | [visual-experience-navigation-missing-for-the-stack](faq-setup.md#visual-experience-navigation-missing-for-the-stack) |
-| The site renders in the preview pane but behaves as if logged out, or without personalization, locale or curre… | [third-party-cookies-blocked-inside-the-preview-iframe](faq-setup.md#third-party-cookies-blocked-inside-the-preview-iframe) |
-| A previously working local Live Preview setup breaks with `Access to fetch at 'http://localhost:5173/' from or… | [chrome-local-network-access-blocks-preview-of-localhost](faq-setup.md#chrome-local-network-access-blocks-preview-of-localhost) |
-| `data-cslp` attributes in the DOM contain `undefined` where the entry uid should be | [cslp-tags-contain-the-literal-string-undefined](faq-setup.md#cslp-tags-contain-the-literal-string-undefined) |
-| Live Preview on a statically generated site is unreliable or simply shows build-time content: blank or black s… | [ssg-preview-needs-csr-mode](faq-setup.md#ssg-preview-needs-csr-mode) |
+| Live Preview / Visual Editor loads the site fine, but edits made in the entry form or the right-hand panel nev… | [app-fetches-from-delivery-cdn-instead-of-preview-service](faq-integration.md#app-fetches-from-delivery-cdn-instead-of-preview-service) |
+| The Live Preview / Visual Editor pane is blank or shows "`<your-host>` refused to connect" | [iframe-blocked-by-x-frame-options-or-csp-frame-ancestors](faq-integration.md#iframe-blocked-by-x-frame-options-or-csp-frame-ancestors) |
+| Preview API requests fail with `{"error_message":"Please create tracker before starting live preview session",… | [error-382-create-tracker-before-starting-live-preview-session](faq-integration.md#error-382-create-tracker-before-starting-live-preview-session) |
+| Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar | [edit-tags-not-generated-or-not-spread](faq-integration.md#edit-tags-not-generated-or-not-spread) |
+| Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited | [preview-url-does-not-resolve-to-the-app-route](faq-integration.md#preview-url-does-not-resolve-to-the-app-route) |
+| Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump break… | [sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade](faq-integration.md#sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade) |
+| The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wr… | [environment-base-url-misconfigured-or-missing-for-a-locale](faq-integration.md#environment-base-url-misconfigured-or-missing-for-a-locale) |
+| The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or t… | [edit-button-rendered-outside-a-live-preview-session](faq-integration.md#edit-button-rendered-outside-a-live-preview-session) |
+| `Access to fetch at 'https://<region>-rest-preview.contentstack.com/v3/...' from origin '<site origin>' has be… | [cors-blocked-on-preview-api-requests](faq-integration.md#cors-blocked-on-preview-api-requests) |
+| Two opposite failures from the same mistake | [ssr-stack-instance-shared-or-duplicated](faq-integration.md#ssr-stack-instance-shared-or-duplicated) |
+| In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit… | [nextjs-app-router-init-must-run-in-a-client-component](faq-integration.md#nextjs-app-router-init-must-run-in-a-client-component) |
+| "Preview Service Not Enabled" shows in the preview panel on a setup that otherwise works | [legacy-management-token-setup-not-migrated-to-preview-token](faq-integration.md#legacy-management-token-setup-not-migrated-to-preview-token) |
+| Preview opens for pages that already exist on the main branch but never shows updates, and any page that exist… | [branch-or-alias-mismatch-between-app-token-and-entry](faq-integration.md#branch-or-alias-mismatch-between-app-token-and-entry) |
+| Live Preview never activates or the preview panel reports the service is not enabled, even though the stack se… | [wrong-region-hosts-in-sdk-and-preview-config](faq-integration.md#wrong-region-hosts-in-sdk-and-preview-config) |
+| Start Editing / the Edit button opens Visual Editor or the entry editor with `locale=en-us` even though the st… | [locale-defaults-to-en-us-in-init](faq-integration.md#locale-defaults-to-en-us-in-init) |
+| The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `… | [start-editing-button-cannot-be-hidden-in-editor-mode](faq-integration.md#start-editing-button-cannot-be-hidden-in-editor-mode) |
+| A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days… | [onboarding-check-card-not-visible-or-appears-unexpectedly](faq-integration.md#onboarding-check-card-not-visible-or-appears-unexpectedly) |
+| The "Visual Experience" / builder-mode option does not appear in the Contentstack navigation at all, so the te… | [visual-experience-navigation-missing-for-the-stack](faq-integration.md#visual-experience-navigation-missing-for-the-stack) |
+| The site renders in the preview pane but behaves as if logged out, or without personalization, locale or curre… | [third-party-cookies-blocked-inside-the-preview-iframe](faq-integration.md#third-party-cookies-blocked-inside-the-preview-iframe) |
+| A previously working local Live Preview setup breaks with `Access to fetch at 'http://localhost:5173/' from or… | [chrome-local-network-access-blocks-preview-of-localhost](faq-integration.md#chrome-local-network-access-blocks-preview-of-localhost) |
+| `data-cslp` attributes in the DOM contain `undefined` where the entry uid should be | [cslp-tags-contain-the-literal-string-undefined](faq-integration.md#cslp-tags-contain-the-literal-string-undefined) |
+| Live Preview on a statically generated site is unreliable or simply shows build-time content: blank or black s… | [ssg-preview-needs-csr-mode](faq-integration.md#ssg-preview-needs-csr-mode) |
 
 ## Preview runtime
 
@@ -45,7 +44,6 @@ SKILL.md before reading anything below.
 | Edits only appear after manually reloading the preview | [csr-edits-need-manual-refresh](faq-preview-runtime.md#csr-edits-need-manual-refresh) |
 | Preview works on the entry's own URL, but navigating within the site inside the preview panel breaks it — "Pag… | [spa-client-navigation-loses-preview-context](faq-preview-runtime.md#spa-client-navigation-loses-preview-context) |
 | `ContentstackLivePreview.hash` logs as an empty string, so the code that gates on it never switches to the pre… | [hash-empty-outside-the-preview-iframe](faq-preview-runtime.md#hash-empty-outside-the-preview-iframe) |
-| The very first `onEntryChange` fetch after opening the preview returns published data even though the entry wa… | [stale-first-fetch-when-editing-a-referenced-entry](faq-preview-runtime.md#stale-first-fetch-when-editing-a-referenced-entry) |
 | Live Preview works for top-level fields but an edit to an entry that is referenced inside another entry does n… | [legacy-management-token-preview-breaks-on-references](faq-preview-runtime.md#legacy-management-token-preview-breaks-on-references) |
 | One user sees an empty or partly empty page in Live Preview / Visual Editor while colleagues on the same stack… | [preview-renders-empty-for-a-restricted-user](faq-preview-runtime.md#preview-renders-empty-for-a-restricted-user) |
 | Ad slots, consent widgets, or other host-dependent third-party scripts intermittently fail to render inside Li… | [third-party-scripts-misbehave-inside-the-preview-iframe](faq-preview-runtime.md#third-party-scripts-misbehave-inside-the-preview-iframe) |
diff --git a/cursor/rules/00-router.mdc b/cursor/rules/00-router.mdc
index 648307d..3f26a91 100644
--- a/cursor/rules/00-router.mdc
+++ b/cursor/rules/00-router.mdc
@@ -13,7 +13,7 @@ Use the table below to route a user request to the right skill. Each row maps a
 | Use when users want to migrate, move, switch, port, or re-platform from Contentful to Contentstack, including content models, content, assets, locales, application integrations, website code, migration prerequisites, migration progress checks, or post-migration validation. | [contentstack-migration-companion](../../skills/migration-companion/SKILL.md) |
 | Use when a user wants to migrate Contentstack Delivery SDK code from JavaScript to TypeScript. | [dx-migrate-js-to-ts-sdk](../../skills/dx-migrate-js-to-ts-sdk/SKILL.md) |
 | Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, Live Preview setup, Visual Builder support, SSR preview handling, or debugging SDK query chains. | [dx-delivery-sdk](../../skills/dx-delivery-sdk/SKILL.md) |
-| Use for any Contentstack Live Preview, Visual Editor or Visual Builder question (Visual Editor and Visual Builder are the same product), whether setting it up or debugging it: first-time integration in any framework, SDK upgrades, the SDK installed but nothing happening, a blank preview pane, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, canvas or edit-tag resolution failures, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](../../skills/cms-live-preview-visual-editor-support-assistant/SKILL.md) |
+| Use for any Contentstack Visual Experience question: Live Preview, Visual Editor or Visual Builder (the same product), Timeline, the Onboarding Check, edit tags, preview tokens and hosts, and Visual Experience settings. Covers how they work, setting them up in any framework, configuration, and debugging: the SDK installed but nothing happening, a blank or unreachable preview pane, a stuck Onboarding Check, edits that never appear, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, nothing editable on the canvas, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](../../skills/cms-live-preview-visual-editor-support-assistant/SKILL.md) |
 | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](../../skills/cms-data-modeling-best-practices/SKILL.md) |
 | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](../../skills/cms-entries/SKILL.md) |
 | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](../../skills/cms-assets/SKILL.md) |
diff --git a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
index 5edb18e..f773280 100644
--- a/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
+++ b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
@@ -1,5 +1,5 @@
 ---
-description: "Systematically set up and debug Contentstack Live Preview, Visual Editor (also called Visual Builder), and Timeline. Setup follows the official documentation. Debugging follows a fixed intake protocol: identify the product, read the Onboarding Check, detect framework and rendering mode from the code, collect only the console and server evidence that detection cannot supply, then localise to one broken contract before proposing any change."
+description: "Answer any Contentstack Visual Experience question: Live Preview, Visual Editor (also called Visual Builder), Timeline, the Onboarding Check, edit tags, preview tokens and hosts. Use for how they work, first-time integration in any framework, adding Visual Editor or Timeline to a Live Preview site, configuration, or an integration that misbehaves: a blank or unreachable preview pane, edits that never appear, a stuck Onboarding Check, nothing editable on the canvas, lost preview context, stale or cached preview, wrong locale or variant, Timeline showing the wrong version, or one user seeing empty content."
 alwaysApply: false
 ---
 
@@ -8,431 +8,279 @@ alwaysApply: false
 
 ## Description
 
-Systematically set up and debug Contentstack Live Preview, Visual Editor (also called Visual Builder), and Timeline. Setup follows the official documentation. Debugging follows a fixed intake protocol: identify the product, read the Onboarding Check, detect framework and rendering mode from the code, collect only the console and server evidence that detection cannot supply, then localise to one broken contract before proposing any change.
+Answer any question about Contentstack Visual Experience: Live Preview, Visual Editor (also called
+Visual Builder) and Timeline. One flow covers all of it. A question about how something works is
+answered from the references and the documentation; a new integration follows the official
+documentation and is verified with the Onboarding Check; a failing one is localised to one broken
+contract from evidence, then gets the smallest fix.
 
 ## When to Use
 
-Use for any Contentstack Live Preview, Visual Editor, or Timeline question, whether the integration has never worked or works and misbehaves.
+Use for any Visual Experience question: how a feature works or behaves, what a setting or check
+means, setting up an integration, or an integration that misbehaves.
 
-`dx-delivery-sdk` is the neighbouring skill. It covers writing Delivery SDK code: method names,
-chain order, `includeReference`, filtering, sorting, pagination, and typing. Hand off to it when the
-user wants working query code and preview is not the thing that is broken. Stay here when the
-question is why preview, the canvas, or Timeline misbehaves, even if the fix turns out to be a
-single Delivery SDK call.
-
-Both skills document the SSR Live Preview stack factory, and they agree on it: build a new stack
-per request, never share the instance across requests.
+Hand off to `dx-delivery-sdk` when the user wants Delivery SDK query code and preview is not involved.
+Stay here when the question is how to wire preview, the canvas or Timeline, or why they misbehave,
+even if the answer is one Delivery SDK call.
 
 ## Terminology
 
-**Visual Builder and Visual Editor are the same product.** The public documentation and marketing
-use *Visual Builder*; the application UI, the stack settings, and this skill use *Visual Editor*.
-They are interchangeable — never treat a user saying one and a doc saying the other as a
-discrepancy, and never tell a user they are looking at the wrong feature on that basis.
-
-Mirror whichever term the user used. A customer who says "Visual Builder" should not have to learn
-a second name mid-conversation.
-
-Two related names worth keeping straight:
+**Visual Builder and Visual Editor are the same product.** Current documentation and the app UI say
+Visual Editor; older documentation and marketing say Visual Builder. Never treat the two names as a
+discrepancy. Mirror the term the user used.
 
-- **Visual Experience** is the umbrella covering Live Preview, Visual Editor and Timeline. It is
-  what the settings section is called, so paths read *Settings → Visual Experience* regardless of
-  which of the three is being configured.
-- **`mode: "builder"`** is an SDK option and keeps its name. So does the
-  `visual_builder.onboarding-setup-visible` stack setting. Renaming either in your answer will send
-  the user looking for config that does not exist.
+- **Visual Experience** is the umbrella for Live Preview, Visual Editor and Timeline, and the name of
+  the settings section: *Settings → Visual Experience*.
+- **`mode: "builder"`** (SDK option) and **`visual_builder.onboarding-setup-visible`** (stack
+  setting) keep their names. Do not rename them in an answer.
 
 ## User Problem
 
-The same complaint has many unrelated causes. "Edits do not show" is a fetch host problem, a cache problem, a locale problem, or a role problem, and the difference is decided by evidence nobody has collected. Guessing produces a long thread of speculative fixes.
-
-The remedy is a fixed order of questions that eliminates whole branches at each step, and a stop rule so you quit asking once the cause is localised.
+Setup instructions reconstructed from memory drift from the documentation and miss the requirements
+that differ per rendering mode. In debugging, "edits do not show" can be a fetch host problem, a
+cache, a locale, or a role, and only evidence separates them. Guessing produces a long thread of
+speculative fixes.
 
 ## Success Criteria
 
-- Works the intake protocol in order rather than jumping to a plausible cause
-- Establishes the product first, because the three do not share a setup or a check
-- Asks for the Onboarding Check before anything else, and uses what its result already proves
-- Never asks a question the evidence has already answered
-- Stops collecting once one contract is localised
-- Uses the documentation for setup and the failure catalogue for debugging
-- Recognises causes outside the user's application and points the user to Contentstack Support instead of debugging
+- Works the steps in order and reports the checklist back ticked
+- For a new integration, links the documentation page for the framework and mode instead of
+  inventing steps, and does not ask diagnostic questions about code that does not exist yet
+- Reads the Onboarding Check before any other diagnostic question
+- Never asks for what the code or earlier evidence already answers
+- Names one broken contract, with evidence, before proposing a change
+- Recognises causes outside the application and hands them to Contentstack Support
 
 ## Expected Inputs
 
-Collected in the order set out below, not all at once. Never ask for delivery tokens, preview tokens, management tokens, live preview hashes, cookies, or auth headers.
+Collected step by step, never all at once. Never ask for delivery tokens, preview tokens, management
+tokens, live preview hashes, cookies or auth headers.
 
 ## Expected Outputs
 
-- The broken contract or mechanism, and the evidence for it
+- For a new integration: the documentation page, the requirements that apply, and how to verify
+- For a failing one: the broken contract and the evidence for it
 - The smallest correct change, or a plain statement that no application-side fix exists
-- A verification the user runs themselves
-- What to send Contentstack Support, when the cause sits outside the user's code
+- One verification the user runs
+- A Support handover note when the cause is outside the application
+
+## Example User Requests
+
+- "What does the Onboarding Check actually verify?"
+- "How do I set up Live Preview in our Next.js App Router site?"
+- "We have Live Preview working. What do we add for Visual Builder?"
+- "Live Preview loads but my edits never show up."
+- "The preview pane is blank / says it could not connect."
+- "Visual Builder shows Setup Complete but I can't click anything."
+- "Preview worked yesterday and now shows published content."
+- "Timeline always shows the current version."
+
+## Rules
+
+Follow these on every turn that diagnoses a failure.
+
+1. **Stop rule.** Once one contract is localised, stop collecting evidence and move to the fix.
+2. **Observed beats intended.** The Onboarding Check reports what the deployed build did; the code
+   reports what it intends. When they disagree, the check wins.
+3. **Falsification rule.** Before acting on a diagnosis, name the one artifact that would contradict
+   it, and get it.
+4. **Reproduction rule.** No code change without a reproduced failure. State the contract, the
+   evidence, and the action that reproduces it. No reproduction means a hypothesis: keep collecting.
+5. **Transition rule.** Worked then broke, a gate that advanced then regressed, a new error replacing
+   an old one: restart at step 2 and ask what changed, including your own edits this session.
+6. **No resilience while diagnosing.** Add no fallbacks, retries or caches. A fallback to published
+   content hides the exact signal being debugged.
 
 ## Workflow Summary
 
-Work these as a checklist and report it back ticked. An unticked step is a visible gap the user
-can see and question; a silently skipped step is how a wrong diagnosis gets past both of you.
+Report this back ticked. An unticked step is a visible gap.
 
 - [ ] 1. Identify the product.
-- [ ] 2. Setup or regression.
-- [ ] 3. Read the Onboarding Check. Not skippable whenever a preview pane renders.
-- [ ] 4. Detect framework and rendering mode from the code.
-- [ ] 5. Collect only the evidence detection could not supply.
+- [ ] 2. Question, new integration, never worked, or regression? Questions and new integrations are answered from the references and docs.
+- [ ] 3. Read the Onboarding Check.
+- [ ] 4. Detect framework, rendering mode and fetch layer from the code.
+- [ ] 5. Collect only the evidence steps 3 and 4 did not settle.
 - [ ] 6. Localise to one contract.
-- [ ] 7. Fix, verify, or hand to Contentstack Support.
+- [ ] 7. Fix and verify, or hand to Contentstack Support.
 
 ## Instructions
 
-Work these in order. Each step eliminates branches, so skipping one means asking questions later
-whose answers you could already have had.
-
-**Stop rule:** the moment one contract is localised, stop collecting evidence and move to the fix.
-Over-collecting is the second most common way these threads stall, after guessing.
-
-**Falsification rule:** before acting on a diagnosis, name the one artifact that would contradict
-it, and go get it. Confidence is the cue to do this, not the excuse to skip it. The commonest miss is
-a mode assumption: the code reads one way, and the Onboarding Check card or the network tab says
-otherwise. When they disagree, the observed behaviour wins over the intended one.
-
-**Reproduction rule:** no code change without a reproduced failure. Before editing application code,
-state the contract you believe is broken, the evidence for it, and the command or action that
-reproduces the failure. If you cannot reproduce it, you have a hypothesis, not a diagnosis. Keep
-collecting. A fix that "works" without a reproduced baseline may be working for a reason you have not
-identified, and you will not know which.
-
-**Transition rule:** any transition restarts at step 2. Worked then broke, a gate that advanced then
-regressed, a new error replacing an old one: each is a regression from a known state, and the first
-question is what changed since it last worked. Include your own edits in that question, not only the
-user's. Mid-session, the change most likely to have caused a transition is the one you just made, and
-it is also the one you are least likely to suspect. An Onboarding Check gate that goes backwards is
-information, not flakiness; do not answer it with a reload.
-
-**No-resilience rule:** while diagnosing, add no fallbacks, retries, caches, or optimisations.
-Falling back to published content when the preview fetch fails shows an editor published content
-while they believe they are looking at their edit, and hides the very signal being debugged. Fail
-visibly. If SDK-prescribed behaviour looks improvable, find the guard the SDK already has for that
-concern before changing anything; it usually exists.
-
 ### Step 1. Which product?
 
-Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
-Onboarding Check, or a failure set.
-
-| Product | What it is | Notes |
-|---|---|---|
-| **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
-| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags **plus** `mode: "builder"` in `init()`. `mode: "preview"` fails its Verify Mode gate even with tags present. Not a separate integration. |
-| **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
-| **Preview Sharing** | Share a preview link externally | Plan-gated, and a content-manager feature rather than an integration. The skill carries no troubleshooting for it; point at [Preview Sharing](https://www.contentstack.com/docs/content-managers/preview-sharing). |
-
-If the user is on Visual Editor, confirm whether plain Live Preview works. If it does not, that is
-the problem, and the Visual Editor symptom is downstream noise.
+Ask explicitly. Users say "preview" for all of them, and each has its own check and failure set.
 
-### Step 2. Setup, or regression?
-
-Ask: has this ever worked correctly, for anyone, on any route?
-
-**Never worked** goes to [references/setup-docs.md](references/setup-docs.md). Follow the official
-documentation for the framework and mode. Do not reconstruct setup steps from memory. Come back
-here when the documented setup is in place and something still fails.
-
-**Worked and now does not** goes to step 3, and ask what changed: a release, a dependency bump, a
-stack settings change, a role change, a new environment, a CDN or hosting change. This question is not
-only for intake. Every transition during the session, such as a gate that advanced and then regressed
-or a new error replacing the old one, comes back here, and the list of changes must include every
-edit you made since the last known-good state, not only the user's.
+| Product | What it is |
+|---|---|
+| **Live Preview** | Preview pane with content refresh. Everything else builds on it. |
+| **Visual Editor** | Live Preview plus on-canvas editing. Needs edit tags **and** `mode: "builder"` in `init()`. |
+| **Timeline** | Preview at a point in time. Needs `preview_timestamp` forwarded with the hash. |
+
+On Visual Editor or Timeline, confirm plain Live Preview works. If it does not, that is the problem.
+
+### Step 2. Question, new, never worked, or regression?
+
+- **A question about how something works, not a failure** ("what does the Onboarding Check
+  verify?", "does Timeline need anything extra?", "what is the difference between Live Preview and
+  Visual Builder?"): answer it from the relevant reference file and link the documentation page.
+  No diagnostic intake. If the answer reveals a failure, continue at step 3.
+- **Nothing integrated yet, or adding Visual Editor or Timeline:** read the framework and rendering
+  mode from the code, give the matching documentation page and the requirements that apply from
+  [references/setup-docs.md](references/setup-docs.md), and stop there. Do not ask diagnostic
+  questions about code that does not exist yet. When the user has it in place, continue at step 3 to
+  verify.
+- **Integrated, never worked:** continue at step 3.
+- **Worked, now broken:** ask what changed (release, dependency bump, settings, role, environment,
+  CDN or hosting), then continue at step 3.
 
 ### Step 3. Read the Onboarding Check
 
-Ask for a **screenshot** of the floating status card in the preview panel. Do this before any other
-diagnostic question. The product already ran the check you are about to run by hand.
+Ask for a **screenshot** of the check in the preview panel, before any other diagnostic question.
+Code access does not excuse this step. Users paraphrase step names, and each name maps to one gate.
+If the user already quoted a card or item name that matches the tables below word for word, use it
+and skip the screenshot.
 
-**This step is not skippable when a pane renders at all, and repository access does not excuse it.**
-Step 4 reads the code and tells you what the integration *intends*; the card tells you what the editor
-*observed* on the actual deployed build. They can disagree, most often on rendering mode, and when
-they do the card is the one that reflects reality. Do step 3 first, then let step 4 explain it.
+All three products evaluate their gates as a chain that stops at the first failure. **Read the first
+failing item. Everything before it passed; everything after it never ran.**
 
-Ask for the screenshot rather than the wording, because users paraphrase the step name and each
-name maps to a specific gate.
-
-Three products, three different checks. Confirm the product first. Full gate lists and meanings are
-in [references/onboarding-check.md](references/onboarding-check.md).
-
-**Live Preview** shows one card. The gates run as one ordered chain that stops at the first failure,
-so the step shown proves every earlier gate passed:
+Live Preview shows one card:
 
 | Card | Localises to |
 |---|---|
-| Could Not Connect to Website | Frame headers, auth gate, Base URL, certificate, browser blocking localhost |
-| Live Preview SDK Not Initialized | `init()` never ran on the client in the deployed build |
-| Outdated Live Preview SDK Version | Version below the supported minimum |
-| Preview Service Not Enabled | The fetch never switched host and headers |
-| Default Environment Not Set | Setup is fine; no default preview environment on the stack |
-| Setup Complete | Reachability, handshake, version and Preview Service are all fine |
-
-**Visual Editor shows a six-item list, not a card**, but it still stops evaluating at the first item
-that fails, so read the first incomplete item and ignore the ones under it. Configure environment
-(Default Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
-customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
-Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
-
-**Timeline runs a third check.** A small status card while it runs, then a full-pane "Set Up
-Timeline" overlay with three items once one fails. The items are chained, so the first empty circle
-is the failure and the ones below it never ran:
-
-| Overlay item | Localises to |
-|---|---|
-| Configure the environment | No environment on the Timeline URL and no default preview environment on the stack |
-| Install the latest Live Preview SDK | The `init()` handshake never reached Timeline, or the SDK major version is below 2 |
-| Generate and use Preview Token | No content request reached the Preview Service before the check stopped waiting |
+| Could Not Connect to Website | Network-level failure only: wrong or unreachable Base URL, DNS, bad certificate, mixed content, the browser blocking localhost |
+| Live Preview SDK Not Initialized | No init handshake: `init()` never ran on the client, `enable` not truthy, **or the frame is blank** (frame headers, an auth or password screen) |
+| Outdated Live Preview SDK Version | SDK below 1.4.0 |
+| Preview Service Not Enabled | Content fetch never switched to the preview host and headers |
+| Default Environment Not Set | Integration fine; the stack has no default preview environment |
+| Setup Complete | Reachability, handshake, version and Preview Service all fine |
 
-The overlay appears ten seconds after the last status change, and item 3 gives up waiting at about
-nine, so a slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
-before believing it.
+Visual Editor and Timeline show a status card while checking, then a full-pane overlay ("Set Up
+Visual Editor", "Set Up Timeline") listing their items. Gates, verbatim item text and timing are in
+[references/onboarding-check.md](references/onboarding-check.md). The two Visual Editor items that
+catch users coming from a Live Preview guide: **Verify Mode for Live Preview** fails on
+`mode: "preview"`, and **Validate the Base URL** needs the Base URL origin to match the previewed page
+exactly.
 
-Two readings that decide the whole branch:
+Two readings decide the branch:
 
-- **Setup Complete, but nothing is editable.** The check never inspects `data-cslp`. This is edit
-  tags, every time. Go to contract 2 in step 6.
-- **No card at all.** Absence is not a pass. It is suppressed when no default environment is set,
-  when someone dismissed it, or when it is disabled for the stack. Verify the contracts by hand.
+- **Setup Complete, nothing editable.** The check never inspects `data-cslp`. Go to contract 2.
+- **Setup Complete, only fields from referenced entries not editable.** Tags are not rebased to the
+  referenced entry: `cslp-not-rebased-to-referenced-entry` in faq-visual-editor.md.
+- **No check at all.** Absence is not a pass. See "When the check does not appear" in
+  onboarding-check.md, then verify the contracts by hand.
 
-### Step 4. Establish framework and rendering mode
+### Step 4. Detect framework, mode and fetch layer
 
-**Detect this, do not ask for it.** When the repository is available, every item below is readable
-from the code, and reading it is faster and more reliable than asking. Detection does not replace
-step 3: the card still comes first, because it reports the deployed build rather than the branch you
-are reading. Developers routinely answer
-"Next.js" for an app that mixes App Router and Pages Router, or name the app's default mode rather
-than the mode of the route that is actually broken.
+Read the code instead of asking. State what you found and ask only for confirmation.
 
-Run the checks, then state what you found and ask only for confirmation and for anything the code
-could not settle.
-
-| Question | Where to look | What it tells you |
+| Check | Where | Why |
 |---|---|---|
-| Framework and version | `package.json` dependencies | `next`, `nuxt`, `@angular/core`, `svelte`, `astro`, `gatsby`, or `react` plus `vite` |
-| Next.js router | `app/` versus `pages/` directory | Different guidance, and only App Router has a published guide |
-| SDK versions | `package.json`, lockfile | Against the minimums in Tooling Notes |
-| One SDK copy | lockfile, plus any `<script type="module">` in the HTML | An npm install alongside a CDN import of another version behaves like a config bug |
-| Rendering mode of the route | `export const dynamic`, `revalidate`, `getStaticProps`, `getServerSideProps`, `output: "export"` | The mode of that route, which is what matters |
-| `ssr` setting | the `init(` call site | Explicit value, or absent and therefore inferred |
-| `stackSdk` passed | the `init(` call site | Mandatory in CSR, and what the SDK uses to default `ssr` |
-| Init placement | the file containing `init(`, and whether it is `"use client"` | Contract 1. Server-only placement is the most common Next.js miss |
-| Edit tags | `addEditableTags` | Contract 2. Absent means Visual Editor cannot work, whatever else is true |
-| Fetch layer | `@contentstack/delivery-sdk` import, raw `fetch`, or a GraphQL client | Decides which form of contract 3 applies |
-| Preview host wiring | `preview_token`, `live_preview`, any hostname constant | Contract 3 |
-| Cache posture | `fetch` cache options, `revalidate`, CDN or middleware config | The "works locally, fails deployed" class |
-
-That sweep usually settles contracts 1, 2 and 3 in step 6 before you ask the user anything, and it
-often makes step 5 unnecessary.
-
-Two things the repository cannot tell you. Ask for these:
-
-1. **Where it is served**: localhost, a preview deployment, or production.
-2. **Whether the deployed build matches the branch you are reading.** An environment variable that
-   does not parse as a boolean, or a stale deploy, makes correct-looking code behave as if init
-   never ran.
-
-Without repository access, ask for the same list, in this order: framework and version, the mode of
-the affected route, the fetch layer, and the `init()` call site.
-
-The SDK ships no framework adapters, no framework peer dependencies, and no per-framework code
-paths. Framework choice decides only where `init()` may run and whether hydration preserves edit
-tags. Everything else follows from mode and fetch layer.
-
-| Mode | `ssr` | Hash travels via | Updates arrive as |
+| Framework, router | `package.json`; `app/` vs `pages/` | Decides where `init()` may run |
+| SDK versions, one copy | `package.json`, lockfile, any `<script type="module">` | Two copies behave like a config bug |
+| Route's rendering mode | `dynamic`, `revalidate`, `getStaticProps`, `getServerSideProps`, `output: "export"` | The broken route's mode, not the app default |
+| `ssr` | `init(` call site **and** the Stack's `live_preview.ssr` | Stack config overrides `init({ ssr })` |
+| `stackSdk`, `mode` | `init(` call site | `stackSdk` absent defaults `ssr` to `true` |
+| Init placement | file containing `init(`, `"use client"` | Contract 1 |
+| Edit tags | `addEditableTags` | Contract 2 |
+| Fetch layer, host wiring | Delivery SDK, raw `fetch`, GraphQL client; `preview_token`, `live_preview`, hosts | Contract 3 |
+| Cache | fetch cache options, `revalidate`, CDN or middleware | "Works locally, fails deployed" |
+
+The code cannot tell you where the site is served or whether the deployed build matches the branch.
+Ask for both.
+
+Mode decides how updates arrive:
+
+| Mode | `ssr` | Hash reaches the fetch via | Updates |
 |---|---|---|---|
-| CSR + REST | `false` | postMessage, into `stackSdk` | `onEntryChange` refetch, no reload |
-| SSR + REST | `true` | `live_preview` query parameter | full iframe reload, driven by the parent. `onEntryChange` subscribers **never fire** in this mode |
-| CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch, manual host swap |
-| SSR + GraphQL | `true` | `request.query.live_preview` | full reload, manual host swap |
-| SSG | `false` | postMessage | runs as CSR at runtime |
-
-**`onEntryChange` is inert under `ssr: true`.** The SDK guards its entry-change dispatch on `!ssr`,
-so any subscriber registered in an SSR app never runs. Registering one to trigger a refetch or
-`router.refresh()` produces a callback that looks correct and does nothing. Under `ssr: true` the
-update path is the parent reloading the iframe with the new hash; the app's only job is to read the
-hash off that request. If you want client-driven refresh, the route has to be CSR (`ssr: false`).
-
-`stackSdk` is mandatory in CSR and is what the SDK uses to default `ssr`. A CSR app that omits it
-silently gets SSR behaviour; an SSG site initialised with `ssr: true` gives blank screens rather
-than an error. Two mode traps to check before prescribing: **SSR** needs a per-request Stack
-instance, because a module-level one leaks one editor's draft into other users' responses; **SSG** is
-supported, but only in CSR mode: a prerendered page never sees the `live_preview` query parameter,
-so the documented setup is `ssr: false` with `stackSdk`, where the hash arrives by postMessage
-instead. **ISR** is the harder case: a regenerated page is still a cached page, and caching has to be off
-on the preview path. There is no published recipe for combining ISR with Live Preview.
-
-Detail and the framework coverage table are in
-[references/rendering-modes.md](references/rendering-modes.md); init placement per framework is in
+| CSR (incl. SSG at runtime) | `false` | postMessage into `stackSdk`; `ContentstackLivePreview.hash` for GraphQL | `onEntryChange` refetch |
+| SSR | `true` | `live_preview` query parameter on the request | Parent reloads the iframe; `onEntryChange` never fires on edits |
+
+Detail per mode, including SSG, ISR and GraphQL, is in
+[references/rendering-modes.md](references/rendering-modes.md). Init placement per framework is in
 [references/frameworks.md](references/frameworks.md).
 
-### Step 5. Collect logs and one request
-
-Only for what step 4 could not settle. With repository access the contracts are often already
-localised, and the single most valuable item left is the request host. Skip whatever you can
-already answer, and ask for the rest in one pass rather than one at a time.
-
-1. **Browser console, with the preview panel open.** Look for the init handshake, CSP or frame
-   refusals, CORS failures, and framework hydration errors. Ask them to reproduce with the console
-   open, because most of these fire once at load. Read it against the noise list below before
-   drawing any conclusion.
-2. **Server-side logs**, for SSR, middleware, BFF, or proxy setups. This is where a swallowed
-   preview fetch error lives, and it is invisible in the browser. Skip for pure CSR.
-3. **One failing request from the Network tab**: full request URL and host, response status, and
-   response headers. Redacted.
-
-**Check the console output against [references/console-noise.md](references/console-noise.md)
-before concluding anything from it.** Preview runs the site in an iframe with postMessage between
-two apps, so a healthy setup still produces console chatter — `NO_REQUEST_LISTENER_FOUND` and third-party script errors both appear on working
-integrations. If one of those is the only thing in the console, you have no console evidence, not
-evidence of a problem.
-
-The request host alone settles the most common failure of all. During an active preview
-session, content coming from `cdn.contentstack.io` or `graphql.contentstack.com` means the hash is
-not reaching the fetch, regardless of the reported symptom.
-
-Also ask, in one line each, the questions that separate causes:
-
-- **One user or everyone?** One user points at their role. Preview runs as that user and applies
-  their full ACL — content types, entries, fields, locales, assets — so anything they cannot read
-  comes back empty. Delivery uses a delivery token and applies none, which is why the published
-  page looks fine. This is by design: the fix is usually defensive rendering on the site, not a
-  product issue.
-- **Localhost or deployed?** Working locally and failing deployed is a cache on the preview path,
-  or a frame header.
-- **Consistent or intermittent?** Intermittent and user-dependent under SSR is a shared
-  module-level Stack instance. That one reaches public traffic.
-- **Which locale, and which variant?** Both change the fetch, and both are common false leads.
+### Step 5. Collect what is still open
 
-### Step 6. Localise to one contract
+Ask for the rest in one message, skipping anything already settled:
+
+1. **Browser console** with the preview panel open, reproduced after a reload. Check it against
+   [references/console-noise.md](references/console-noise.md) first: some messages appear on
+   healthy setups and are not evidence.
+2. **Server logs**, for SSR, middleware, BFF or proxy setups. A swallowed preview fetch error lives
+   here.
+3. **One content request from the Network tab**: host, status, response headers, redacted. A
+   delivery CDN host for the stack's region during a preview session means the hash is not reaching
+   the fetch, whatever the symptom.
 
-A working integration needs four independent contracts. They fail separately and complain
-identically. Name which one is unmet, with the evidence, before proposing anything.
+And, one line each: one user or everyone (one user points at their role), localhost or deployed
+(deployed-only points at a cache or frame header), consistent or intermittent (intermittent under SSR
+points at a shared Stack instance), which locale and variant.
+
+### Step 6. Localise to one contract
 
 | # | Contract | One-look check |
 |---|---|---|
-| 1 | `init()` runs, on the client, in the deployed build | The Live Preview Onboarding Check moves past "Live Preview SDK Not Initialized" — that item clears only when the SDK's init message reaches the app, which happens only from `init()` |
-| 2 | Edit tags are generated and land on DOM elements | Some rendered element carries `data-cslp` |
-| 3 | The hash reaches the fetch, which switches host plus headers | Content requests hit a `*-preview.contentstack.com` host |
-| 4 | The preview target is reachable in an iframe | The pane renders at all |
-
-Contract 1 gates 2 and 3. Contract 4 gates everything. Steps 3, 4 and 5 have usually already decided
-this; if they have, do not re-derive it.
-
-For contract 2, the one the Onboarding Check cannot see:
-
-```jsx
-addEditableTags(entry, contentTypeUid, true, locale);
-<h1 {...data.$?.title}>{data.title}</h1>
-```
-
-`mode: "builder"` does not generate tags; only `addEditableTags()` does. (`mode: "builder"` is
-still required, because Visual Editor's Verify Mode gate fails on `mode: "preview"`.) The call
-mutates the entry and returns nothing, and the third argument must be `true` for React and JSX.
-Call it once per top-level entry: references resolved with `includeReference()` or `include[]`
-carry `uid` and `_content_type_uid`, and their tags are rebased to the referenced entry
-automatically. A separate call is needed only for references merged by hand, or GraphQL nodes
-fetched without `system`. Mirror the data path exactly, because references come back as arrays:
-`post.author[0].$?.name`, not `post.$?.author.name`.
-
-Tag leaves **and** containers. A scalar takes `entry.$.field` on the element that renders the value.
-Multiple fields, references and modular blocks take `entry.$.field` on the wrapper plus
-`entry.$["field__" + i]` on each instance; the canvas attaches add and reorder controls only when
-an instance sits inside an element carrying the container tag. An empty multiple or block field
-keeps its wrapper in the DOM while previewing, marked with `VB_EmptyBlockParentClass` and the
-container tag, or the canvas has nothing to draw its add button on.
-
-Enumerate fields from `Object.keys(entry.$)` and diff against what the page renders. Do not eyeball
-the JSX. The full key convention and a per-field-kind checklist are in
-[references/edit-tags.md](references/edit-tags.md).
-
-For contract 3:
-
-```js
-// SSR reads it from the request. CSR uses ContentstackLivePreview.hash.
-const livePreviewHash = request.query.live_preview;
-
-if (livePreviewHash) {
-  headers.append("live_preview", livePreviewHash);
-  headers.append("preview_token", PREVIEW_TOKEN);
-  url.hostname = LIVE_PREVIEW_HOST;   // rest-preview.contentstack.com
-} else {
-  url.hostname = CONTENTSTACK_CDN_HOST; // cdn.contentstack.io
-}
-```
-
-If the symptom is behavioural rather than a failed contract, look it up in
-[references/symptom-index.md](references/symptom-index.md), which routes to
-[faq-setup.md](references/faq-setup.md),
-[faq-preview-runtime.md](references/faq-preview-runtime.md),
-[faq-visual-editor.md](references/faq-visual-editor.md), and
-[faq-timeline.md](references/faq-timeline.md).
-
-For a first-time setup or an end-to-end sweep,
-[references/preflight-checklist.md](references/preflight-checklist.md) runs the contracts as 34
-ordered checks.
-
-### Step 7. Fix, verify, or hand to Contentstack Support
-
-Before proposing any change, satisfy the reproduction rule: contract, evidence, and the action that
-reproduces the failure, stated in that order. Then propose the smallest correct change at the right
-layer: init, tagging, fetch, cache boundary, routing, or stack configuration, and give one verification
-the user runs themselves. The verification is the reproduction step run again with the opposite
-result.
-
-Some causes sit outside the user's application entirely: stack provisioning, plan gating, and
-browser policy. Recognising one early beats any workaround, because no change to the site can
-resolve it. See [references/contact-support.md](references/contact-support.md) for the list, and
-**produce the handover note it defines** — filled from what steps 1–6 already collected — for the
-user to paste into their ticket to Contentstack Support.
+| 1 | `init()` runs on the client in the deployed build | Live Preview check gets past "Live Preview SDK Not Initialized" |
+| 2 | Edit tags are generated and land on DOM elements | Rendered elements carry `data-cslp` |
+| 3 | The hash reaches the fetch, which switches host and headers | Content requests hit the region's `*-preview` host |
+| 4 | The site is reachable in an iframe | The pane renders at all |
+
+Contract 4 gates everything; contract 1 gates 2 and 3. Name the unmet one with its evidence.
+
+- Contract 2 detail, key conventions and the empty-block contract:
+  [references/edit-tags.md](references/edit-tags.md).
+- Behavioural symptoms: look them up in [references/symptom-index.md](references/symptom-index.md),
+  which routes to [faq-integration.md](references/faq-integration.md),
+  [faq-preview-runtime.md](references/faq-preview-runtime.md),
+  [faq-visual-editor.md](references/faq-visual-editor.md) and
+  [faq-timeline.md](references/faq-timeline.md).
+
+### Step 7. Fix and verify, or hand over
+
+State contract, evidence and reproduction, then the smallest change at the right layer: init, tags,
+fetch, cache, routing, or stack configuration. The verification is the reproduction run again with
+the opposite result.
+
+Some causes sit outside the application: provisioning, plan gating, browser policy. No site change
+fixes them. See [references/contact-support.md](references/contact-support.md) and produce its
+handover note from what steps 1 to 6 already collected.
 
 ## Output Format
 
-Lead with the broken contract or mechanism and the evidence for it. Then the smallest correct
-change, as a snippet or diff, or a plain statement that no application-side fix exists. Then one
-verification. Attach mode-specific caveats to the step they affect.
+New integration: follow "Reply shape" in [references/setup-docs.md](references/setup-docs.md).
+
+Failing integration: lead with the broken contract and its evidence. Then the smallest change as a snippet or diff, or a
+plain statement that no application-side fix exists. Then one verification.
 
-When you still need evidence, ask for the specific artifact that separates the remaining
-candidates, and say what each possible answer would mean. Do not send a generic list of requests.
+When evidence is still missing, ask for the one artifact that separates the remaining candidates and
+say what each answer would mean.
 
-Say when a behaviour applies only to preview and not production, and say the reverse too, because
-preview output reaching real visitors is a production incident rather than an authoring annoyance.
+Say whether a behaviour applies to preview only or to production too. Preview output reaching real
+visitors is a production incident.
 
 ## Tooling Notes
 
-Read-only inspection first, with Read, Grep and Glob when the repository is available. Useful
-greps: the `init(` call site, `addEditableTags`, `onEntryChange`, `live_preview`, `preview_token`,
-any hostname constant, and cache configuration on the preview route.
+Read-only inspection with Read, Grep and Glob. Useful greps: `init(`, `addEditableTags`,
+`onEntryChange`, `live_preview`, `preview_token`, hostname constants, cache configuration.
 
-Minimum versions: Live Preview Utils v3.0+ and Delivery SDK v3.20.3+ for Visual Editor, and Live
-Preview Utils v4.4.4+ for `setPageContext()`. Confirm exactly one copy of the preview SDK is
-loaded.
+Minimum versions: Live Preview Utils v3.0+ for Visual Editor (legacy `contentstack` JavaScript SDK
+v3.20.3+); Live Preview Utils v4.4.4+ for `setPageContext()`.
 
-When the repository is not available, run the same protocol against described code and screenshots.
-Do not pretend to have inspected code.
+Without repository access, run the same steps against described code and screenshots. Do not claim
+to have inspected code.
 
 ## Security
 
 ### Defaults
 
-- Never expose delivery tokens, preview tokens, management tokens, or environment secrets.
-- Treat preview tokens and live preview hashes as credentials. Do not ask users to paste them, and
-  redact them if they appear. Ask for redacted logs and screenshots.
-- A management token in client-side Live Preview configuration is an exposure.
+- Never ask for, echo or reconstruct tokens or live preview hashes. Ask for redacted logs and
+  screenshots. If a secret appears, tell the user to rotate it.
+- A management token in client-side configuration is an exposure.
 - Do not recommend enabling Live Preview in production builds. An edit button on a public site is a
   symptom of exactly that.
-- Preview output served to real visitors is a production data-exposure issue, not a cosmetic bug.
-- Validate preview target hosts before suggesting header or CSP changes.
+- Validate preview target hosts before suggesting header or CSP changes, and scope any relaxation to
+  the preview deployment.
 
 ### Destructive Actions
 
-Do not change stack settings, roles, tokens, cache configuration, or environment configuration
-automatically. Propose the change, state the blast radius, and require confirmation.
-
-### Secrets
-
-Never reveal, echo, or reconstruct tokens or hashes. If a secret appears in provided input, tell
-the user to rotate it.
+Do not change stack settings, roles, tokens, cache or environment configuration automatically.
+Propose the change, state the blast radius, and require confirmation.
diff --git a/skills/CLAUDE.md b/skills/CLAUDE.md
index 69f4fef..9996622 100644
--- a/skills/CLAUDE.md
+++ b/skills/CLAUDE.md
@@ -8,7 +8,7 @@ Use the table below to route a user request to the right skill. Each row maps a
 | Use when users want to migrate, move, switch, port, or re-platform from Contentful to Contentstack, including content models, content, assets, locales, application integrations, website code, migration prerequisites, migration progress checks, or post-migration validation. | [contentstack-migration-companion](./migration-companion/SKILL.md) |
 | Use when a user wants to migrate Contentstack Delivery SDK code from JavaScript to TypeScript. | [dx-migrate-js-to-ts-sdk](./dx-migrate-js-to-ts-sdk/SKILL.md) |
 | Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, Live Preview setup, Visual Builder support, SSR preview handling, or debugging SDK query chains. | [dx-delivery-sdk](./dx-delivery-sdk/SKILL.md) |
-| Use for any Contentstack Live Preview, Visual Editor or Visual Builder question (Visual Editor and Visual Builder are the same product), whether setting it up or debugging it: first-time integration in any framework, SDK upgrades, the SDK installed but nothing happening, a blank preview pane, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, canvas or edit-tag resolution failures, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](./cms-live-preview-visual-editor-support-assistant/SKILL.md) |
+| Use for any Contentstack Visual Experience question: Live Preview, Visual Editor or Visual Builder (the same product), Timeline, the Onboarding Check, edit tags, preview tokens and hosts, and Visual Experience settings. Covers how they work, setting them up in any framework, configuration, and debugging: the SDK installed but nothing happening, a blank or unreachable preview pane, a stuck Onboarding Check, edits that never appear, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, nothing editable on the canvas, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](./cms-live-preview-visual-editor-support-assistant/SKILL.md) |
 | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](./cms-data-modeling-best-practices/SKILL.md) |
 | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](./cms-entries/SKILL.md) |
 | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](./cms-assets/SKILL.md) |
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
index 5283997..660517d 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: cms-live-preview-visual-editor-support-assistant
-description: "Systematically set up and debug Contentstack Live Preview, Visual Editor (also called Visual Builder), and Timeline. Setup follows the official documentation. Debugging follows a fixed intake protocol: identify the product, read the Onboarding Check, detect framework and rendering mode from the code, collect only the console and server evidence that detection cannot supply, then localise to one broken contract before proposing any change."
+description: "Answer any Contentstack Visual Experience question: Live Preview, Visual Editor (also called Visual Builder), Timeline, the Onboarding Check, edit tags, preview tokens and hosts. Use for how they work, first-time integration in any framework, adding Visual Editor or Timeline to a Live Preview site, configuration, or an integration that misbehaves: a blank or unreachable preview pane, edits that never appear, a stuck Onboarding Check, nothing editable on the canvas, lost preview context, stale or cached preview, wrong locale or variant, Timeline showing the wrong version, or one user seeing empty content."
 allowed-tools: Read Grep Glob
 ---
 
@@ -8,431 +8,279 @@ allowed-tools: Read Grep Glob
 
 ## Description
 
-Systematically set up and debug Contentstack Live Preview, Visual Editor (also called Visual Builder), and Timeline. Setup follows the official documentation. Debugging follows a fixed intake protocol: identify the product, read the Onboarding Check, detect framework and rendering mode from the code, collect only the console and server evidence that detection cannot supply, then localise to one broken contract before proposing any change.
+Answer any question about Contentstack Visual Experience: Live Preview, Visual Editor (also called
+Visual Builder) and Timeline. One flow covers all of it. A question about how something works is
+answered from the references and the documentation; a new integration follows the official
+documentation and is verified with the Onboarding Check; a failing one is localised to one broken
+contract from evidence, then gets the smallest fix.
 
 ## When to Use
 
-Use for any Contentstack Live Preview, Visual Editor, or Timeline question, whether the integration has never worked or works and misbehaves.
+Use for any Visual Experience question: how a feature works or behaves, what a setting or check
+means, setting up an integration, or an integration that misbehaves.
 
-`dx-delivery-sdk` is the neighbouring skill. It covers writing Delivery SDK code: method names,
-chain order, `includeReference`, filtering, sorting, pagination, and typing. Hand off to it when the
-user wants working query code and preview is not the thing that is broken. Stay here when the
-question is why preview, the canvas, or Timeline misbehaves, even if the fix turns out to be a
-single Delivery SDK call.
-
-Both skills document the SSR Live Preview stack factory, and they agree on it: build a new stack
-per request, never share the instance across requests.
+Hand off to `dx-delivery-sdk` when the user wants Delivery SDK query code and preview is not involved.
+Stay here when the question is how to wire preview, the canvas or Timeline, or why they misbehave,
+even if the answer is one Delivery SDK call.
 
 ## Terminology
 
-**Visual Builder and Visual Editor are the same product.** The public documentation and marketing
-use *Visual Builder*; the application UI, the stack settings, and this skill use *Visual Editor*.
-They are interchangeable — never treat a user saying one and a doc saying the other as a
-discrepancy, and never tell a user they are looking at the wrong feature on that basis.
-
-Mirror whichever term the user used. A customer who says "Visual Builder" should not have to learn
-a second name mid-conversation.
-
-Two related names worth keeping straight:
+**Visual Builder and Visual Editor are the same product.** Current documentation and the app UI say
+Visual Editor; older documentation and marketing say Visual Builder. Never treat the two names as a
+discrepancy. Mirror the term the user used.
 
-- **Visual Experience** is the umbrella covering Live Preview, Visual Editor and Timeline. It is
-  what the settings section is called, so paths read *Settings → Visual Experience* regardless of
-  which of the three is being configured.
-- **`mode: "builder"`** is an SDK option and keeps its name. So does the
-  `visual_builder.onboarding-setup-visible` stack setting. Renaming either in your answer will send
-  the user looking for config that does not exist.
+- **Visual Experience** is the umbrella for Live Preview, Visual Editor and Timeline, and the name of
+  the settings section: *Settings → Visual Experience*.
+- **`mode: "builder"`** (SDK option) and **`visual_builder.onboarding-setup-visible`** (stack
+  setting) keep their names. Do not rename them in an answer.
 
 ## User Problem
 
-The same complaint has many unrelated causes. "Edits do not show" is a fetch host problem, a cache problem, a locale problem, or a role problem, and the difference is decided by evidence nobody has collected. Guessing produces a long thread of speculative fixes.
-
-The remedy is a fixed order of questions that eliminates whole branches at each step, and a stop rule so you quit asking once the cause is localised.
+Setup instructions reconstructed from memory drift from the documentation and miss the requirements
+that differ per rendering mode. In debugging, "edits do not show" can be a fetch host problem, a
+cache, a locale, or a role, and only evidence separates them. Guessing produces a long thread of
+speculative fixes.
 
 ## Success Criteria
 
-- Works the intake protocol in order rather than jumping to a plausible cause
-- Establishes the product first, because the three do not share a setup or a check
-- Asks for the Onboarding Check before anything else, and uses what its result already proves
-- Never asks a question the evidence has already answered
-- Stops collecting once one contract is localised
-- Uses the documentation for setup and the failure catalogue for debugging
-- Recognises causes outside the user's application and points the user to Contentstack Support instead of debugging
+- Works the steps in order and reports the checklist back ticked
+- For a new integration, links the documentation page for the framework and mode instead of
+  inventing steps, and does not ask diagnostic questions about code that does not exist yet
+- Reads the Onboarding Check before any other diagnostic question
+- Never asks for what the code or earlier evidence already answers
+- Names one broken contract, with evidence, before proposing a change
+- Recognises causes outside the application and hands them to Contentstack Support
 
 ## Expected Inputs
 
-Collected in the order set out below, not all at once. Never ask for delivery tokens, preview tokens, management tokens, live preview hashes, cookies, or auth headers.
+Collected step by step, never all at once. Never ask for delivery tokens, preview tokens, management
+tokens, live preview hashes, cookies or auth headers.
 
 ## Expected Outputs
 
-- The broken contract or mechanism, and the evidence for it
+- For a new integration: the documentation page, the requirements that apply, and how to verify
+- For a failing one: the broken contract and the evidence for it
 - The smallest correct change, or a plain statement that no application-side fix exists
-- A verification the user runs themselves
-- What to send Contentstack Support, when the cause sits outside the user's code
+- One verification the user runs
+- A Support handover note when the cause is outside the application
+
+## Example User Requests
+
+- "What does the Onboarding Check actually verify?"
+- "How do I set up Live Preview in our Next.js App Router site?"
+- "We have Live Preview working. What do we add for Visual Builder?"
+- "Live Preview loads but my edits never show up."
+- "The preview pane is blank / says it could not connect."
+- "Visual Builder shows Setup Complete but I can't click anything."
+- "Preview worked yesterday and now shows published content."
+- "Timeline always shows the current version."
+
+## Rules
+
+Follow these on every turn that diagnoses a failure.
+
+1. **Stop rule.** Once one contract is localised, stop collecting evidence and move to the fix.
+2. **Observed beats intended.** The Onboarding Check reports what the deployed build did; the code
+   reports what it intends. When they disagree, the check wins.
+3. **Falsification rule.** Before acting on a diagnosis, name the one artifact that would contradict
+   it, and get it.
+4. **Reproduction rule.** No code change without a reproduced failure. State the contract, the
+   evidence, and the action that reproduces it. No reproduction means a hypothesis: keep collecting.
+5. **Transition rule.** Worked then broke, a gate that advanced then regressed, a new error replacing
+   an old one: restart at step 2 and ask what changed, including your own edits this session.
+6. **No resilience while diagnosing.** Add no fallbacks, retries or caches. A fallback to published
+   content hides the exact signal being debugged.
 
 ## Workflow Summary
 
-Work these as a checklist and report it back ticked. An unticked step is a visible gap the user
-can see and question; a silently skipped step is how a wrong diagnosis gets past both of you.
+Report this back ticked. An unticked step is a visible gap.
 
 - [ ] 1. Identify the product.
-- [ ] 2. Setup or regression.
-- [ ] 3. Read the Onboarding Check. Not skippable whenever a preview pane renders.
-- [ ] 4. Detect framework and rendering mode from the code.
-- [ ] 5. Collect only the evidence detection could not supply.
+- [ ] 2. Question, new integration, never worked, or regression? Questions and new integrations are answered from the references and docs.
+- [ ] 3. Read the Onboarding Check.
+- [ ] 4. Detect framework, rendering mode and fetch layer from the code.
+- [ ] 5. Collect only the evidence steps 3 and 4 did not settle.
 - [ ] 6. Localise to one contract.
-- [ ] 7. Fix, verify, or hand to Contentstack Support.
+- [ ] 7. Fix and verify, or hand to Contentstack Support.
 
 ## Instructions
 
-Work these in order. Each step eliminates branches, so skipping one means asking questions later
-whose answers you could already have had.
-
-**Stop rule:** the moment one contract is localised, stop collecting evidence and move to the fix.
-Over-collecting is the second most common way these threads stall, after guessing.
-
-**Falsification rule:** before acting on a diagnosis, name the one artifact that would contradict
-it, and go get it. Confidence is the cue to do this, not the excuse to skip it. The commonest miss is
-a mode assumption: the code reads one way, and the Onboarding Check card or the network tab says
-otherwise. When they disagree, the observed behaviour wins over the intended one.
-
-**Reproduction rule:** no code change without a reproduced failure. Before editing application code,
-state the contract you believe is broken, the evidence for it, and the command or action that
-reproduces the failure. If you cannot reproduce it, you have a hypothesis, not a diagnosis. Keep
-collecting. A fix that "works" without a reproduced baseline may be working for a reason you have not
-identified, and you will not know which.
-
-**Transition rule:** any transition restarts at step 2. Worked then broke, a gate that advanced then
-regressed, a new error replacing an old one: each is a regression from a known state, and the first
-question is what changed since it last worked. Include your own edits in that question, not only the
-user's. Mid-session, the change most likely to have caused a transition is the one you just made, and
-it is also the one you are least likely to suspect. An Onboarding Check gate that goes backwards is
-information, not flakiness; do not answer it with a reload.
-
-**No-resilience rule:** while diagnosing, add no fallbacks, retries, caches, or optimisations.
-Falling back to published content when the preview fetch fails shows an editor published content
-while they believe they are looking at their edit, and hides the very signal being debugged. Fail
-visibly. If SDK-prescribed behaviour looks improvable, find the guard the SDK already has for that
-concern before changing anything; it usually exists.
-
 ### Step 1. Which product?
 
-Ask explicitly. Users say "preview" for all of them, and they do not share a setup path, an
-Onboarding Check, or a failure set.
-
-| Product | What it is | Notes |
-|---|---|---|
-| **Live Preview** | Side-by-side preview pane, content refresh only | The base. Everything else builds on it. |
-| **Visual Editor** (a.k.a. Visual Builder) | Live Preview plus on-canvas editing | Requires working Live Preview **plus** edit tags **plus** `mode: "builder"` in `init()`. `mode: "preview"` fails its Verify Mode gate even with tags present. Not a separate integration. |
-| **Timeline** | Preview at a point in time | Own Onboarding Check with different gates. |
-| **Preview Sharing** | Share a preview link externally | Plan-gated, and a content-manager feature rather than an integration. The skill carries no troubleshooting for it; point at [Preview Sharing](https://www.contentstack.com/docs/content-managers/preview-sharing). |
-
-If the user is on Visual Editor, confirm whether plain Live Preview works. If it does not, that is
-the problem, and the Visual Editor symptom is downstream noise.
+Ask explicitly. Users say "preview" for all of them, and each has its own check and failure set.
 
-### Step 2. Setup, or regression?
-
-Ask: has this ever worked correctly, for anyone, on any route?
-
-**Never worked** goes to [references/setup-docs.md](references/setup-docs.md). Follow the official
-documentation for the framework and mode. Do not reconstruct setup steps from memory. Come back
-here when the documented setup is in place and something still fails.
-
-**Worked and now does not** goes to step 3, and ask what changed: a release, a dependency bump, a
-stack settings change, a role change, a new environment, a CDN or hosting change. This question is not
-only for intake. Every transition during the session, such as a gate that advanced and then regressed
-or a new error replacing the old one, comes back here, and the list of changes must include every
-edit you made since the last known-good state, not only the user's.
+| Product | What it is |
+|---|---|
+| **Live Preview** | Preview pane with content refresh. Everything else builds on it. |
+| **Visual Editor** | Live Preview plus on-canvas editing. Needs edit tags **and** `mode: "builder"` in `init()`. |
+| **Timeline** | Preview at a point in time. Needs `preview_timestamp` forwarded with the hash. |
+
+On Visual Editor or Timeline, confirm plain Live Preview works. If it does not, that is the problem.
+
+### Step 2. Question, new, never worked, or regression?
+
+- **A question about how something works, not a failure** ("what does the Onboarding Check
+  verify?", "does Timeline need anything extra?", "what is the difference between Live Preview and
+  Visual Builder?"): answer it from the relevant reference file and link the documentation page.
+  No diagnostic intake. If the answer reveals a failure, continue at step 3.
+- **Nothing integrated yet, or adding Visual Editor or Timeline:** read the framework and rendering
+  mode from the code, give the matching documentation page and the requirements that apply from
+  [references/setup-docs.md](references/setup-docs.md), and stop there. Do not ask diagnostic
+  questions about code that does not exist yet. When the user has it in place, continue at step 3 to
+  verify.
+- **Integrated, never worked:** continue at step 3.
+- **Worked, now broken:** ask what changed (release, dependency bump, settings, role, environment,
+  CDN or hosting), then continue at step 3.
 
 ### Step 3. Read the Onboarding Check
 
-Ask for a **screenshot** of the floating status card in the preview panel. Do this before any other
-diagnostic question. The product already ran the check you are about to run by hand.
+Ask for a **screenshot** of the check in the preview panel, before any other diagnostic question.
+Code access does not excuse this step. Users paraphrase step names, and each name maps to one gate.
+If the user already quoted a card or item name that matches the tables below word for word, use it
+and skip the screenshot.
 
-**This step is not skippable when a pane renders at all, and repository access does not excuse it.**
-Step 4 reads the code and tells you what the integration *intends*; the card tells you what the editor
-*observed* on the actual deployed build. They can disagree, most often on rendering mode, and when
-they do the card is the one that reflects reality. Do step 3 first, then let step 4 explain it.
+All three products evaluate their gates as a chain that stops at the first failure. **Read the first
+failing item. Everything before it passed; everything after it never ran.**
 
-Ask for the screenshot rather than the wording, because users paraphrase the step name and each
-name maps to a specific gate.
-
-Three products, three different checks. Confirm the product first. Full gate lists and meanings are
-in [references/onboarding-check.md](references/onboarding-check.md).
-
-**Live Preview** shows one card. The gates run as one ordered chain that stops at the first failure,
-so the step shown proves every earlier gate passed:
+Live Preview shows one card:
 
 | Card | Localises to |
 |---|---|
-| Could Not Connect to Website | Frame headers, auth gate, Base URL, certificate, browser blocking localhost |
-| Live Preview SDK Not Initialized | `init()` never ran on the client in the deployed build |
-| Outdated Live Preview SDK Version | Version below the supported minimum |
-| Preview Service Not Enabled | The fetch never switched host and headers |
-| Default Environment Not Set | Setup is fine; no default preview environment on the stack |
-| Setup Complete | Reachability, handshake, version and Preview Service are all fine |
-
-**Visual Editor shows a six-item list, not a card**, but it still stops evaluating at the first item
-that fails, so read the first incomplete item and ignore the ones under it. Configure environment
-(Default Environment, Base URL), Install SDK, Verify Mode for Live Preview, Preview Token. Two of these bite
-customers who arrived from a Live Preview setup: Verify Mode fails on `mode: "preview"` (Visual
-Editor needs `mode: "builder"`), and Base URL is origin-exact against the page being previewed.
-
-**Timeline runs a third check.** A small status card while it runs, then a full-pane "Set Up
-Timeline" overlay with three items once one fails. The items are chained, so the first empty circle
-is the failure and the ones below it never ran:
-
-| Overlay item | Localises to |
-|---|---|
-| Configure the environment | No environment on the Timeline URL and no default preview environment on the stack |
-| Install the latest Live Preview SDK | The `init()` handshake never reached Timeline, or the SDK major version is below 2 |
-| Generate and use Preview Token | No content request reached the Preview Service before the check stopped waiting |
+| Could Not Connect to Website | Network-level failure only: wrong or unreachable Base URL, DNS, bad certificate, mixed content, the browser blocking localhost |
+| Live Preview SDK Not Initialized | No init handshake: `init()` never ran on the client, `enable` not truthy, **or the frame is blank** (frame headers, an auth or password screen) |
+| Outdated Live Preview SDK Version | SDK below 1.4.0 |
+| Preview Service Not Enabled | Content fetch never switched to the preview host and headers |
+| Default Environment Not Set | Integration fine; the stack has no default preview environment |
+| Setup Complete | Reachability, handshake, version and Preview Service all fine |
 
-The overlay appears ten seconds after the last status change, and item 3 gives up waiting at about
-nine, so a slow site can show an empty circle on a correct setup. Have the user reopen the panel on a warm cache
-before believing it.
+Visual Editor and Timeline show a status card while checking, then a full-pane overlay ("Set Up
+Visual Editor", "Set Up Timeline") listing their items. Gates, verbatim item text and timing are in
+[references/onboarding-check.md](references/onboarding-check.md). The two Visual Editor items that
+catch users coming from a Live Preview guide: **Verify Mode for Live Preview** fails on
+`mode: "preview"`, and **Validate the Base URL** needs the Base URL origin to match the previewed page
+exactly.
 
-Two readings that decide the whole branch:
+Two readings decide the branch:
 
-- **Setup Complete, but nothing is editable.** The check never inspects `data-cslp`. This is edit
-  tags, every time. Go to contract 2 in step 6.
-- **No card at all.** Absence is not a pass. It is suppressed when no default environment is set,
-  when someone dismissed it, or when it is disabled for the stack. Verify the contracts by hand.
+- **Setup Complete, nothing editable.** The check never inspects `data-cslp`. Go to contract 2.
+- **Setup Complete, only fields from referenced entries not editable.** Tags are not rebased to the
+  referenced entry: `cslp-not-rebased-to-referenced-entry` in faq-visual-editor.md.
+- **No check at all.** Absence is not a pass. See "When the check does not appear" in
+  onboarding-check.md, then verify the contracts by hand.
 
-### Step 4. Establish framework and rendering mode
+### Step 4. Detect framework, mode and fetch layer
 
-**Detect this, do not ask for it.** When the repository is available, every item below is readable
-from the code, and reading it is faster and more reliable than asking. Detection does not replace
-step 3: the card still comes first, because it reports the deployed build rather than the branch you
-are reading. Developers routinely answer
-"Next.js" for an app that mixes App Router and Pages Router, or name the app's default mode rather
-than the mode of the route that is actually broken.
+Read the code instead of asking. State what you found and ask only for confirmation.
 
-Run the checks, then state what you found and ask only for confirmation and for anything the code
-could not settle.
-
-| Question | Where to look | What it tells you |
+| Check | Where | Why |
 |---|---|---|
-| Framework and version | `package.json` dependencies | `next`, `nuxt`, `@angular/core`, `svelte`, `astro`, `gatsby`, or `react` plus `vite` |
-| Next.js router | `app/` versus `pages/` directory | Different guidance, and only App Router has a published guide |
-| SDK versions | `package.json`, lockfile | Against the minimums in Tooling Notes |
-| One SDK copy | lockfile, plus any `<script type="module">` in the HTML | An npm install alongside a CDN import of another version behaves like a config bug |
-| Rendering mode of the route | `export const dynamic`, `revalidate`, `getStaticProps`, `getServerSideProps`, `output: "export"` | The mode of that route, which is what matters |
-| `ssr` setting | the `init(` call site | Explicit value, or absent and therefore inferred |
-| `stackSdk` passed | the `init(` call site | Mandatory in CSR, and what the SDK uses to default `ssr` |
-| Init placement | the file containing `init(`, and whether it is `"use client"` | Contract 1. Server-only placement is the most common Next.js miss |
-| Edit tags | `addEditableTags` | Contract 2. Absent means Visual Editor cannot work, whatever else is true |
-| Fetch layer | `@contentstack/delivery-sdk` import, raw `fetch`, or a GraphQL client | Decides which form of contract 3 applies |
-| Preview host wiring | `preview_token`, `live_preview`, any hostname constant | Contract 3 |
-| Cache posture | `fetch` cache options, `revalidate`, CDN or middleware config | The "works locally, fails deployed" class |
-
-That sweep usually settles contracts 1, 2 and 3 in step 6 before you ask the user anything, and it
-often makes step 5 unnecessary.
-
-Two things the repository cannot tell you. Ask for these:
-
-1. **Where it is served**: localhost, a preview deployment, or production.
-2. **Whether the deployed build matches the branch you are reading.** An environment variable that
-   does not parse as a boolean, or a stale deploy, makes correct-looking code behave as if init
-   never ran.
-
-Without repository access, ask for the same list, in this order: framework and version, the mode of
-the affected route, the fetch layer, and the `init()` call site.
-
-The SDK ships no framework adapters, no framework peer dependencies, and no per-framework code
-paths. Framework choice decides only where `init()` may run and whether hydration preserves edit
-tags. Everything else follows from mode and fetch layer.
-
-| Mode | `ssr` | Hash travels via | Updates arrive as |
+| Framework, router | `package.json`; `app/` vs `pages/` | Decides where `init()` may run |
+| SDK versions, one copy | `package.json`, lockfile, any `<script type="module">` | Two copies behave like a config bug |
+| Route's rendering mode | `dynamic`, `revalidate`, `getStaticProps`, `getServerSideProps`, `output: "export"` | The broken route's mode, not the app default |
+| `ssr` | `init(` call site **and** the Stack's `live_preview.ssr` | Stack config overrides `init({ ssr })` |
+| `stackSdk`, `mode` | `init(` call site | `stackSdk` absent defaults `ssr` to `true` |
+| Init placement | file containing `init(`, `"use client"` | Contract 1 |
+| Edit tags | `addEditableTags` | Contract 2 |
+| Fetch layer, host wiring | Delivery SDK, raw `fetch`, GraphQL client; `preview_token`, `live_preview`, hosts | Contract 3 |
+| Cache | fetch cache options, `revalidate`, CDN or middleware | "Works locally, fails deployed" |
+
+The code cannot tell you where the site is served or whether the deployed build matches the branch.
+Ask for both.
+
+Mode decides how updates arrive:
+
+| Mode | `ssr` | Hash reaches the fetch via | Updates |
 |---|---|---|---|
-| CSR + REST | `false` | postMessage, into `stackSdk` | `onEntryChange` refetch, no reload |
-| SSR + REST | `true` | `live_preview` query parameter | full iframe reload, driven by the parent. `onEntryChange` subscribers **never fire** in this mode |
-| CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch, manual host swap |
-| SSR + GraphQL | `true` | `request.query.live_preview` | full reload, manual host swap |
-| SSG | `false` | postMessage | runs as CSR at runtime |
-
-**`onEntryChange` is inert under `ssr: true`.** The SDK guards its entry-change dispatch on `!ssr`,
-so any subscriber registered in an SSR app never runs. Registering one to trigger a refetch or
-`router.refresh()` produces a callback that looks correct and does nothing. Under `ssr: true` the
-update path is the parent reloading the iframe with the new hash; the app's only job is to read the
-hash off that request. If you want client-driven refresh, the route has to be CSR (`ssr: false`).
-
-`stackSdk` is mandatory in CSR and is what the SDK uses to default `ssr`. A CSR app that omits it
-silently gets SSR behaviour; an SSG site initialised with `ssr: true` gives blank screens rather
-than an error. Two mode traps to check before prescribing: **SSR** needs a per-request Stack
-instance, because a module-level one leaks one editor's draft into other users' responses; **SSG** is
-supported, but only in CSR mode: a prerendered page never sees the `live_preview` query parameter,
-so the documented setup is `ssr: false` with `stackSdk`, where the hash arrives by postMessage
-instead. **ISR** is the harder case: a regenerated page is still a cached page, and caching has to be off
-on the preview path. There is no published recipe for combining ISR with Live Preview.
-
-Detail and the framework coverage table are in
-[references/rendering-modes.md](references/rendering-modes.md); init placement per framework is in
+| CSR (incl. SSG at runtime) | `false` | postMessage into `stackSdk`; `ContentstackLivePreview.hash` for GraphQL | `onEntryChange` refetch |
+| SSR | `true` | `live_preview` query parameter on the request | Parent reloads the iframe; `onEntryChange` never fires on edits |
+
+Detail per mode, including SSG, ISR and GraphQL, is in
+[references/rendering-modes.md](references/rendering-modes.md). Init placement per framework is in
 [references/frameworks.md](references/frameworks.md).
 
-### Step 5. Collect logs and one request
-
-Only for what step 4 could not settle. With repository access the contracts are often already
-localised, and the single most valuable item left is the request host. Skip whatever you can
-already answer, and ask for the rest in one pass rather than one at a time.
-
-1. **Browser console, with the preview panel open.** Look for the init handshake, CSP or frame
-   refusals, CORS failures, and framework hydration errors. Ask them to reproduce with the console
-   open, because most of these fire once at load. Read it against the noise list below before
-   drawing any conclusion.
-2. **Server-side logs**, for SSR, middleware, BFF, or proxy setups. This is where a swallowed
-   preview fetch error lives, and it is invisible in the browser. Skip for pure CSR.
-3. **One failing request from the Network tab**: full request URL and host, response status, and
-   response headers. Redacted.
-
-**Check the console output against [references/console-noise.md](references/console-noise.md)
-before concluding anything from it.** Preview runs the site in an iframe with postMessage between
-two apps, so a healthy setup still produces console chatter — `NO_REQUEST_LISTENER_FOUND` and third-party script errors both appear on working
-integrations. If one of those is the only thing in the console, you have no console evidence, not
-evidence of a problem.
-
-The request host alone settles the most common failure of all. During an active preview
-session, content coming from `cdn.contentstack.io` or `graphql.contentstack.com` means the hash is
-not reaching the fetch, regardless of the reported symptom.
-
-Also ask, in one line each, the questions that separate causes:
-
-- **One user or everyone?** One user points at their role. Preview runs as that user and applies
-  their full ACL — content types, entries, fields, locales, assets — so anything they cannot read
-  comes back empty. Delivery uses a delivery token and applies none, which is why the published
-  page looks fine. This is by design: the fix is usually defensive rendering on the site, not a
-  product issue.
-- **Localhost or deployed?** Working locally and failing deployed is a cache on the preview path,
-  or a frame header.
-- **Consistent or intermittent?** Intermittent and user-dependent under SSR is a shared
-  module-level Stack instance. That one reaches public traffic.
-- **Which locale, and which variant?** Both change the fetch, and both are common false leads.
+### Step 5. Collect what is still open
 
-### Step 6. Localise to one contract
+Ask for the rest in one message, skipping anything already settled:
+
+1. **Browser console** with the preview panel open, reproduced after a reload. Check it against
+   [references/console-noise.md](references/console-noise.md) first: some messages appear on
+   healthy setups and are not evidence.
+2. **Server logs**, for SSR, middleware, BFF or proxy setups. A swallowed preview fetch error lives
+   here.
+3. **One content request from the Network tab**: host, status, response headers, redacted. A
+   delivery CDN host for the stack's region during a preview session means the hash is not reaching
+   the fetch, whatever the symptom.
 
-A working integration needs four independent contracts. They fail separately and complain
-identically. Name which one is unmet, with the evidence, before proposing anything.
+And, one line each: one user or everyone (one user points at their role), localhost or deployed
+(deployed-only points at a cache or frame header), consistent or intermittent (intermittent under SSR
+points at a shared Stack instance), which locale and variant.
+
+### Step 6. Localise to one contract
 
 | # | Contract | One-look check |
 |---|---|---|
-| 1 | `init()` runs, on the client, in the deployed build | The Live Preview Onboarding Check moves past "Live Preview SDK Not Initialized" — that item clears only when the SDK's init message reaches the app, which happens only from `init()` |
-| 2 | Edit tags are generated and land on DOM elements | Some rendered element carries `data-cslp` |
-| 3 | The hash reaches the fetch, which switches host plus headers | Content requests hit a `*-preview.contentstack.com` host |
-| 4 | The preview target is reachable in an iframe | The pane renders at all |
-
-Contract 1 gates 2 and 3. Contract 4 gates everything. Steps 3, 4 and 5 have usually already decided
-this; if they have, do not re-derive it.
-
-For contract 2, the one the Onboarding Check cannot see:
-
-```jsx
-addEditableTags(entry, contentTypeUid, true, locale);
-<h1 {...data.$?.title}>{data.title}</h1>
-```
-
-`mode: "builder"` does not generate tags; only `addEditableTags()` does. (`mode: "builder"` is
-still required, because Visual Editor's Verify Mode gate fails on `mode: "preview"`.) The call
-mutates the entry and returns nothing, and the third argument must be `true` for React and JSX.
-Call it once per top-level entry: references resolved with `includeReference()` or `include[]`
-carry `uid` and `_content_type_uid`, and their tags are rebased to the referenced entry
-automatically. A separate call is needed only for references merged by hand, or GraphQL nodes
-fetched without `system`. Mirror the data path exactly, because references come back as arrays:
-`post.author[0].$?.name`, not `post.$?.author.name`.
-
-Tag leaves **and** containers. A scalar takes `entry.$.field` on the element that renders the value.
-Multiple fields, references and modular blocks take `entry.$.field` on the wrapper plus
-`entry.$["field__" + i]` on each instance; the canvas attaches add and reorder controls only when
-an instance sits inside an element carrying the container tag. An empty multiple or block field
-keeps its wrapper in the DOM while previewing, marked with `VB_EmptyBlockParentClass` and the
-container tag, or the canvas has nothing to draw its add button on.
-
-Enumerate fields from `Object.keys(entry.$)` and diff against what the page renders. Do not eyeball
-the JSX. The full key convention and a per-field-kind checklist are in
-[references/edit-tags.md](references/edit-tags.md).
-
-For contract 3:
-
-```js
-// SSR reads it from the request. CSR uses ContentstackLivePreview.hash.
-const livePreviewHash = request.query.live_preview;
-
-if (livePreviewHash) {
-  headers.append("live_preview", livePreviewHash);
-  headers.append("preview_token", PREVIEW_TOKEN);
-  url.hostname = LIVE_PREVIEW_HOST;   // rest-preview.contentstack.com
-} else {
-  url.hostname = CONTENTSTACK_CDN_HOST; // cdn.contentstack.io
-}
-```
-
-If the symptom is behavioural rather than a failed contract, look it up in
-[references/symptom-index.md](references/symptom-index.md), which routes to
-[faq-setup.md](references/faq-setup.md),
-[faq-preview-runtime.md](references/faq-preview-runtime.md),
-[faq-visual-editor.md](references/faq-visual-editor.md), and
-[faq-timeline.md](references/faq-timeline.md).
-
-For a first-time setup or an end-to-end sweep,
-[references/preflight-checklist.md](references/preflight-checklist.md) runs the contracts as 34
-ordered checks.
-
-### Step 7. Fix, verify, or hand to Contentstack Support
-
-Before proposing any change, satisfy the reproduction rule: contract, evidence, and the action that
-reproduces the failure, stated in that order. Then propose the smallest correct change at the right
-layer: init, tagging, fetch, cache boundary, routing, or stack configuration, and give one verification
-the user runs themselves. The verification is the reproduction step run again with the opposite
-result.
-
-Some causes sit outside the user's application entirely: stack provisioning, plan gating, and
-browser policy. Recognising one early beats any workaround, because no change to the site can
-resolve it. See [references/contact-support.md](references/contact-support.md) for the list, and
-**produce the handover note it defines** — filled from what steps 1–6 already collected — for the
-user to paste into their ticket to Contentstack Support.
+| 1 | `init()` runs on the client in the deployed build | Live Preview check gets past "Live Preview SDK Not Initialized" |
+| 2 | Edit tags are generated and land on DOM elements | Rendered elements carry `data-cslp` |
+| 3 | The hash reaches the fetch, which switches host and headers | Content requests hit the region's `*-preview` host |
+| 4 | The site is reachable in an iframe | The pane renders at all |
+
+Contract 4 gates everything; contract 1 gates 2 and 3. Name the unmet one with its evidence.
+
+- Contract 2 detail, key conventions and the empty-block contract:
+  [references/edit-tags.md](references/edit-tags.md).
+- Behavioural symptoms: look them up in [references/symptom-index.md](references/symptom-index.md),
+  which routes to [faq-integration.md](references/faq-integration.md),
+  [faq-preview-runtime.md](references/faq-preview-runtime.md),
+  [faq-visual-editor.md](references/faq-visual-editor.md) and
+  [faq-timeline.md](references/faq-timeline.md).
+
+### Step 7. Fix and verify, or hand over
+
+State contract, evidence and reproduction, then the smallest change at the right layer: init, tags,
+fetch, cache, routing, or stack configuration. The verification is the reproduction run again with
+the opposite result.
+
+Some causes sit outside the application: provisioning, plan gating, browser policy. No site change
+fixes them. See [references/contact-support.md](references/contact-support.md) and produce its
+handover note from what steps 1 to 6 already collected.
 
 ## Output Format
 
-Lead with the broken contract or mechanism and the evidence for it. Then the smallest correct
-change, as a snippet or diff, or a plain statement that no application-side fix exists. Then one
-verification. Attach mode-specific caveats to the step they affect.
+New integration: follow "Reply shape" in [references/setup-docs.md](references/setup-docs.md).
+
+Failing integration: lead with the broken contract and its evidence. Then the smallest change as a snippet or diff, or a
+plain statement that no application-side fix exists. Then one verification.
 
-When you still need evidence, ask for the specific artifact that separates the remaining
-candidates, and say what each possible answer would mean. Do not send a generic list of requests.
+When evidence is still missing, ask for the one artifact that separates the remaining candidates and
+say what each answer would mean.
 
-Say when a behaviour applies only to preview and not production, and say the reverse too, because
-preview output reaching real visitors is a production incident rather than an authoring annoyance.
+Say whether a behaviour applies to preview only or to production too. Preview output reaching real
+visitors is a production incident.
 
 ## Tooling Notes
 
-Read-only inspection first, with Read, Grep and Glob when the repository is available. Useful
-greps: the `init(` call site, `addEditableTags`, `onEntryChange`, `live_preview`, `preview_token`,
-any hostname constant, and cache configuration on the preview route.
+Read-only inspection with Read, Grep and Glob. Useful greps: `init(`, `addEditableTags`,
+`onEntryChange`, `live_preview`, `preview_token`, hostname constants, cache configuration.
 
-Minimum versions: Live Preview Utils v3.0+ and Delivery SDK v3.20.3+ for Visual Editor, and Live
-Preview Utils v4.4.4+ for `setPageContext()`. Confirm exactly one copy of the preview SDK is
-loaded.
+Minimum versions: Live Preview Utils v3.0+ for Visual Editor (legacy `contentstack` JavaScript SDK
+v3.20.3+); Live Preview Utils v4.4.4+ for `setPageContext()`.
 
-When the repository is not available, run the same protocol against described code and screenshots.
-Do not pretend to have inspected code.
+Without repository access, run the same steps against described code and screenshots. Do not claim
+to have inspected code.
 
 ## Security
 
 ### Defaults
 
-- Never expose delivery tokens, preview tokens, management tokens, or environment secrets.
-- Treat preview tokens and live preview hashes as credentials. Do not ask users to paste them, and
-  redact them if they appear. Ask for redacted logs and screenshots.
-- A management token in client-side Live Preview configuration is an exposure.
+- Never ask for, echo or reconstruct tokens or live preview hashes. Ask for redacted logs and
+  screenshots. If a secret appears, tell the user to rotate it.
+- A management token in client-side configuration is an exposure.
 - Do not recommend enabling Live Preview in production builds. An edit button on a public site is a
   symptom of exactly that.
-- Preview output served to real visitors is a production data-exposure issue, not a cosmetic bug.
-- Validate preview target hosts before suggesting header or CSP changes.
+- Validate preview target hosts before suggesting header or CSP changes, and scope any relaxation to
+  the preview deployment.
 
 ### Destructive Actions
 
-Do not change stack settings, roles, tokens, cache configuration, or environment configuration
-automatically. Propose the change, state the blast radius, and require confirmation.
-
-### Secrets
-
-Never reveal, echo, or reconstruct tokens or hashes. If a secret appears in provided input, tell
-the user to rotate it.
+Do not change stack settings, roles, tokens, cache or environment configuration automatically.
+Propose the change, state the blast radius, and require confirmation.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md b/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
index 2d609f0..c629387 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
@@ -13,12 +13,16 @@ problem.** Say so and move to the network tab.
 
 ## The list
 
-### `NO_REQUEST_LISTENER_FOUND` / `No ack listener found`
+### `NO_REQUEST_LISTENER_FOUND` and `No ack listener found`
 
-Routine. It means a postMessage arrived with no registered listener, which happens normally during
-load and teardown. Appears on working setups.
+Two different postMessage errors from the same library, both routine:
 
-Never conclude anything from it on its own. It does not affect SSR content, and it is not evidence
+- `NO_REQUEST_LISTENER_FOUND` ("No request listener found for event …"): one side sent a request
+  the other side has no handler for, for example a `scroll` event during load.
+- `No ack listener found`: an acknowledgement arrived after its sender stopped waiting, typically
+  during load or teardown.
+
+Both appear on working setups. Never conclude anything from either on its own. It does not affect SSR content, and it is not evidence
 that the handshake failed — read the Live Preview Onboarding Check instead, which sticks on **Live
 Preview SDK Not Initialized** until the SDK's init message arrives.
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md b/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
index db17626..b0ba0b4 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
@@ -20,7 +20,7 @@ with Contentstack Support.
 | Symptom | What it actually is |
 |---|---|
 | A previously working `localhost` preview stops working, console shows a local network access error | Chrome's Local Network Access policy now blocks the app origin from framing localhost. Only the user can grant the permission, in the browser. |
-| Preview pane blank, and the site sits behind platform password protection or third-party SSO | Those screens set `X-Frame-Options: DENY` on themselves. Contentstack cannot inject headers into a browser-originated iframe request. Workarounds, cheapest first: enable **Open in New Tab**, which renders the site outside the iframe so frame headers stop applying; otherwise disable protection on the preview deployment, put a bypass token in the Base URL, or front it with a server-side proxy that strips the header. |
+| Preview pane blank, and the site sits behind platform password protection or third-party SSO | Those screens set `X-Frame-Options: DENY` on themselves. Contentstack cannot inject headers into a browser-originated iframe request. Workarounds, cheapest first: enable **Open in New Tab**, which renders the site outside the iframe so frame headers stop applying; otherwise disable protection on the preview deployment, put a bypass token in the Base URL (scoped to the preview deployment and rotated, since every stack user can read it), or front it with a server-side proxy that strips the header. |
 | Ad slots, consent widgets, or other host-dependent third-party scripts misbehave in the pane | Those scripts key off the top-level origin, which is the Contentstack app inside an iframe. Expected, not a preview defect. |
 
 ## How to hand it over
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md b/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
index f045012..2a5d030 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
@@ -12,12 +12,15 @@ addEditableTags(entry, contentTypeUid, true, locale /*, { useLowerCaseLocale: fa
 
 - Mutates the entry and returns nothing. It attaches a `$` object at every level: the entry, each
   group, each block instance, and each resolved reference.
-- Call it **once per top-level entry**. A resolved reference that carries `uid` and
+- Call it **once per top-level entry**. A resolved reference that carries top-level `uid` and
   `_content_type_uid` (which `includeReference()` and REST `include[]` preserve) gets its own `$`,
   rebased to the referenced entry: `author.<author_uid>.<locale>.title`, not
-  `blog_post.<post_uid>.<locale>.author.0.title`. A separate call per referenced entry is needed
-  only when references were fetched separately and merged by hand, or when a GraphQL query omitted
-  `system { uid content_type_uid locale }`.
+  `blog_post.<post_uid>.<locale>.author.0.title`. The locale segment is the reference's own
+  `locale` when it has one. A separate call per referenced entry is needed when references were
+  fetched separately and merged by hand.
+- **GraphQL never rebases on its own.** A GraphQL node nests `uid` and `content_type_uid` under
+  `system`, and references sit under `edges[].node`, so the rebase condition is never met. Normalise
+  the response first (see `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md`).
 - The third argument must be `true` in React and JSX so the values are objects you can spread.
 - `locale` and `contentTypeUid` are lowercased; pass `{ useLowerCaseLocale: false }` for stacks with
   mixed-case locale codes.
@@ -104,9 +107,11 @@ Hover and click on the marked wrapper draw no outline; the button is the afforda
 ## Variants
 
 Highlight Variant and audience mode key on v2 tags:
-`v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>`. `addEditableTags()` emits them only for fields
-listed in the entry's `_applied_variants`, and the response includes that map only when the request
-carries `include_applied_variants=true`. Pass it as a query parameter on the content request:
+`v2:<ct>.<entry_uid>_<variant_uid>.<locale>.<field>`. `addEditableTags()` emits them for fields
+listed in the entry's applied-variants map (`_applied_variants`, or `system.applied_variants`) and
+for fields nested under a listed path. Each referenced entry uses its own map, not the parent's. The
+response includes the map only when the request carries `include_applied_variants=true`. Pass it as
+a query parameter on the content request:
 
 ```js
 // Honoured: a query parameter on the request itself
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
similarity index 84%
rename from skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
rename to skills/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
index d08f67d..36bde9a 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
@@ -1,14 +1,14 @@
-# Setup FAQ
+# Integration FAQ
 
-Setup and first-integration failures, ordered by how often they come up in practice. Each entry
-gives the symptom as users actually report it, the mechanism behind it, the fix, and a
-verification step.
+Failures in an existing integration's wiring: reachability, init, edit tags, the fetch, hosts and
+stack configuration. Ordered by how often they come up. Each entry gives the symptom as users report
+it, the mechanism, the fix, and a verification step.
 
-Read this after localising the problem to one of the four contracts in the parent skill. The
-contract tells you which section to read; this file tells you what to do.
+Read this after localising the problem to one of the four contracts in SKILL.md. For first-time
+setup, use `setup-docs.md` instead.
 
 ### app-fetches-from-delivery-cdn-instead-of-preview-service
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Live Preview / Visual Editor loads the site fine, but edits made in the entry form or the right-hand panel never appear in the preview. Content only changes after the entry is published. The Onboarding Check gets past the site-loading and SDK gates and then stops on **Preview Service Not Enabled**. Variant selection in Visual Editor also shows the base entry.
 - **frameworks**: Next.js (Pages + App Router), React, Angular, Gatsby, Vue/Nuxt, Java/Spring, framework-agnostic REST/GraphQL clients
 - **rendering_modes**: any
@@ -35,22 +35,23 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### iframe-blocked-by-x-frame-options-or-csp-frame-ancestors
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: The Live Preview / Visual Editor pane is blank or shows "`<your-host>` refused to connect". Console shows `Refused to display '<url>' in a frame because it set 'X-Frame-Options' to 'sameorigin'` (or `deny`), or a `frame-ancestors` CSP violation. Frequently paired with a `401` on a `HEAD`/`GET` of the site root. Works on localhost, fails on the deployed dev/QA/staging host.
 - **frameworks**: framework-agnostic (server / CDN / hosting-platform header config)
 - **rendering_modes**: any
 - **root_cause**: Contentstack renders the site inside an iframe on the app origin. Any `X-Frame-Options: SAMEORIGIN|DENY` or a CSP `frame-ancestors` directive that does not include the Contentstack app origin makes the browser refuse the frame before the page can run. Platform-level deployment protection (for example a hosting provider's password protection) adds `X-Frame-Options: DENY` to the password screen itself, so even the auth prompt cannot render.
 - **fix**:
-  1. Remove `X-Frame-Options` for the preview host and use CSP instead: `Content-Security-Policy: frame-ancestors 'self' https://*.contentstack.com https://*.contentstack.io;` (`X-Frame-Options` has no allowlist syntax; a bare `SAMEORIGIN` always wins).
+  1. Remove `X-Frame-Options` for the preview host and use CSP instead, allowing the Contentstack app origin for the stack's region: `Content-Security-Policy: frame-ancestors 'self' https://app.contentstack.com;` (for example `https://eu-app.contentstack.com` in EU). `https://*.contentstack.com` is the broader fallback. `X-Frame-Options` has no allowlist syntax; a bare `SAMEORIGIN` always wins.
   2. Apply the header on every route, not just the site root. A route that redirects to a different hostname than the configured Base URL will also fail.
-  3. If the deployment sits behind platform password protection, note that no header or query parameter can be injected into a browser-originated iframe request from Contentstack. Options: disable protection on the preview deployment, use a bypass token embedded in the Base URL, put a server-side proxy in front that injects the header, or use Live Preview → Open in New Tab (a plan-gated feature that renders outside the iframe).
+  3. If the deployment sits behind platform password protection, note that no header or query parameter can be injected into a browser-originated iframe request from Contentstack. Options: disable protection on the preview deployment, use a bypass token embedded in the Base URL (every stack user can read the Base URL, so scope the token to the preview deployment and rotate it), put a server-side proxy in front that injects the header, or use Live Preview → Open in New Tab (a plan-gated feature that renders outside the iframe).
   4. Third-party SSO screens that themselves set `X-Frame-Options: DENY` cannot render in the iframe at all. Use Open in New Tab, which renders the preview outside the iframe so those screens can load.
+  5. On the Live Preview Onboarding Check this shows as **Live Preview SDK Not Initialized**, not "Could Not Connect to Website". The reachability gate is a `no-cors` request, which succeeds on any HTTP response, so frame headers and auth screens pass it.
 - **verification**: `curl -I https://<preview-host>/<some-deep-route>` and confirm no `X-Frame-Options` and a `frame-ancestors` value that includes the Contentstack app origin. Reload Live Preview; the pane should render.
 
 ---
 
 ### error-382-create-tracker-before-starting-live-preview-session
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Preview API requests fail with
   `{"error_message":"Please create tracker before starting live preview session","error_code":382,"status":400}`
   (a sibling variant is `{"error_message":"Please provide live preview hash in request","error_code":382}`). Often appears the moment `mode: "builder"` is set, or when the site is opened directly rather than from inside the Contentstack preview pane. Sometimes reproduces for one developer and not another on "identical" setups.
@@ -67,18 +68,18 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### edit-tags-not-generated-or-not-spread
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar. Clicking the canvas does nothing, or selects the wrong (parent) element. `entry.$` / `post.$` is `undefined` in the app, or `data-cslp` renders as literal text instead of an attribute. Live Preview auto-refresh often still works, which makes it look like a Visual Editor bug.
 - **frameworks**: React, Next.js, Vue, Angular, Gatsby, Blazor/.NET, jQuery
 - **rendering_modes**: any
 - **root_cause**: Tags need two independent things and teams usually do only one: `addEditableTags()` must run on every fetched entry, **and** the generated `$` attributes must be spread onto the DOM elements that render each field. `mode: "builder"` does not generate tags, but it is still required: Visual Editor's Verify Mode gate fails on `mode: "preview"`, so tags alone do not produce a canvas. Four ways this goes wrong: the call is missing entirely (commonly commented out during a migration); `tagsAsObject` is `false` or omitted, producing a `data-cslp` string React cannot spread; the content type **title** is passed instead of its **uid**; or the call is correct but nothing spreads the result into the markup.
 - **fix**:
-  1. Call it on every entry right after fetching, including referenced entries: `addEditableTags(entry, contentTypeUid, true, locale)`. The third argument must be `true` for React and JSX.
+  1. Call it once per top-level entry right after fetching: `addEditableTags(entry, contentTypeUid, true, locale)`. The third argument must be `true` for React and JSX. References resolved with `includeReference()` or `include[]` are tagged in the same call; only hand-merged references need their own call.
   2. Pass the content type **uid**, not its display title.
   3. Spread onto the element that renders the value: `<h1 {...post.$?.title}>{post.title}</h1>`.
   4. Mirror the data path exactly. References come back as arrays, so it is `post.author[0].$?.name`, not `post.$?.author.name`.
-  5. Tag the leaf element that holds the value, one `data-cslp` per element. Tagging a wrapper group instead of the field makes Visual Editor select the wrong field.
-  6. Check nothing strips them at build time: `cleanCslpOnProduction: true` removes `data-cslp` from the DOM, and `PURGE_PREVIEW_SDK=true` no-ops the whole SDK.
+  5. Put a scalar field's tag on the element that renders its value, not on a surrounding wrapper, or Visual Editor selects the wrong field. Multiple, reference and modular-block fields are the exception: their container tag goes on the wrapper and each instance gets its own `field__<index>` tag. See `edit-tags.md`.
+  6. Check nothing strips them: with `enable: false`, the default `cleanCslpOnProduction: true` removes `data-cslp` from the DOM, and `PURGE_PREVIEW_SDK=true` no-ops the whole SDK. A build that evaluates `enable` as false on the preview deployment loses its tags this way.
   7. For GraphQL, the response shape itself breaks tag paths — see `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md` for the normalizer that has to run before `addEditableTags()`.
   8. If you only want auto-refresh and not in-context editing, use `mode: "preview"` rather than `mode: "builder"` with no tags.
 - **verification**: In DevTools on the previewed page, `document.querySelectorAll('[data-cslp]').length` must be greater than 0, and a rendered field must carry `data-cslp="<content_type_uid>.<entry_uid>.<locale>.<field_path>"`. Hovering it in the canvas should highlight it, and clicking should focus the matching field in the form panel.
@@ -86,13 +87,13 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### preview-url-does-not-resolve-to-the-app-route
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited. Navigating inside the preview 404s. Sometimes the pane says "You are currently previewing a different webpage". Affects entries whose real URL is nested, taxonomy-driven, multi-tenant, or has no `url` field at all.
 - **frameworks**: Next.js, React, framework-agnostic
 - **rendering_modes**: any
 - **root_cause**: By default the preview URL is `environment Base URL` + the entry's `url` field. That only works when app routing maps 1:1 to the `url` field. Nested paths, custom route prefixes, several content types with different URL shapes, multiple sites served from one stack, or a URL stored in a custom text field instead of the built-in `url` field all break the concatenation.
 - **fix**:
-  1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL). This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated. Follow the docs for the pattern syntax, placeholders, Base URL aliases and defaults: [Custom Preview URLs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls).
+  1. Configure **Custom Preview URLs** (Settings → Visual Experience → Preview URL). This is the feature that decouples preview from `Base URL + entry.url`; it is plan-gated. Follow the docs for the pattern syntax, placeholders, Base URL aliases and defaults: [Custom Preview URLs](https://www.contentstack.com/docs/headless-cms/custom-preview-urls).
   2. With Custom Preview URLs enabled, tell the editor which entry each page is by calling `setPageContext({ entryUid, contentTypeUid })` on every page (Live Preview Utils v4.4.4+). Fallbacks: the `window.__CS_PAGE_CONTEXT__` global, or `<meta name="contentstack:entry-uid">` and `<meta name="contentstack:content-type-uid">`. **This only has an effect when the Custom Preview URLs setting exists for the stack and is configured.** Without it the editor resolves by URL alone and the call is silently ignored — it does not error, so a stack without the feature looks like `setPageContext` not working.
   3. Do not narrow the environment Base URL to one content type's prefix (for example `.../inspiration/articles/`) — that fixes one content type and breaks all others.
   4. Verify the entry's `url` field actually corresponds to a route the app serves, and that the route renders the content type you expect.
@@ -101,14 +102,14 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade
-- **bucket**: setup
-- **symptom**: Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump breaks a previously working integration — `setConfigFromParams` disappears, `ReferenceError: window is not defined` in server code, the Edit button suddenly renders in production, or `Live_Preview_SDK: To use edit tags, you must provide the stack API key`.
+- **bucket**: integration
+- **symptom**: Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump breaks a previously working integration: `setConfigFromParams` is no longer callable, `ReferenceError: window is not defined` in server code, the Edit button suddenly renders in production, or `Live_Preview_SDK: To use edit tags, you must provide the stack API key`.
 - **frameworks**: Next.js, React, Gatsby, Angular
 - **rendering_modes**: any
-- **root_cause**: Feature availability is version-gated and majors carry breaking changes that were not always documented. Pinned-old dependency policies (auto-update disabled) leave teams on v1.x where the required callbacks do not exist. The v2 → v3 jump removed `setConfigFromParams` (its replacement reads `window`, which throws in SSR) and made `stackDetails.apiKey` mandatory for edit tags.
+- **root_cause**: Feature availability is version-gated and majors carry breaking changes. Pinned-old dependency policies (auto-update disabled) leave teams on v1.x where builder mode does not exist; it arrived in v3. `setConfigFromParams` is no longer part of the public API, and code that replaced it with a helper reading `window` throws in SSR. `stackDetails.apiKey` is required for edit tags and builder mode.
 - **fix**:
-  1. Meet the minimums: Live Preview Utils **v3.0+** and Delivery SDK **v3.20.3+** for Visual Editor; **v4.4.4+** if you use `setPageContext()`.
-  2. Pass `stackDetails: { apiKey, environment }` explicitly in `init()` — v2+ no longer derives the API key from the Stack object for edit tags.
+  1. Meet the minimums: Live Preview Utils **v3.0+** for Visual Editor (legacy `contentstack` JavaScript SDK **v3.20.3+**; every `@contentstack/delivery-sdk` release qualifies); **v4.4.4+** if you use `setPageContext()`.
+  2. Pass `stackDetails: { apiKey, environment }` explicitly in `init()`. Builder mode throws without them.
   3. In SSR, stop calling `setConfigFromParams`. Read the query parameters from the request and apply them with `livePreviewQuery()` instead of relying on any SDK helper that touches `window`.
   4. Pin one delivery method for the SDK. Mixing an npm install with an ESM/CDN `<script type="module">` import of a different version produces version-specific behaviour differences (for example the Edit button appearing after a CDN bump).
   5. Read the SDK release notes before a major bump rather than the setup docs alone.
@@ -117,7 +118,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### environment-base-url-misconfigured-or-missing-for-a-locale
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wrong path or the site root; a specific locale cannot be previewed at all while others work; the preview pane keeps showing the previous environment's URL after switching.
 - **frameworks**: framework-agnostic (stack configuration)
 - **rendering_modes**: any
@@ -133,27 +134,27 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### edit-button-rendered-outside-a-live-preview-session
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or the `#cslp-tooltip` button element is injected into `document.body` on production even when not visible (usually caught in an accessibility audit). Sometimes intermittent, correlating with client-side route changes rather than fresh page loads.
 - **frameworks**: Next.js (App Router especially), React
 - **rendering_modes**: CSR, SSR
-- **root_cause**: With `editButton.enable: true`, the SDK gates the button on `enable` + `inIframe()` + the `cslp-buttons` query parameter. It never checks the `live_preview` hash or any active-session signal, so a normally loaded page with the SDK initialized renders the button by design. Teams that gate `init()` on a server-read hash also get bitten by App Router soft navigation, which does not re-run that server-side gate while the SDK's button instance persists across route changes.
+- **root_cause**: With `editButton.enable: true` and no `exclude`, the SDK renders the button on any page where it is initialized, inside the iframe or not. It never checks the `live_preview` hash or any session signal. `inIframe()` only matters when `exclude` is set, and a `?cslp-buttons=` query parameter overrides `exclude` unless `includeByQueryParameter: false`. Teams that gate `init()` on a server-read hash also get bitten by App Router soft navigation, which does not re-run that server-side gate while the SDK's button instance persists across route changes.
 - **fix**:
-  1. Add `editButton: { enable: true, exclude: ['outsideLivePreviewPortal'] }`. Outside the iframe `inIframe()` is false, so the button will not render, while Live Preview inside the pane keeps working.
-  2. If Live Preview is not used on production at all, strip it from the production build: `cleanCslpOnProduction: true` removes `data-cslp` from the DOM, and the `PURGE_PREVIEW_SDK=true` build flag no-ops the SDK entirely.
+  1. Add `editButton: { enable: true, exclude: ['outsideLivePreviewPortal'], includeByQueryParameter: false }`. Outside the iframe the button no longer renders, a query parameter cannot bring it back, and Live Preview inside the pane keeps working.
+  2. If Live Preview is not used on production at all, do not initialize it there: `enable: false` (with the default `cleanCslpOnProduction: true`, which then strips `data-cslp`), or the `PURGE_PREVIEW_SDK=true` build flag, which no-ops the SDK entirely.
   3. Do not rely on a server-side hash check alone in an App Router app; soft navigation will not re-evaluate it.
-- **verification**: Load the production URL in a normal tab with DevTools open. `document.getElementById('cslp-tooltip')` should be absent, and no `data-cslp` attributes should be present if `cleanCslpOnProduction` is set.
+- **verification**: Load the production URL in a normal tab with DevTools open. `document.getElementById('cslp-tooltip')` should be absent, and no `data-cslp` attributes should be present if the SDK runs with `enable: false`.
 
 ---
 
 ### cors-blocked-on-preview-api-requests
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: `Access to fetch at 'https://<region>-rest-preview.contentstack.com/v3/...' from origin '<site origin>' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource`, frequently alongside a `401 (Unauthorized)` on the same request. Works on localhost, fails on the deployed dev/staging host.
 - **frameworks**: Gatsby, Angular, Next.js, React
 - **rendering_modes**: CSR mainly
 - **root_cause**: Two distinct problems that surface as one console message. (1) The site's own Content Security Policy (`connect-src` / `default-src`) does not allow calls to Contentstack hosts, which most frameworks restrict by default in production but not in local dev. (2) The preview request is genuinely rejected (bad or wrong-type token), and the error response carries no CORS headers, so the browser reports it as a CORS failure instead of a 401. There is no per-stack "CORS allowlist" on the Contentstack side to add origins to.
 - **fix**:
-  1. Widen the site's CSP to the whole Contentstack domain rather than individual hosts. Listing only `app.contentstack.com` and `rest-preview.contentstack.com` has repeatedly been insufficient; `https://*.contentstack.com` (and `https://*.contentstack.io` where delivery/asset hosts are used) is what worked.
+  1. Allow every Contentstack host the page calls in the site's `connect-src`: the region's delivery, preview, GraphQL and asset hosts as well as the app host. Listing only the app and REST preview hosts usually misses one. `https://*.contentstack.com https://*.contentstack.io` is the simple form when listing hosts individually keeps failing.
   2. Fix the 401 separately: confirm you are sending a valid **Preview Token** (not a Delivery Token, not a Management Token) in the `preview_token` header, and regenerate it if in doubt. Resolve the CSP first, or the server error stays masked.
   3. Recheck env vars after a stack migration or API key change — a stale API key produces the same 401-behind-CORS shape.
 - **verification**: `curl` the same preview URL with the same headers from a terminal. A 200 proves the token is valid and the remaining problem is browser-side CSP. In the browser, the request should complete with `Access-Control-Allow-Origin` present.
@@ -161,7 +162,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### ssr-stack-instance-shared-or-duplicated
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Two opposite failures from the same mistake. **(A) Hash never arrives:** `init()` succeeds and `ContentstackLivePreview.hash` is populated on the client, but server-rendered pages still return published content. Deterministic, and only the author notices. **(B) Preview state leaks out:** intermittent, user-dependent wrong content, and the **production** site failing with `The Live Preview tracker is invalid or no longer exists. Create a new tracker to continue.` (error_code 382) or `The requested tracker was created for the 'dev' branch. Access using the 'main' branch is not allowed.`; preview stalling after a while; `TypeError: Cannot read properties of undefined (reading 'uid')` after idle hours in production; two editors seeing each other's content; personalization on the public site stopping resolving per visitor because a cached preview render is being served instead. This one reaches real visitors.
 - **frameworks**: Next.js (App Router and Pages Router), Express/Node, Nuxt
 - **rendering_modes**: SSR | edge
@@ -179,7 +180,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### nextjs-app-router-init-must-run-in-a-client-component
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit tags render but do nothing, or nothing at all happens when the entry is edited. The same code works in a Pages Router project.
 - **frameworks**: Next.js App Router
 - **rendering_modes**: SSR, CSR
@@ -203,7 +204,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### legacy-management-token-setup-not-migrated-to-preview-token
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: "Preview Service Not Enabled" shows in the preview panel on a setup that otherwise works. Or a setup copied from older docs / an older starter app passes a `management_token` to `live_preview` and fails with 401/422 after tokens were rotated.
 - **frameworks**: Next.js, Gatsby, React, framework-agnostic
 - **rendering_modes**: any
@@ -212,13 +213,13 @@ contract tells you which section to read; this file tells you what to do.
   1. Generate a Preview Token on the Delivery Token you already use.
   2. Replace `live_preview.management_token` with `live_preview.preview_token` and point `live_preview.host` at the region's `*-rest-preview.contentstack.com`.
   3. Update any framework source plugin to a version whose build output actually reads `preview_token` (some releases had source and build output disagreeing).
-  4. Remove the Management Token from client-side code entirely. Stack API Key, Delivery Token, and Preview Token are read-only and safe to ship to the browser; a Management Token has write access and is not.
+  4. Remove the Management Token from client-side code entirely; it has write access. The Stack API Key, Delivery Token and Preview Token are read-only and acceptable client-side, but still treat them as credentials: do not paste them into tickets or logs.
 - **verification**: No Management Token appears in any client bundle or preview request; the "Preview Service Not Enabled" card is gone and the Onboarding Check reaches Setup Complete.
 
 ---
 
 ### branch-or-alias-mismatch-between-app-token-and-entry
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Preview opens for pages that already exist on the main branch but never shows updates, and any page that exists only on the working branch 404s. Or: `error_code: 901, "Access denied. You have insufficient permissions to perform operation on this branch"`.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: any
@@ -232,7 +233,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### wrong-region-hosts-in-sdk-and-preview-config
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Live Preview never activates or the preview panel reports the service is not enabled, even though the stack settings look correct. Requests in the network tab go to the default North America hosts while the stack lives in another region.
 - **frameworks**: Next.js, Angular, React
 - **rendering_modes**: any
@@ -243,18 +244,18 @@ contract tells you which section to read; this file tells you what to do.
      - preview: `rest-preview.contentstack.com` → e.g. `eu-rest-preview.contentstack.com`, `azure-na-rest-preview.contentstack.com`, `gcp-eu-rest-preview.contentstack.com`
      - GraphQL preview: `graphql-preview.contentstack.com` → the region-prefixed equivalent
      - app host (`clientUrlParams.host`): `app.contentstack.com` → e.g. `eu-app.contentstack.com`, `gcp-na-app.contentstack.com`
-  2. Use the SDK's `region` option where available rather than hand-writing hosts, and make sure a hardcoded `host` does not override it.
+  2. On the Delivery SDK, use its `region` option rather than hand-writing hosts, and make sure a hardcoded `host` does not override it. Live Preview Utils has no `region` option: set `clientUrlParams.host` to the region's app host by hand.
   3. Re-check every host after a stack migration; the API key changes too.
 - **verification**: In DevTools → Network, every Contentstack request goes to a host carrying the correct region prefix, and returns 200.
 
 ---
 
 ### locale-defaults-to-en-us-in-init
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Start Editing / the Edit button opens Visual Editor or the entry editor with `locale=en-us` even though the stack has no `en-us` language, producing a 404 or a "Language not found" toast. Works on one deployment and not another with identical code.
 - **frameworks**: React, Angular, framework-agnostic
 - **rendering_modes**: any
-- **root_cause**: When `stackDetails.locale` is not set in `init()`, the SDK tries to infer the locale by finding an element with `data-cslp` in the DOM and reading the locale out of it. If no tagged element is present at that moment, it falls back to `en-us`. That fallback is invalid on stacks whose master language is something else, and it explains why the same code behaves differently on two deployments (one happens to have tagged content in the DOM, the other does not).
+- **root_cause**: The SDK picks the locale for the editor URL in this order: a valid `data-cslp` tag found in the DOM, then `stackDetails.locale` from `init()`, then the default `en-us`. With no tagged element in the DOM at that moment and no configured locale, it lands on `en-us`, which is invalid on stacks whose master language is something else. That is why the same code behaves differently on two deployments: one happens to have tagged content in the DOM, the other does not.
 - **fix**:
   1. Set the locale explicitly:
      `ContentstackLivePreview.init({ stackDetails: { apiKey, environment, locale: '<your-locale>' } })`.
@@ -265,11 +266,11 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### start-editing-button-cannot-be-hidden-in-editor-mode
-- **bucket**: setup
-- **symptom**: The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `mode: "builder"` is set, including production. Setting `editButton.enable: false` removes the per-field edit tags but not this button.
+- **bucket**: integration
+- **symptom**: The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `mode: "builder"` is set, including production. Setting `editButton.enable: false` removes the per-field Edit button but not this one.
 - **frameworks**: React, Next.js, Gatsby
 - **rendering_modes**: any
-- **root_cause**: "Start Editing" is a separate control from the per-field edit tags. It is enabled implicitly by `mode: "builder"` and has its own config key, which was not obvious from the setup docs. `editButton` governs only the field-level tags.
+- **root_cause**: "Start Editing" is a separate control from the per-field Edit button. It is enabled implicitly by `mode: "builder"` and has its own config key. `editButton` governs only the per-field button.
 - **fix**:
   1. Disable it explicitly:
      ```js
@@ -278,17 +279,17 @@ contract tells you which section to read; this file tells you what to do.
        editInVisualBuilderButton: { enable: false },
      });
      ```
-  2. Better for production builds: do not initialize the SDK there at all, or use `PURGE_PREVIEW_SDK=true` / `cleanCslpOnProduction: true`.
+  2. Better for production builds: do not initialize the SDK there at all (`enable: false`), or use `PURGE_PREVIEW_SDK=true`.
 - **verification**: Load the production URL; no floating Start Editing button. Load the preview environment; the button is present when you want it.
 
 ---
 
 ### onboarding-check-card-not-visible-or-appears-unexpectedly
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days later on its own. Conversely, other teams never see the status card at all when they want to diagnose a failing integration.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: any
-- **root_cause**: Each product keeps its own stack setting, and they do not agree on what "unset" means. Timeline treats an unset value as visible. Live Preview treats an unset value as hidden. Visual Editor treats an unset value as visible, and also treats a stack with no `visual_builder` settings at all as visible. Meanwhile the Visual Experience settings screen renders the toggle as on whenever the value is unset, so a stack that never explicitly saved the setting can show the toggle on while Live Preview behaves as though it is off. Separately, the checks run asynchronously with a timeout, so the card can appear briefly on a correctly configured site whose first preview fetch is slow, then clear itself once the request lands.
+- **root_cause**: Each product keeps its own stack setting, and they do not agree on what "unset" means. Timeline treats an unset value as visible. Live Preview treats an unset value as hidden. Visual Editor treats a stack with no `visual_builder` settings at all as visible, but a stack that has `visual_builder` settings without this key as hidden. Meanwhile the Visual Experience settings screen renders the toggle as on whenever the value is unset, so a stack that never explicitly saved the setting can show the toggle on while Live Preview behaves as though it is off. Separately, the checks run asynchronously with a timeout, so the card can appear briefly on a correctly configured site whose first preview fetch is slow, then clear itself once the request lands.
 - **fix**:
   1. Open Settings → Visual Experience and click Save without changing anything. Saving once stores the state shown for Live Preview, Visual Editor and Timeline together, and a toggle that was never saved still shows as on, so one save records an explicit on for all three. That removes the unset ambiguity and makes all three agree.
   2. Check the setting for the product actually being used. Live Preview, Visual Editor and Timeline each have their own, under Settings → Visual Experience.
@@ -300,7 +301,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### visual-experience-navigation-missing-for-the-stack
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: The "Visual Experience" / builder-mode option does not appear in the Contentstack navigation at all, so the team cannot open the builder and assumes their integration is wrong.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: any
@@ -313,7 +314,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### third-party-cookies-blocked-inside-the-preview-iframe
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: The site renders in the preview pane but behaves as if logged out, or without personalization, locale or currency preferences. Anything driven by the site's own cookies is lost.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: any
@@ -328,7 +329,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### chrome-local-network-access-blocks-preview-of-localhost
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: A previously working local Live Preview setup breaks with
   `Access to fetch at 'http://localhost:5173/' from origin 'https://<region>-app.contentstack.com' has been blocked by CORS policy: Permission was denied for this request to access the 'unknown' address space`.
   Chrome only; Safari unaffected. Downgrading the SDK does not help.
@@ -343,7 +344,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### cslp-tags-contain-the-literal-string-undefined
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: `data-cslp` attributes in the DOM contain `undefined` where the entry uid should be. Inline editing does not work and edit mapping silently fails on those elements.
 - **frameworks**: Next.js
 - **rendering_modes**: SSR
@@ -362,7 +363,7 @@ contract tells you which section to read; this file tells you what to do.
 ---
 
 ### ssg-preview-needs-csr-mode
-- **bucket**: setup
+- **bucket**: integration
 - **symptom**: Live Preview on a statically generated site is unreliable or simply shows build-time content: blank or black screens, flicker, an auth prompt on reload, or edits that never appear no matter what. The hash is on the URL and never reaches the fetch.
 - **frameworks**: Next.js, Gatsby, Astro, framework-agnostic
 - **rendering_modes**: SSG/ISR
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
index 7262d4c..c80ccb7 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -1,9 +1,9 @@
 # Preview runtime FAQ
 
 Content correctness once the integration is confirmed wired up: staleness, lost preview context,
-caching, locale, variants, and Timeline.
+caching, locale, variants and roles. Timeline is in `faq-timeline.md`.
 
-If the integration itself is not confirmed, work the four setup contracts in SKILL.md first. A
+If the integration itself is not confirmed, work the four contracts in SKILL.md first. A
 fetch that never switched to the Preview Service produces most of the symptoms below and none of
 the fixes here will help.
 
@@ -12,15 +12,14 @@ the fixes here will help.
 - **symptom**: Selecting a variant (or switching audience in Audience Preview) in Visual Experience keeps rendering the base entry. The side form shows the correct variant content, but the canvas does not. A manual browser refresh sometimes fixes it. Clicking into the element shows the correct variant value while the rendered page does not.
 - **frameworks**: Next.js, React, framework-agnostic
 - **rendering_modes**: CSR | SSR
-- **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-setup.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the Contentstack UI loads the entry on its own, independently of your site's fetch. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
+- **root_cause**: Two distinct mechanisms. (1) Most common: the iframe's content requests are not reaching the Preview service at all (see `app-fetches-from-delivery-cdn-instead-of-preview-service` in `faq-integration.md`). Delivery returns the published base entry and has no knowledge of the variant selected in the UI — the side form looks right because the Contentstack UI loads the entry on its own, independently of your site's fetch. (2) Refresh gap: on variant switch the site must re-fetch, and in CSR that only happens if `onEntryChange` is registered. Without it the canvas keeps its first render. In practice almost every report is one of these two — the Preview Service not configured, or `onEntryChange` missing — not a defect in variant resolution.
 - **fix**:
   1. First confirm the preview path works at all: change a plain text field and check the canvas updates. If it does not, fix that first — the variant symptom is downstream of it.
   2. Do **not** pass the variant yourself. The Preview Service resolves it from the UI selection; no `variant` query param, no `Entries.variants()`. Do pass `include_applied_variants=true` as a query parameter on the content request (`.addParams({ include_applied_variants: "true" })`), or the variant renders but Highlight Variant and audience mode have nothing to key on; see `highlight-variant-or-audience-mode-does-nothing` in `faq-visual-editor.md`.
   3. Confirm the Preview Service is actually configured: a preview token on the Stack's `live_preview` config, and content requests going to a `*-preview.contentstack.com` host during the session. This is the most common cause.
   4. Register `ContentstackLivePreview.onEntryChange(fetchFn)` and make `fetchFn` re-query through the preview-configured Stack. This is the second most common cause. Confirm `ssr` matches the route's actual rendering mode while you are there.
-  5. Check the cache layer. If preview responses are cached under a key that ignores the `live_preview` hash, the base content is served no matter what. Bypass caching entirely for preview requests.
+  5. Check the cache layer. A cache on the preview path serves the base content, or one variant's response for another, no matter what the UI selects. Do not key it by hash or variant: bypass it for preview requests entirely.
   6. Variants on referenced entries: the referenced content type must be linked to the variant group for its variant content to resolve in preview, and that reference field must be in the `includeReference()` / `referenceFieldPath` list used for the page.
-  7. If a cache sits in front, it must not serve one variant's response for another. Do not key it by variant — bypass it for preview requests entirely.
 - **verification**: Switch variants; the network tab should show a fresh request to the preview host, and the rendered canvas should change without a manual refresh.
 
 ---
@@ -44,7 +43,7 @@ the fixes here will help.
 - **symptom**: A page that renders fine in the entry editor and on the live site comes back blank in Visual Experience for a non-master locale. Or preview opens with a locale that does not exist in the stack (e.g. `en-us` on a stack that only has `fr-fr`) and 404s. Or one modular block referencing another entry renders empty in an unlocalized locale.
 - **frameworks**: framework-agnostic
 - **rendering_modes**: CSR | SSR | SSG/ISR
-- **root_cause**: The Delivery API falls back to the master locale automatically; the Preview service does not. If the request to the preview service omits `include_fallback=true` (REST) or `fallback_locale: true` (GraphQL), an unlocalized entry — including an unlocalized *referenced* entry inside a modular block — returns nothing and the page renders empty. Separately, Visual Experience needs a base URL configured per locale in the environment; a locale with no base URL cannot load an iframe, and the preview URL falls back to a default locale that may not exist in the stack.
+- **root_cause**: If the request to the preview service omits `include_fallback=true` (REST) or `fallback_locale: true` (GraphQL), an unlocalized entry — including an unlocalized *referenced* entry inside a modular block — returns nothing and the page renders empty. Separately, Visual Experience needs a base URL configured per locale in the environment; a locale with no base URL cannot load an iframe, and the preview URL falls back to a default locale that may not exist in the stack.
 - **fix**:
   1. Add `include_fallback=true` (REST) / `fallback_locale: true` (GraphQL) to every preview fetch, and to nested reference includes.
   2. Configure a base URL for every locale you want to author in, under the environment's Live Preview settings. A missing URL for one locale can disable the whole environment selector for that locale.
@@ -77,8 +76,8 @@ the fixes here will help.
 - **root_cause**: The SDK keeps the preview params on the URL by one mechanism only: a click listener that finds the clicked `<a>` and rewrites its `href` to include `live_preview` before the browser follows it. It does not patch the History API, so any navigation that does not go through a real anchor href — `router.push()`, `useNavigate()`, `history.pushState` — carries no params and the preview context is lost. Framework `<Link>` components are the common trap: they render an `<a>`, so the href is rewritten, but the router calls `preventDefault()` and pushes its own URL, so the rewrite is never used. Separately, if the app's routing does not map 1:1 to the entry's `url` field, the preview URL that Contentstack constructs (environment base URL + entry `url`) points at a route that does not exist. App Router soft navigation also does not re-run server-side hash gating.
 - **fix**:
   1. Preserve `live_preview`, `content_type_uid`, `entry_uid`, and `preview_timestamp` in the URL across programmatic navigations, or trigger a hard navigation inside the preview.
-  2. For routes that cannot be derived from the entry `url` field, enable **Custom Preview URLs** and then call `setPageContext({ entryUid, contentTypeUid })` on each page (Live Preview Utils v4.4.4+). The call only takes effect when Custom Preview URLs is configured and enabled on the plan; otherwise it is silently ignored and the editor keeps resolving by URL.
-  3. For non-trivial URL structures, configure **Custom Preview URLs** in Settings → Visual Experience → Preview URL, following [the docs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls) for patterns and Base URL aliases.
+  2. For routes that cannot be derived from the entry `url` field, enable **Custom Preview URLs** and then call `setPageContext({ entryUid, contentTypeUid })` on each page (Live Preview Utils v4.4.4+). The call only takes effect when Custom Preview URLs is enabled for the stack; otherwise it is silently ignored and the editor keeps resolving by URL.
+  3. For non-trivial URL structures, configure **Custom Preview URLs** in Settings → Visual Experience → Preview URL, following [the docs](https://www.contentstack.com/docs/headless-cms/custom-preview-urls) for patterns and Base URL aliases.
   4. Confirm every route allows iframe embedding, not just the root — an `X-Frame-Options` or CSP `frame-ancestors` header, or a hard redirect to a different host, on a deep route will break navigation inside the panel.
 - **verification**: Click through the site's own nav inside the preview panel; the URL keeps its preview params and edits still apply on the new page.
 
@@ -99,20 +98,6 @@ the fixes here will help.
 
 ---
 
-### stale-first-fetch-when-editing-a-referenced-entry
-- **bucket**: preview-runtime
-- **symptom**: The very first `onEntryChange` fetch after opening the preview returns published data even though the entry was already modified. Every subsequent keystroke-triggered fetch returns the correct draft data.
-- **frameworks**: Next.js (Pages Router), GraphQL
-- **rendering_modes**: CSR (on an SSG/ISR site)
-- **root_cause**: Service-side. It reproduced only when the entry being edited is a **referenced** entry and the site fetches the **parent** entry through a reference connection — the first preview response did not yet include the referenced entry's draft state.
-- **fix**:
-  1. Confirm the shape: are you editing a child/referenced entry while the page queries the parent through a reference connection? If so this is the known case and was fixed service-side.
-  2. Confirm the first request really is going to the preview host (the Onboarding Check reports this too) before assuming this issue — a first request to the delivery host looks identical from the outside.
-  3. Update to a current Live Preview Utils version.
-- **verification**: Modify a referenced entry, open the preview fresh, and confirm the draft value is present on the first render with no keystroke.
-
----
-
 ### legacy-management-token-preview-breaks-on-references
 - **bucket**: preview-runtime
 - **symptom**: Live Preview works for top-level fields but an edit to an entry that is referenced inside another entry does not update. Setup status reports "Preview Service Not Enabled" even though Live Preview is on for the stack. Migrating to preview tokens returns `401 Unauthorized` on the first attempt.
@@ -123,7 +108,7 @@ the fixes here will help.
   1. Migrate to the Preview Service: generate a Preview Token tied to your Delivery Token and replace `management_token` with `preview_token` in `live_preview`, and point `host` at the region's preview host.
   2. Remove the CMA host override and any `setHost` calls left over from the old setup.
   3. If preview requests 401 after the swap, confirm the Preview Token is tied to the Delivery Token you are actually using and that the token is sent as the `preview_token` header (not `authorization`).
-  4. Minimum versions for Visual Editor: Live Preview Utils v3.0+, Delivery SDK v3.20.3+ (v4.4.4+ of Live Preview Utils if you use `setPageContext`).
+  4. Minimum versions for Visual Editor: Live Preview Utils v3.0+, legacy `contentstack` JavaScript SDK v3.20.3+ (v4.4.4+ of Live Preview Utils if you use `setPageContext`).
 - **verification**: Setup status stops reporting "Preview Service Not Enabled"; edits to a referenced entry appear in the parent page's preview.
 
 ---
@@ -141,7 +126,7 @@ the fixes here will help.
   4. Grant read on the content type itself, not only on its entries. Granting entry access alone leaves the 422 in place.
   5. Do not work around it by granting broader edit rights. Read access on the environment and the content types is the correct fix.
   6. After changing the role, have the user sign out and back in before retesting. Role changes do not always apply to an existing session.
-  7. **Everyone** seeing "No environments available", not just one user, is a different problem: a missing Base URL — see `environment-base-url-misconfigured-or-missing-for-a-locale` in `faq-setup.md`.
+  7. **Everyone** seeing "No environments available", not just one user, is a different problem: a missing Base URL — see `environment-base-url-misconfigured-or-missing-for-a-locale` in `faq-integration.md`.
 - **verification**: The restricted user's preview renders without gaps or errors, showing graceful fallbacks where access is limited; no `422 Content Type ... not found` in their preview requests. The environment dropdown lists the preview environment for their role.
 
 ---
@@ -154,7 +139,7 @@ the fixes here will help.
 - **root_cause**: The preview renders inside a cross-origin iframe. Third-party scripts whose targeting or delivery logic depends on the top-level host, referrer, or first-party storage see the iframe context instead of the real site and behave differently. Not a Contentstack request failure: the calls fire and fail at the third party's delivery stage. This is inherent to rendering the site in an iframe and there is no product-side fix for it.
 - **fix**:
   1. Where the third party allows it, add the Contentstack app origin to its allowed-referrer or allowed-domain configuration.
-  2. Use **Open in New Tab**, which renders the preview outside the iframe so the third party sees the real host. This is an existing feature, not something to request.
+  2. Use **Open in New Tab**, which renders the preview outside the iframe so the third party sees the real host. It is plan-gated; if it is missing, see `contact-support.md`.
   3. Where neither is possible, exclude those third-party scripts when the preview parameters are present, so authors preview content without them rather than with a broken version of them.
 - **verification**: Use Open in New Tab rather than the preview panel and confirm the third-party content renders. That difference confirms the iframe context is the trigger.
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
index b5b5a83..7299acc 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
@@ -30,7 +30,7 @@ already good.
 - **rendering_modes**: any
 - **root_cause**: Highlight Differences works by matching changed fields to DOM elements through their `data-cslp` attributes. It needs live edit tags enabled on the site **and** a `data-cslp` physically present on the element that renders the changed field. Where the tag coverage is thin, or the specific field that changed carries no tag, the diff has nothing to attach the highlight to and the comparison looks empty even though both versions rendered.
 - **fix**:
-  1. Confirm live edit tags are enabled and rendered — see `edit-tags-not-generated-or-not-spread` in `faq-setup.md`.
+  1. Confirm live edit tags are enabled and rendered — see `edit-tags-not-generated-or-not-spread` in `faq-integration.md`.
   2. In the Timeline iframe, run
      `[...document.querySelectorAll('[data-cslp]')].map(el => ({tag: el.tagName, cslp: el.getAttribute('data-cslp')}))`
      and confirm the **specific field you changed** appears in that list.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
index 19212bc..083688a 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -5,18 +5,18 @@ affordance, and what the canvas does with the site's own clicks. Live Preview re
 the canvas misbehaves points here.
 
 If nothing on the canvas is editable at all, start with `edit-tags-not-generated-or-not-spread` in
-`faq-setup.md` — that is setup contract 2, and everything here assumes it is met.
+`faq-integration.md` — that is contract 2, and everything here assumes it is met.
 
 ### cslp-not-rebased-to-referenced-entry
 - **bucket**: visual-editor
 - **symptom**: Edit tags on fields that come from a **referenced** entry do nothing when clicked. Tags on the page's own fields work. Console may show `{code: 'NO_REQUEST_LISTENER_FOUND', message: 'contentstack-adv-post-message: No request listener found for event "scroll"'}`, but that message is routine and appears on healthy setups too — treat it as incidental, not as the identifying evidence. Diagnose from the tags themselves.
 - **frameworks**: React, Next.js, framework-agnostic
 - **rendering_modes**: CSR, SSR
-- **root_cause**: `addEditableTags()` rebases a tag onto the referenced entry only when the resolved reference object carries both `uid` and `_content_type_uid`. Without them the tag stays anchored to the parent entry (`product.<parent_entry_uid>.<locale>.<reference_field>.<index>.<field>`), so there is no entry to navigate to. Common causes: references fetched separately and merged by hand (which drops those keys), or a GraphQL query that omits `system`. Hardcoding `data-cslp` by hand is a related failure — the referenced entry's uid and content type uid are not the ones being edited.
+- **root_cause**: `addEditableTags()` rebases a tag onto the referenced entry only when the resolved reference object carries both `uid` and `_content_type_uid`. Without them the tag stays anchored to the parent entry (`product.<parent_entry_uid>.<locale>.<reference_field>.<index>.<field>`), so there is no entry to navigate to. Common causes: references fetched separately and merged by hand (which drops those keys), or any GraphQL response, where those keys sit under `system` instead of at the top level. Hardcoding `data-cslp` by hand is a related failure — the referenced entry's uid and content type uid are not the ones being edited.
 - **fix**:
   1. Inspect the referenced field in DevTools. Working shape is `<referenced_ct_uid>.<referenced_entry_uid>.<locale>.<field>`. If you see the parent entry's uid, this is the bug.
   2. REST / Delivery SDK: resolve references with `includeReference()` / `include[]` so resolved objects keep `uid` and `_content_type_uid`.
-  3. GraphQL: request `system { uid, content_type_uid, locale }` on every reference.
+  3. GraphQL: request `system { uid, content_type_uid, locale }` on every reference, then normalise each node so `uid` and `_content_type_uid` sit at its top level. See `graphql-connection-wrappers-break-cslp`.
   4. If references are fetched separately, either preserve those two keys when merging, or call `addEditableTags()` on each referenced entry with its own content type uid.
   5. Never hardcode `data-cslp` — always read the value the SDK put on the entry object.
 - **verification**: Click the edit tag on a referenced field; the CMS should open the referenced entry's editor and scroll to that field.
@@ -76,10 +76,11 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 - **rendering_modes**: any
 - **root_cause**: `addEditableTags()` walks the response object and bakes every traversed layer into the `data-cslp` path. A GraphQL response nests values under `Connection -> edges -> node`, so those wrapper layers end up in the path and no field path resolves against the entry. This is by design — the SDK has no knowledge of GraphQL response shapes — so it needs a normalizer on the application side.
 - **fix**:
-  1. Request `system { uid, content_type_uid }` on every node the page renders, including referenced entries. Without those the tags cannot be attributed to an entry at all.
+  1. Request `system { uid, content_type_uid, locale }` on every node the page renders, including referenced entries. Without those the tags cannot be attributed to an entry at all.
   2. Flatten the response before tagging: collapse each `Connection -> edges -> node` into the plain object or array the REST shape would have produced, so a reference is an array of entries and a field is a direct property.
-  3. Call `addEditableTags()` on the flattened object, never on the raw GraphQL response.
-  4. Confirm the resulting `data-cslp` values contain no `edges` or `node` segments.
+  3. On every entry and referenced entry, copy `system.uid` to `uid` and `system.content_type_uid` to `_content_type_uid`. `addEditableTags()` reads only the top-level keys, so without this references are never rebased and their tags point at the parent entry.
+  4. Call `addEditableTags()` on the normalised object, never on the raw GraphQL response.
+  5. Confirm the resulting `data-cslp` values contain no `edges` or `node` segments.
 - **verification**: Inspect a tagged element. Its `data-cslp` reads `<content_type_uid>.<entry_uid>.<locale>.<field_path>` with no connection segments, and clicking it focuses the field in the form panel.
 
 ---
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md b/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
index 5ca0f83..16f028e 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -9,11 +9,14 @@ needs to be previewable.
 
 ## Next.js, App Router
 
-The most common setup mistake in this framework, and the one that produces "the SDK is installed
-and nothing happens" with no error anywhere.
+The most common mistake in this framework, and the one that produces "the SDK is installed and
+nothing happens" with no error in the browser. On the server, `init()` logs "The SDK is not
+initialized in the browser." and returns.
 
 `init()` cannot run in a server component. Put it in a client component and import that into the
-layout so it runs once per app load:
+layout so it runs once per app load. The options differ by mode.
+
+CSR (content fetched in the browser):
 
 ```tsx
 "use client";
@@ -35,6 +38,35 @@ export function LivePreviewInit() {
 }
 ```
 
+SSR (server components fetch at request time). `init()` takes no `stackSdk`; the server applies
+the hash per request instead:
+
+```tsx
+// LivePreviewInit.tsx
+"use client";
+import { useEffect } from "react";
+import ContentstackLivePreview from "@contentstack/live-preview-utils";
+
+export function LivePreviewInit() {
+  useEffect(() => {
+    ContentstackLivePreview.init({
+      ssr: true,
+      mode: "builder",
+      stackDetails: { apiKey: API_KEY, environment: ENVIRONMENT },
+    });
+  }, []);
+  return null;
+}
+
+// app/[...slug]/page.tsx
+export default async function Page({ searchParams }) {
+  const params = await searchParams; // a Promise since Next.js 15
+  const stack = createStack();       // new Delivery SDK instance per request
+  stack.livePreviewQuery(params);    // reads live_preview, content_type_uid, entry_uid, preview_timestamp
+  // fetch through `stack` ...
+}
+```
+
 Watch for three things here:
 
 - Soft navigation does not re-run server-side gating, and the SDK's module-level state persists
@@ -42,8 +74,9 @@ Watch for three things here:
   will appear on production pages after a client-side navigation.
 - App Router metadata is produced by `generateMetadata()`, which has no hook for injecting window
   globals. If you are using the `window.__CS_PAGE_CONTEXT__` route for page context, set it from a
-  client component, or use the `<meta>` tag form instead. Page context is only honoured when
-  **Custom Preview URLs** is configured and enabled on the plan; without that it is silently ignored.
+  client component, or use the `<meta>` tag form instead. The SDK always sends page context, but
+  Visual Editor uses it only when **Custom Preview URLs** is enabled for the stack; otherwise it is
+  silently ignored.
 - Reading `searchParams` opts the route out of static rendering. Expect that when you add the SSR
   hash path.
 
@@ -93,8 +126,8 @@ route.
 
 Init in a client-only plugin. For page context, `useHead()` is the natural place to emit the
 `<meta>` tags, since Nuxt produces head tags natively and has no built-in hook for injecting window
-globals. As everywhere, page context only takes effect with **Custom Preview URLs** configured and
-enabled on the plan.
+globals. As everywhere, page context only takes effect when **Custom Preview URLs** is enabled for
+the stack.
 
 The Nuxt CSR and SSR stories differ on whether Visual Editor overlays appear, and Contentstack's
 own material is inconsistent on this point. Verify against the actual app before promising overlay
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
index 5585428..75dfeb6 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -1,165 +1,131 @@
 # The Onboarding Check
 
-Every visual experience product ships a setup check that runs automatically when its panel opens.
-There are **three** of them, and they differ in both gates and shape. Live Preview shows one card
-carrying the first failing gate. Visual Editor shows all six of its items, each with its own status,
-but stops evaluating at the first one that fails. Timeline shows a small status card while it checks,
-then a full-pane "Set Up Timeline" overlay listing three items with a status each once one fails.
-Confirm which product the user is in before reading anything below. It is the highest-yield thing to
-ask about, because it has already run the diagnosis the user is asking you to do.
+Each Visual Experience product runs its own setup check when its panel opens. There are **three**,
+with different gates, different minimum SDK versions, and different surfaces. Confirm the product
+before reading anything below.
 
-**Always ask for a screenshot of the check before asking anything else.** The failing step name
-localises the problem to one gate, and because of how the check is structured, it also tells you
-everything that already passed.
+**Ask for a screenshot before anything else.** The first failing item localises the problem to one
+gate and proves every earlier gate passed.
 
-## The property that makes all three checks powerful
+## The chain property
 
-All three evaluate their gates as an ordered chain that stops at the first failure. They differ only
-in how much they show you. Live Preview renders just the failing step. Timeline and Visual Editor
-render their full item list with a status each, but the items below the first incomplete one were
-never evaluated, so they carry no information. **In every product, read the first failing item and
-ignore what is under it.**
+All three checks evaluate their gates in order and stop at the first failure. Read the **first**
+failing item. Items after it never ran and carry no information.
 
-So a card reading "Preview Service Not Enabled" is not just one fact. It proves the website loaded
-in the frame, the SDK initialised, and the SDK version is supported. Three contracts are already
-ruled out. Do not re-ask about them.
+So "Preview Service Not Enabled" proves the site was reachable, the SDK initialised, and its version
+is supported. Do not re-ask about those. The inverse holds too: a check stuck on its first gate says
+nothing about the SDK, because the SDK gate never ran.
 
-The inverse also holds. A card stuck on the first gate tells you nothing about any later gate,
-because none of them ran. Do not theorise about the SDK when the site never loaded.
+## Live Preview
 
-## Live Preview and Visual Editor
-
-Five gates, in this order.
+One card, showing the gate under test while checking and the first failure when one fails.
 
 | # | Card while checking | Card on failure | What the failure means |
 |---|---|---|---|
-| 1 | Website Loading | **Could Not Connect to Website** | The site never rendered in the frame. Frame headers (`X-Frame-Options`, CSP `frame-ancestors`), an auth gate or password protection, a wrong or unreachable Base URL, a non-localhost `http://` host (mixed content; allow insecure content for the app origin) or an untrusted certificate (open the URL in its own tab, accept the warning, reload the pane), or the browser blocking localhost. Nothing after this ran. |
-| 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | The frame loaded but no init handshake arrived. `init()` is in server-only code, the enable flag did not parse as a boolean in the deployed build, the init module was tree-shaken out, or init runs after the check window. |
-| 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake arrived from a version below the supported minimum. Upgrade Live Preview Utils. |
-| 4 | Verifying Preview Service | **Preview Service Not Enabled** | The SDK is fine and the site is fine, but content is not coming from the Preview Service. This is the fetch layer never switching host and headers, which is the most common failure of all. |
-| 5 | — | **Default Environment Not Set** | Everything works. The stack simply has no default preview environment, set in stack settings. |
+| 1 | Website Loading | **Could Not Connect to Website** | A `no-cors` `HEAD` request to the preview URL failed at the network level: a wrong or unreachable Base URL, DNS, connection refused, an untrusted certificate (open the URL in its own tab, accept the warning, reload the pane), a non-localhost `http://` host (mixed content), or the browser blocking localhost. Frame headers and auth screens do **not** fail this gate, because a `no-cors` request succeeds on any HTTP response. |
+| 2 | Verifying Live Preview SDK | **Live Preview SDK Not Initialized** | No init handshake arrived within about 12 seconds. Either the frame rendered nothing (`X-Frame-Options`, CSP `frame-ancestors`, a password, auth or SSO screen) or the page loaded and `init()` never ran on the client: server-only placement, `enable` not truthy in the deployed build, the init module tree-shaken out, or init running late. |
+| 3 | Verifying Live Preview SDK | **Outdated Live Preview SDK Version** | The handshake reported a version below 1.4.0, or an unparseable one. Upgrade Live Preview Utils. |
+| 4 | Verifying Preview Service | **Preview Service Not Enabled** | Site and SDK are fine, but content is not coming from the Preview Service. The fetch layer never switched host and headers. The most common failure. |
+| 5 | — | **Default Environment Not Set** | Integration fine. The stack has no default preview environment. |
 | — | — | **Setup Complete** | All gates passed. |
 
-The exact body text is worth quoting back to users, because they often paraphrase it into
-something ambiguous. Gate 1 reads "Ensure the website is live and accessible via Contentstack
+To tell the two gate-2 causes apart, look at the pane: blank or a browser error page means frame
+headers or an auth screen; the site visibly rendered means `init()`.
+
+Body text worth quoting back: gate 1 reads "Ensure the website is live and accessible via Contentstack
 origins." Gate 4 reads "Please enable the Preview Service for a seamless live preview experience."
 
 ## Visual Editor
 
-Visual Editor runs its own check, not Live Preview's. Six items, shown as a list with a status per
-item. Unlike Live Preview it shows the whole list, but evaluation still stops at the first item that
-fails, so a partially green list is the normal way it looks while something is wrong and only the
-**first** incomplete item is diagnostic. Item text as observed in the UI.
+Its own check, not Live Preview's. A small status card runs first, its header naming the gate under
+test: "Live Preview SDK", "Live Preview SDK Init Mode", "API Key / Preview Token", then "All Set!".
+If a gate is still incomplete 18 seconds after the last change, a full-pane **"Set Up Visual Editor"**
+overlay replaces it. If the environment gate fails, the overlay appears at once. Ask for the overlay
+screenshot.
+
+Overlay items, verbatim:
 
-| # | Item (card text) | Passes when |
+| # | Overlay item | Passes when |
 |---|---|---|
-| 1 | Configure environment | both sub-steps below pass |
-| 1a | Default Environment | the environment in the preview URL's parameters exists on the stack |
-| 1b | Base URL | that environment has a Base URL for the current locale, and its **origin matches the origin of the page being previewed**. A Base URL on a different host or scheme fails here even though the page loads |
-| 2 | Install SDK | Live Preview Utils major version is 3 or higher |
-| 3 | Verify Mode for Live Preview | `init()` was called with `mode: "builder"`. **`mode: "preview"` fails this gate.** Edit tags alone do not get you a canvas |
-| 4 | Preview Token | the site's content requests for the previewed page reach the Preview Service (the REST or GraphQL preview host) instead of the delivery CDN. The check looks for that a handful of times across roughly the first 18 seconds after the SDK's `init()` handshake arrives and items 1-3 pass, so a site that fetches only from the delivery CDN, or fetches nothing in that window, fails here |
-
-Two consequences worth stating:
-
-- **Visual Editor needs three things, not two.** Working Live Preview, edit tags, and `mode: "builder"`
-  in `init()`. The product table in SKILL.md says so; a customer who followed a Live Preview guide has
-  `mode: "preview"` and will fail item 3 with everything else green.
-- **Item 1b is origin-exact.** The Base URL must match the previewed page's scheme and host. A Base
-  URL of `https://www.example.com` with the site served at `https://example.com`, or `http` versus
-  `https`, fails the check while the frame still renders.
+| 1 | Configure the environment | both sub-checks pass |
+| 1a | Validate the Default Environment | the `environment` in the preview URL exists on the stack |
+| 1b | Validate the Base URL | that environment has a Base URL for the current locale, and its **origin equals the previewed page's origin** |
+| 2 | Install the Latest Live Preview SDK | Live Preview Utils major version is 3 or higher |
+| 3 | Verify Mode for Live Preview | `init()` was called with `mode: "builder"`. `mode: "preview"` fails here |
+| 4 | Validate the Preview Token / API Key | after items 1 to 3 pass and the handshake arrives, a content request reaches the REST or GraphQL Preview Service. Polled 5 times over about 18 seconds |
 
-## Timeline
+Two consequences:
+
+- **Visual Editor needs three things.** Working Live Preview, edit tags, and `mode: "builder"`. A setup
+  copied from a Live Preview guide has `mode: "preview"` and fails item 3 with everything else green.
+- **Item 1b is origin-exact.** `https://www.example.com` against a page on `https://example.com`, or
+  `http` against `https`, fails while the frame still renders.
 
-Timeline runs its own check with three items, not Live Preview's five or Visual Editor's six. Do not
-map any of them onto another table. It has two surfaces:
+## Timeline
 
-1. **A small status card** at the bottom of the pane while the check runs. Its header names the item
-   under test: "Default Environment", then "Live Preview SDK", then "Preview Token", then "All Set!".
-   When everything passes it shows All Set! and disappears about two seconds later.
-2. **A full-pane "Set Up Timeline" overlay** that replaces the card when an item fails. It lists all
-   three items under "Get Started", each with a filled or empty circle. This is the screenshot to ask
-   for.
+Its own check, three items. A small status card runs first ("Default Environment", "Live Preview
+SDK", "Preview Token", then "All Set!", which hides after about two seconds). If an item is still
+unchecked ten seconds after the last status change, or one second after when no environment resolves,
+a full-pane **"Set Up Timeline"** overlay lists the items under "Get Started", each with a filled or
+empty circle.
 
 | # | Overlay item | Passes when | Empty circle means |
 |---|---|---|---|
-| 1 | Configure the environment | an environment resolves for the session: the `environment` on the Timeline URL, falling back to the stack's default preview environment (`live_preview.default-env`) | no environment on the URL and no default preview environment in stack settings |
-| 2 | Install the latest Live Preview SDK | item 1 passed and the SDK's `init()` handshake reached Timeline with a major version of 2 or higher | `init()` never ran inside the frame, or the SDK is 1.x |
-| 3 | Generate and use Preview Token | item 2 passed and, by the end of the check's short window, at least one of the site's content requests (REST or GraphQL) has been served by the Preview Service | the site fetched from the delivery CDN, or fetched nothing in time |
+| 1 | Configure the environment | an environment resolves: `environment` on the Timeline URL, else the stack's default preview environment | none on the URL and no default set |
+| 2 | Install the latest Live Preview SDK | item 1 passed and the `init()` handshake reached Timeline with major version 2 or higher | `init()` never ran in the frame, or SDK 1.x |
+| 3 | Generate and use Preview Token | item 2 passed and a content request reached the Preview Service within about nine seconds | the site fetched from the delivery CDN, or fetched nothing in time |
 
-The items are chained: 2 is only evaluated after 1 passes, 3 only after 2. Read the **first** empty
-circle. The ones below it never ran and tell you nothing.
+A slow site can show item 3 empty on a correct setup. Have the user reopen the panel on a warm cache
+before believing it.
 
-**Timing.** The overlay appears ten seconds after the last status change if anything is still
-unchecked, or after one second when no environment resolves at all. Item 3 waits roughly nine seconds for
-the site's first Preview Service request. A site whose
-first preview request lands later than that shows item 3 empty on a correct setup. Have the user
-reopen the panel on a warm cache before believing it.
+"Configure" opens the stack's Live Preview settings page. The footer links to the Set Up Timeline
+documentation.
 
-**Links on the overlay.** "Configure" opens Settings → Live Preview for the stack. "Install" and
-"Preview Token" open help articles. The footer links to the Set Up Timeline documentation page.
+## Minimum SDK versions differ
 
-**Closing it.** The X on the full overlay hides it for the current view only; nothing is stored. The
-X on the small status card is where suppression happens: owners, admins and developers get a modal
-offering "this session" (browser storage, per stack) or "for everyone" (writes
-`timeline.onboarding-setup-visible: false` to stack settings); any other role gets the session
-suppression silently.
+| Product | The check fails below |
+|---|---|
+| Live Preview | 1.4.0 |
+| Timeline | major version 2 |
+| Visual Editor | major version 3 |
 
-## What the check does not cover
+So an SDK can pass Live Preview's check and fail Visual Editor's.
 
-This is where the check earns its keep as a diagnostic, and where people over-trust it. "Setup
-Complete" and a broken experience is a real and informative combination.
+## What the checks do not cover
 
-The check verifies reachability, the SDK handshake, SDK version, and that the Preview Service is in
-use. It does not look at any of the following:
+"Setup Complete" with a broken experience is a real and informative combination. None of the three
+checks looks at:
 
-- **Edit tags.** Nothing in the chain inspects `data-cslp`. If the card says Setup Complete and
-  nothing on the canvas is editable, the answer is edit-tag generation, every time. This is the
-  single most useful inference the check supports.
-- **Preview URL resolution.** The site loading is not the same as the correct entry loading. A card
-  reading Setup Complete on the wrong page is a routing problem.
-- **Locale, variants, and Timeline timestamps.**
-- **Caching.** Any cache on the preview path can serve published content while every gate passes.
-- **Roles.** The check runs as the signed-in user but does not report permission gaps, which is why
-  a role problem looks like "works for everyone except one person" rather than a failed gate.
+- **Edit tags.** Nothing inspects `data-cslp`. Setup Complete with nothing editable is edit-tag
+  generation, every time.
+- **Preview URL resolution.** The site loading is not the right entry loading.
+- **Locale, variants and Timeline timestamps.**
+- **Caching.** A cache can serve published content while every gate passes.
+- **Roles.** The check runs as the signed-in user but reports no permission gaps.
 
-## When the card does not appear at all
+## When the check does not appear
 
-Absence is not a pass. Before treating a missing card as "the check succeeded", rule out:
+Absence is not a pass. Rule out:
 
-- No default environment is set and none is remembered locally for that locale, in which case the
-  overlay is deliberately not shown.
-- The user, or someone on their team, dismissed it. The preference persists per stack.
-- The stack setting suppresses it.
+- **Live Preview:** no default environment is set and none is remembered locally for the locale.
+- **Visual Editor:** the check already completed for this user and preview URL, or every gate passed.
+- **Dismissed.** Each product stores a per-stack dismissal in the user's browser storage. It
+  persists until site data is cleared, whatever the dismissal dialog says about "next login".
+- **Turned off in stack settings.**
 
-**Do not reason about the default.** Each product keeps its own stack setting, and they disagree on
-what an unset value means:
+The stack settings disagree on what an unset value means:
 
 | Product | Setting | Unset resolves to |
 |---|---|---|
-| Timeline | `timeline.onboarding-setup-visible` | visible |
 | Live Preview | `live_preview.lp-onboarding-setup-visible` | hidden |
-| Visual Editor | `visual_builder.onboarding-setup-visible` | visible |
-
-The Visual Experience settings screen renders every one of these as **on** when unset, so a stack
-that never explicitly saved the setting can show the toggle on while the card never appears.
-
-The fix is one action: open Settings → Visual Experience and Save, without changing anything. That
-form submits all three products' keys together and an unset value arrives as on, so one save writes
-an explicit value for all three and they stop disagreeing.
-
-If it then appears for colleagues but not for the reporter, they dismissed it. That suppression
-lives per stack in their own browser storage and no stack-level save clears it.
-
-If the user cannot produce the card, fall back to the four contracts in SKILL.md and verify them by
-hand.
+| Timeline | `timeline.onboarding-setup-visible` | visible |
+| Visual Editor | `visual_builder.onboarding-setup-visible` | visible if the stack has no `visual_builder` settings at all; **hidden** if it has them without this key |
 
-## How to ask for it
+The settings screen shows every one of these as **on** when unset, so the toggle can read on while
+the check never appears. The fix is one action: open Settings → Visual Experience and Save without
+changing anything. That writes an explicit value for all three.
 
-Ask for the screenshot rather than the wording. Users paraphrase the step name into a different
-one, and since each name maps to a specific gate, a paraphrase can send you down the wrong branch.
+If the check then appears for colleagues but not the reporter, the reporter dismissed it. No stack
+save clears that; they clear site data for the app origin or use another browser profile.
 
-If they cannot screenshot it, ask for the exact step name and body text as displayed, and confirm
-which product they are in. Live Preview shows one card, Timeline a three-item overlay, Visual Editor
-a six-item list, and none of them share gates; a paraphrased step name from the wrong product sends
-you down the wrong branch.
+If the user cannot produce the check, verify the four contracts in SKILL.md by hand.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md b/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
deleted file mode 100644
index 1021d83..0000000
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md
+++ /dev/null
@@ -1,105 +0,0 @@
-# Preflight checklist
-
-Run in order. Each step either passes or localises the problem to one contract. Stop at the first
-failure and fix it before continuing, because a failure upstream makes every downstream check
-meaningless.
-
-## Before touching the application
-
-1. **Get the Onboarding Check to appear.** It walks the contracts in order and names the first one
-   that fails. Do not assume its default state: each product has its own toggle under
-   Settings → Visual Experience, and one that has never been saved can read on while the card never
-   appears. Save the setting explicitly for the product in use.
-2. **Live Preview is enabled on the stack**, with a default preview environment set.
-3. **A Preview Token exists**, generated against the Delivery Token the application already uses.
-   A management token is not a substitute and must never reach client-side configuration.
-4. **The environment has a Base URL**, and one for each locale being previewed. A missing Base URL
-   presents as a greyed-out environment selector or "No environments available".
-5. **The signed-in user's role can read everything the page uses.** Preview runs as that user and
-   applies their full ACL — content types, entries, fields, locales, assets — so anything they
-   cannot read comes back empty. Delivery uses a delivery token and applies none. Expect preview
-   to differ per user, and make the site render missing data gracefully.
-
-## Reachability
-
-6. **The preview host is HTTPS, or it is `localhost`.** Browsers treat `http://localhost` as a secure
-   context, so a plain-HTTP dev server loads in the pane. Any other `http://` host inside the HTTPS app
-   is mixed content and the browser blocks the frame; the user can allow it for the Contentstack app
-   origin (Chrome: the shield icon, or Site settings → Insecure content → Allow). An untrusted
-   certificate (self-signed, corporate CA) blanks the frame too, with its own bypass: open the preview
-   URL in its own tab, accept the certificate warning, reload the pane. The browser keeps that
-   exception for the origin.
-7. **`curl -I https://<preview-host>/<a-deep-route>`** returns no `X-Frame-Options`, and a CSP
-   `frame-ancestors` that includes the Contentstack app origin. Test a deep route, not the site
-   root, and confirm it holds after any redirect.
-8. **Nothing sits in front of the site that cannot render in a frame**: platform password
-   protection, an SSO screen setting `X-Frame-Options: DENY`, or basic auth.
-9. **If previewing `http://localhost`**, confirm the browser is not blocking it. Chrome's Local
-    Network Access policy blocks the app origin from framing localhost and only the user can grant
-    the permission.
-
-## Versions
-
-10. **Live Preview Utils v3.0+ and Delivery SDK v3.20.3+** for Visual Editor. **v4.4.4+** if using
-    `setPageContext()`.
-11. **Exactly one copy of the preview SDK is loaded.** An npm install plus an ESM or CDN
-    `<script type="module">` import of a different version produces behaviour differences that look
-    like configuration bugs.
-
-## Contract 1: init runs
-
-12. **The Live Preview Onboarding Check gets past "Live Preview SDK Not Initialized"** when the
-    preview panel loads. That item clears only on the SDK's init message, so while it sticks either
-    `init()` never ran on the client or it ran with a falsy `enable` (item 14).
-13. **`init()` runs on the client**, not in server-only code.
-14. **The enable flag parses as a boolean in the deployed build.** A string `"false"` is truthy.
-15. **`ssr` is set explicitly.** The automatic default keys off `stackSdk` and gets it wrong in both
-    directions: a CSR app without `stackSdk` silently becomes SSR, and an SSG site with `ssr: true`
-    produces blank screens rather than an error.
-16. **`stackDetails: { apiKey, environment }` is passed explicitly.** Since v2 the SDK no longer
-    derives the API key from the Stack object for edit tags.
-17. **`mode: "builder"` is set if Visual Editor is the target.** Visual Editor's own onboarding check
-    has a Verify Mode item that fails on `mode: "preview"`. Edit tags alone do not produce a canvas.
-
-## Contract 2: edit tags reach the DOM
-
-18. **A rendered field carries `data-cslp`**, formed as
-    `<content_type_uid>.<entry_uid>.<locale>.<field_path>`.
-19. **`addEditableTags(entry, contentTypeUid, true, locale)`** is called once on every fetched
-    top-level entry. The third argument must be `true` for React and JSX. References resolved with
-    `includeReference()` are rebased automatically; a separate call is only for hand-merged ones.
-20. **`$` keys are spread onto leaves and containers.** Scalars: the element rendering the value.
-    Multiple, reference and block fields: `entry.$.field` on the wrapper plus `entry.$["field__" + i]`
-    per instance, and an empty one keeps the wrapper with `VB_EmptyBlockParentClass`. Enumerate from
-    `Object.keys(entry.$)`, not from the JSX. See [edit-tags.md](edit-tags.md).
-21. **Reference paths mirror the data shape.** References come back as arrays:
-    `post.author[0].$?.name`, not `post.$?.author.name`.
-22. **For GraphQL**, connection wrappers are flattened and `system { uid, content_type_uid }` is
-    requested on every node, before `addEditableTags()` runs.
-
-## Contract 3: the hash reaches the fetch
-
-23. **Content requests hit a `*-preview.contentstack.com` host** during an active preview session.
-    Seeing `cdn.contentstack.io` or `graphql.contentstack.com` here is the single most common setup
-    failure, whatever the reported symptom was.
-24. **Those requests carry `live_preview` and `preview_token` headers** and return 200.
-25. **Every fetch path uses the initialized Stack instance.** A second instance, a hand-rolled
-    wrapper, or a BFF that bypasses it will keep serving published content.
-26. **The hash is never hardcoded or invented.** An unrecognised hash returns
-    `error_code 382, Please create tracker before starting live preview session`.
-27. **If the app proxies Contentstack through its own backend**, the hash is forwarded end to end.
-28. **SSR only: the Stack instance is built per request.** A module-level instance leaks one
-    editor's draft into other users' responses, including public traffic.
-29. **Caching is bypassed for preview requests.** Any cache on the preview path serves published
-    content after the host switch is already correct, and can serve preview output to real visitors.
-
-## Behaviour
-
-30. **Edit a field without saving.** The preview updates.
-31. **Hover a tagged element in Visual Editor.** It highlights, and clicking focuses the matching
-    field in the form panel.
-32. **Open entries from several content types**, including a nested route and one with no `url`
-    field. Each loads its own page.
-33. **Navigate inside the preview pane.** Preview context survives the navigation.
-34. **Load the public site in a normal browser tab.** No edit button, no `#cslp-tooltip` in the DOM,
-    and no preview response served from cache.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
index 46a4016..df318b1 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -11,29 +11,31 @@ Diagnose against this file. Use `frameworks.md` only for where `init()` is allow
 | Mode | `ssr` | How the hash travels | How updates arrive | Hard requirement |
 |---|---|---|---|---|
 | CSR + REST | `false` | postMessage; the SDK injects it into `stackSdk` | `onEntryChange` / `onLiveEdit` refetch, no reload | `stackSdk` is mandatory |
-| SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload, parent-driven; `onEntryChange` subscribers never fire | a fresh Delivery SDK instance per request |
+| SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload, parent-driven; `onEntryChange` never fires on edits | a fresh Delivery SDK instance per request |
 | CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch | manual host swap plus headers |
 | SSR + GraphQL | `true` | `request.query.live_preview` | full iframe reload | manual host swap plus headers |
 | SSG | `false` | postMessage | runs in CSR mode at runtime | `stackSdk`, and `init()` must be browser-only |
 
-## `onEntryChange` does not fire under `ssr: true`
+## `onEntryChange` does not fire on edits under `ssr: true`
 
-The SDK dispatches entry-change events only when `ssr` is `false`. In SSR mode the parent reloads
-the iframe with the new hash and the app never receives a client-side event. A subscriber registered
-in an SSR app is silently inert, so a `router.refresh()` or refetch wired into it never runs, and the
-integration looks correct while doing nothing on edit. Drive SSR updates from the request, not from a
-subscriber; if client-driven refresh is wanted, the route must be CSR.
+The SDK dispatches edit events to subscribers only when `ssr` is `false`. In SSR mode the parent
+reloads the iframe with the new hash instead. A subscriber registered in an SSR app still runs once at
+page load, which makes it look wired up, and then never runs again on an edit. A `router.refresh()` or
+refetch wired into it does nothing. Drive SSR updates from the request; if client-driven refresh is
+wanted, the route must be CSR.
 
 ## How `ssr` is resolved
 
 Precedence is `stackSdk.live_preview.ssr`, then `init({ ssr })`, then the automatic default.
 
-The automatic default keys off `stackSdk`: present means `ssr: false`, absent means `ssr: true`.
-This is the trap behind several setup failures. A CSR app that omits `stackSdk` silently gets SSR
-behaviour, and an SSG site initialized with `ssr: true` produces blank and black screens rather
-than a clean error.
+- An `ssr` in the Delivery SDK's `live_preview` config silently overrides `init({ ssr })`. Check
+  both places before trusting either.
+- The automatic default keys off `stackSdk`: present means `ssr: false`, absent means `ssr: true`.
+  A CSR app that omits `stackSdk` silently gets SSR behaviour.
+- An SSG site running with `ssr: true` reloads on every edit and re-serves its prerendered HTML, so
+  edits never appear. Users report it as blank screens, flicker or "nothing happens".
 
-Set it explicitly. Do not rely on the default.
+Set `ssr` explicitly, in one place.
 
 ## Mode-specific failures worth knowing before you prescribe
 
@@ -56,19 +58,19 @@ parameter, and a prerendered page never sees a query parameter, so the fetch is
 The documented answer is not to fight that, it is to run the preview path in **CSR mode**, where
 the hash arrives by postMessage instead and never needs the URL.
 
-Per [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-static-site-generator-ssg):
+Per [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/headless-cms/set-up-live-preview-for-static-site-generator-ssg):
 
 - Initialise Live Preview Utils with `ssr: false`
 - Pass `stackSdk`, which is mandatory in CSR mode
 - Configure the Delivery SDK with
-  `live_preview: { preview_token, enable: true, host: "rest-preview.contentstack.com" }`
+  `live_preview: { preview_token, enable: true, host: <region preview host> }`
 - Refresh through `onLiveEdit()`, so the browser refetches on each edit
 
 So an SSG site previews without a rebuild. The static build serves the shell, and the preview
 content is fetched client-side during the session.
 
-The common failure here is not SSG itself, it is an SSG site initialised with `ssr: true`. That
-produces blank and black screens rather than a clean error.
+The common failure here is not SSG itself, it is an SSG site running with `ssr: true`, which
+reloads into the same prerendered HTML on every edit.
 
 ### ISR: the genuinely hard case
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 4048af7..7192bd0 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -1,91 +1,170 @@
-# Setup: the documentation is the source of truth
+# New integrations
 
-For setup, follow the official Contentstack documentation. Do not reconstruct setup steps from
-memory and do not invent a procedure. Identify the framework and rendering mode, open the matching
-page, and follow it.
+SKILL.md step 2 sends new integrations here: nothing integrated yet, or Visual Editor or Timeline
+being added to a working Live Preview site.
 
-The rest of this skill exists for when the documented setup has been followed and something still
-does not work. That is a different job, and it is where the mined failure catalogue earns its keep.
+The official documentation is the source of truth. Link the right page and check the requirements
+below against it. Do not write setup procedures from memory.
 
-## Pick the page
+## Steps
 
-Establish framework and rendering mode first, then route.
+1. **Product.** Live Preview, Visual Editor, Timeline, or more than one. Visual Editor and Timeline
+   both build on a working Live Preview, so set that up first.
+2. **Framework and rendering mode.** Read them from the code when it is available (`package.json`,
+   `app/` vs `pages/`, how each route fetches). If the mode is not decided yet, as on a new site,
+   give both candidate pages with one line on how to choose, and ask nothing else.
+3. **Documentation page.** Pick it from the tables below.
+4. **Requirements for that mode.** Walk the matching sections under "Requirements the docs make easy
+   to miss" and confirm each one, in the code or with the user.
+5. **Verify.** Use the checks under "Verify". If verification fails, continue at step 3 of
+   SKILL.md with the check result you already have.
 
-### Start here regardless
+## Documentation pages
 
-- [Set Up Live Preview for your Website](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-your-website) — the setup hub
-- [How Live Preview Works](https://www.contentstack.com/docs/developers/set-up-live-preview/how-live-preview-works) — the model to reason from
-- [How Live Preview Works with SDK](https://www.contentstack.com/docs/headless-cms/how-live-preview-works-with-sdk) — how `ssr` is resolved and how the hash travels
+### Start here
+
+- [Set Up Live Preview for Your Website](https://www.contentstack.com/docs/headless-cms/set-up-live-preview-for-your-website), the setup hub
+- [How Live Preview Works](https://www.contentstack.com/docs/headless-cms/how-live-preview-works)
+- [How Live Preview Works with SDK](https://www.contentstack.com/docs/headless-cms/how-live-preview-works-with-sdk), how `ssr` is resolved and how the hash travels
 
 ### By framework and mode
 
 | Framework and mode | Page |
 |---|---|
-| Next.js App Router, CSR | [Live Preview Implementation for Next.js CSR App Router](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-nextjs-csr-app-router) |
-| Next.js App Router, SSR | [Live Preview Implementation for Next.js SSR App Router](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-nextjs-ssr-app-router) |
-| React, CSR | [Live Preview Implementation for ReactJS CSR Website](https://www.contentstack.com/docs/developers/set-up-live-preview/live-preview-implementation-for-reactjs-csr-website) |
-| Any framework, SSG | [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-static-site-generator-ssg) — runs in CSR mode, `ssr: false` |
-| Any framework, SSR over REST | [Set Up Live Preview with REST for Server-Side Rendering](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-with-rest-for-server-side-rendering) |
+| Next.js App Router, CSR | [Live Preview Implementation for Next.js CSR App Router](https://www.contentstack.com/docs/headless-cms/live-preview-implementation-for-nextjs-csr-app-router) |
+| Next.js App Router, SSR | [Live Preview Implementation for Next.js SSR App Router](https://www.contentstack.com/docs/headless-cms/live-preview-implementation-for-nextjs-ssr-app-router) |
+| React, CSR | [Live Preview Implementation for ReactJS CSR Website](https://www.contentstack.com/docs/headless-cms/live-preview-implementation-for-reactjs-csr-website) |
+| Any framework, SSG | [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/headless-cms/set-up-live-preview-for-static-site-generator-ssg), which runs in CSR mode with `ssr: false` |
+| Any framework, SSR over REST | [Set Up Live Preview with REST for Server-Side Rendering](https://www.contentstack.com/docs/headless-cms/set-up-live-preview-with-rest-for-server-side-rendering) |
+| Next.js Pages Router | No dedicated page. Use the SSR page for `getServerSideProps` and the SSG page for `getStaticProps` |
+| .NET | [Get Started with .Net SDK and Live Preview](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/dot-net/get-started-with-dot-net-sdk-and-live-preview); edit tags come from `Contentstack.Utils` |
 
-When app routing does not map 1:1 onto `Base URL + entry.url`, or `setPageContext()` is in play, the
-relevant page is [Custom Preview URLs](https://www.contentstack.com/docs/developers/set-up-live-preview/custom-preview-urls). Point to it rather than
-restating its pattern syntax; it is plan-gated and the page carries the current placeholder list.
+Where `init()` goes in each framework: [frameworks.md](frameworks.md).
 
-### Visual Editor, on top of a working Live Preview
+Routing that does not map 1:1 onto `Base URL + entry.url`, or `setPageContext()`:
+[Custom Preview URLs](https://www.contentstack.com/docs/headless-cms/custom-preview-urls). It is
+plan-gated; point to it rather than restating its pattern syntax.
 
-Visual Editor is not a separate integration. It is Live Preview plus edit tags plus `mode: "builder"`
-in `init()`, so Live Preview must work first, and a setup copied from a Live Preview guide will still
-fail Visual Editor's Verify Mode gate until the mode is changed from `"preview"`.
+### Visual Editor
 
-- [Set Up Visual Builder for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-builder/set-up-visual-builder-for-your-website)
-- [Set Up Visual Editor for Your Website](https://www.contentstack.com/docs/developers/set-up-visual-editor/set-up-visual-editor-for-your-website)
-- [Set Up Live Edit Tags for Entries with REST](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-edit-tags-for-entries-with-rest) — the `addEditableTags()` reference
+- [Set Up Visual Editor for Your Website](https://www.contentstack.com/docs/headless-cms/set-up-visual-editor-for-your-website)
+- [Set Up Live Edit Tags for Entries with REST](https://www.contentstack.com/docs/headless-cms/set-up-live-edit-tags-for-entries-with-rest), the `addEditableTags()` reference
 
 ### Timeline
 
-Timeline sits on the same Live Preview integration: `init()` in the frame and the Preview Service on
-the fetch. On top of that the site has to forward `preview_timestamp` next to the hash on every
-request. Its onboarding overlay links to this page:
+- [Set Up Timeline for Your Website](https://www.contentstack.com/docs/headless-cms/set-up-timeline-for-your-website)
+
+### Other
+
+- **Preview Sharing** is not an integration task. A content manager shares the link from the editor;
+  nothing on the site changes. [About Preview Sharing](https://www.contentstack.com/docs/headless-cms/about-preview-sharing).
+- **Starters.** [Kickstart Next.js](https://www.contentstack.com/docs/headless-cms/next) and its
+  siblings are working references. When a user's setup disagrees with a kickstart, the kickstart is
+  right.
+
+## Requirements the docs make easy to miss
+
+Confirm only the sections that apply.
+
+### Stack settings (every product)
+
+- Live Preview enabled under Settings → Visual Experience, with a default preview environment.
+- A Preview Token generated against the Delivery Token the site already uses. Never a management
+  token in client code.
+- Every environment and locale to preview has a Base URL, including the scheme (`https://`) and any
+  locale path segment.
+- Versions: Live Preview Utils v3.0+ for Visual Editor, v4.4.4+ for `setPageContext()`. On the legacy
+  `contentstack` JavaScript SDK, v3.20.3+; `@contentstack/delivery-sdk` releases are all newer. One
+  copy of the preview SDK on the page.
+
+### Every rendering mode
+
+- `init()` runs in the browser, once. In Next.js App Router that means a `"use client"` component.
+- Every content fetch goes through the Stack instance configured with `live_preview: { enable: true,
+  preview_token, host: <region preview host> }`. No second instance, no fetch helper that bypasses it.
+- Hosts match the stack's region: delivery, preview, GraphQL and the app host
+  (`clientUrlParams.host`). Region host names are in `wrong-region-hosts-in-sdk-and-preview-config`
+  in [faq-integration.md](faq-integration.md#wrong-region-hosts-in-sdk-and-preview-config).
+- No cache on the preview path: no CDN caching for the preview deployment, `cache: "no-store"` on
+  preview fetches.
+- Set `ssr` in one place. An `ssr` in the Stack's `live_preview` config overrides `init({ ssr })`.
+
+### CSR and SSG
+
+- `ssr: false` and `stackSdk` passed to `init()`. Without `stackSdk` the SDK defaults to SSR.
+- Refetch on edit with `ContentstackLivePreview.onEntryChange(fetchFn)`. Read the current route
+  inside the callback, not from a value captured at mount.
+
+### SSR
+
+- `ssr: true`. Updates arrive as a parent-driven reload, so do not rely on `onEntryChange`.
+- Build the Stack instance **per request**. A module-level instance leaks one editor's draft into
+  other visitors' responses.
+- Read `live_preview` (and `content_type_uid`, `entry_uid`, `preview_timestamp`) from each request
+  and call `stack.livePreviewQuery(query)` on every request, even when there is no hash, so the
+  instance resets. In Next.js 15, `searchParams` is a Promise: await it first. Snippet:
+  [frameworks.md](frameworks.md#nextjs-app-router).
+- `init()` takes `ssr: true` and no `stackSdk`.
+
+### GraphQL or a custom fetch layer
 
-- [Set Up Timeline](https://www.contentstack.com/docs/developers/set-up-timeline)
+- When the hash is present, switch to the region's preview host and add the `live_preview` and
+  `preview_token` headers. Otherwise use the delivery host. In a BFF or proxy, forward the hash end to
+  end.
 
-### Preview Sharing
+### Visual Editor (on top of Live Preview)
 
-Not an integration task. Once Visual Editor works, sharing a preview link is done from the editor by
-a content manager, and the link is valid for seven days. Nothing on the customer's site changes, so
-send them to the documentation rather than debugging their code:
-[Preview Sharing](https://www.contentstack.com/docs/content-managers/preview-sharing).
+- `mode: "builder"` and `stackDetails: { apiKey, environment }` in `init()`, where `environment` is
+  the environment being previewed. `mode` defaults to `"preview"`, which fails Visual Editor's Verify
+  Mode check, so a Live Preview config without `mode` needs it added. Builder mode throws without
+  `stackDetails`.
+- The environment's Base URL origin matches the previewed site exactly: scheme, `www` and port.
+  Visual Editor checks this; Live Preview does not.
+- `addEditableTags(entry, contentTypeUid, true, locale)` from `@contentstack/utils`, once per
+  top-level entry and after every refetch; `true` for React and JSX. GraphQL responses need
+  normalising first.
+- Spread `entry.$.field` onto the element that renders each value, plus container tags on multiple,
+  reference and block fields, or add and reorder controls never appear. Read
+  [edit-tags.md](edit-tags.md) before answering: it has the key conventions and the empty-block
+  contract.
+- Pass `include_applied_variants=true` on content requests if the stack uses variants.
 
-### Starters
+### Timeline (on top of Live Preview)
 
-[Kickstart Next.js](https://www.contentstack.com/docs/developers/kickstarts/next) and its siblings
-are working references. When a user's setup disagrees with a kickstart, the kickstart is right.
+- Forward `preview_timestamp` next to the hash on every request, and keep both on the URL across
+  client-side navigation.
 
-## What the documentation will not settle
+### Production
 
-These come up constantly and are not answered by any setup page. Say so plainly rather than
-guessing, and reach for `rendering-modes.md` and `faq-setup.md`.
+- Do not initialize preview on the production build (`enable: false`), or add
+  `editButton: { exclude: ["outsideLivePreviewPortal"], includeByQueryParameter: false }`, or the
+  Edit button renders for visitors.
 
-- **Next.js Pages Router.** Supported, but has no dedicated page. Use the SSR-over-REST page for
-  `getServerSideProps` and the SSG page for `getStaticProps`; the contracts are identical.
-- **ISR and framework cache or draft modes.** SSG *is* documented (see the table above). ISR is
-  not. Caching must be off for preview routes, and integrating with a framework's own
-  cache-invalidation or draft feature is out of scope.
-- **Edge runtimes.** No coverage anywhere. Untested rather than unsupported. Say that.
-- **GraphQL with edit tags.** Connection wrappers break `data-cslp` paths and need a
-  customer-side response normalizer. By design; see `graphql-connection-wrappers-break-cslp` in
-  `faq-visual-editor.md`.
-- **Frameworks with a starter but no support history.** A starter existing is not evidence the
-  combination is proven.
+## Reply shape
 
-## Two things worth stating before a user starts
+Docs link first, then only the requirements that apply to the user's framework, mode and product,
+each with a one-line reason, then the verification. Skip requirements the user already showed they
+meet. Snippets only where the docs make the shape easy to get wrong (`init()` options, tag spreading).
 
-**Version minimums.** Live Preview Utils v3.0+ and Delivery SDK v3.20.3+ for Visual Editor, and
-Live Preview Utils v4.4.4+ for `setPageContext()`. Load exactly one copy of the preview SDK; mixing
-an npm install with an ESM or CDN import of a different version produces behaviour that looks like
-a configuration bug.
+## Verify
 
-**`addEditableTags()` mutates and returns nothing.** It updates the entry passed as its first
-argument in place. Assigning its result gives you `undefined`, which is a common first-timer
-mistake. For React and JSX, `tagsAsObject` must be `true`; it defaults to `false`, which produces a
-string that React cannot spread.
+- **Live Preview:** the Onboarding Check card reads **Setup Complete**, and editing a field without
+  saving updates the pane.
+- **Visual Editor:** its check reaches **All Set!**, and hovering a field outlines it; clicking it
+  focuses that field in the form.
+- **Timeline:** its check reaches **All Set!**, and picking a future date shows the scheduled
+  content.
+- **Production:** the public site shows no Edit button and no `data-cslp` attributes when preview is
+  disabled there.
+
+Any failure here continues at SKILL.md step 3 with the check result.
+
+## Not covered by any setup page
+
+Say so plainly rather than guessing:
+
+- **ISR and framework draft or cache modes.** Caching must be off on preview routes; no official
+  hybrid recipe exists. See [rendering-modes.md](rendering-modes.md).
+- **Edge runtimes.** Untested rather than unsupported.
+- **GraphQL with edit tags.** Needs an application-side response normaliser. See
+  `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md`.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md b/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
index 1da6105..35728c5 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
@@ -3,37 +3,36 @@
 Find the reported symptom, go to the entry. Symptoms are worded the way users report them, not the
 way the underlying cause would be described.
 
-Setup entries come first because an unmet setup contract produces a large share of what gets
+Integration entries come first because an unmet contract produces a large share of what gets
 reported as behavioural. If the integration has never fully worked, work the four contracts in
 SKILL.md before reading anything below.
 
-
-## Setup and first integration
+## Integration
 
 | Symptom | Entry |
 |---|---|
-| Live Preview / Visual Editor loads the site fine, but edits made in the entry form or the right-hand panel nev… | [app-fetches-from-delivery-cdn-instead-of-preview-service](faq-setup.md#app-fetches-from-delivery-cdn-instead-of-preview-service) |
-| The Live Preview / Visual Editor pane is blank or shows "`<your-host>` refused to connect" | [iframe-blocked-by-x-frame-options-or-csp-frame-ancestors](faq-setup.md#iframe-blocked-by-x-frame-options-or-csp-frame-ancestors) |
-| Preview API requests fail with `{"error_message":"Please create tracker before starting live preview session",… | [error-382-create-tracker-before-starting-live-preview-session](faq-setup.md#error-382-create-tracker-before-starting-live-preview-session) |
-| Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar | [edit-tags-not-generated-or-not-spread](faq-setup.md#edit-tags-not-generated-or-not-spread) |
-| Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited | [preview-url-does-not-resolve-to-the-app-route](faq-setup.md#preview-url-does-not-resolve-to-the-app-route) |
-| Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump break… | [sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade](faq-setup.md#sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade) |
-| The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wr… | [environment-base-url-misconfigured-or-missing-for-a-locale](faq-setup.md#environment-base-url-misconfigured-or-missing-for-a-locale) |
-| The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or t… | [edit-button-rendered-outside-a-live-preview-session](faq-setup.md#edit-button-rendered-outside-a-live-preview-session) |
-| `Access to fetch at 'https://<region>-rest-preview.contentstack.com/v3/...' from origin '<site origin>' has be… | [cors-blocked-on-preview-api-requests](faq-setup.md#cors-blocked-on-preview-api-requests) |
-| Two opposite failures from the same mistake | [ssr-stack-instance-shared-or-duplicated](faq-setup.md#ssr-stack-instance-shared-or-duplicated) |
-| In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit… | [nextjs-app-router-init-must-run-in-a-client-component](faq-setup.md#nextjs-app-router-init-must-run-in-a-client-component) |
-| "Preview Service Not Enabled" shows in the preview panel on a setup that otherwise works | [legacy-management-token-setup-not-migrated-to-preview-token](faq-setup.md#legacy-management-token-setup-not-migrated-to-preview-token) |
-| Preview opens for pages that already exist on the main branch but never shows updates, and any page that exist… | [branch-or-alias-mismatch-between-app-token-and-entry](faq-setup.md#branch-or-alias-mismatch-between-app-token-and-entry) |
-| Live Preview never activates or the preview panel reports the service is not enabled, even though the stack se… | [wrong-region-hosts-in-sdk-and-preview-config](faq-setup.md#wrong-region-hosts-in-sdk-and-preview-config) |
-| Start Editing / the Edit button opens Visual Editor or the entry editor with `locale=en-us` even though the st… | [locale-defaults-to-en-us-in-init](faq-setup.md#locale-defaults-to-en-us-in-init) |
-| The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `… | [start-editing-button-cannot-be-hidden-in-editor-mode](faq-setup.md#start-editing-button-cannot-be-hidden-in-editor-mode) |
-| A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days… | [onboarding-check-card-not-visible-or-appears-unexpectedly](faq-setup.md#onboarding-check-card-not-visible-or-appears-unexpectedly) |
-| The "Visual Experience" / builder-mode option does not appear in the Contentstack navigation at all, so the te… | [visual-experience-navigation-missing-for-the-stack](faq-setup.md#visual-experience-navigation-missing-for-the-stack) |
-| The site renders in the preview pane but behaves as if logged out, or without personalization, locale or curre… | [third-party-cookies-blocked-inside-the-preview-iframe](faq-setup.md#third-party-cookies-blocked-inside-the-preview-iframe) |
-| A previously working local Live Preview setup breaks with `Access to fetch at 'http://localhost:5173/' from or… | [chrome-local-network-access-blocks-preview-of-localhost](faq-setup.md#chrome-local-network-access-blocks-preview-of-localhost) |
-| `data-cslp` attributes in the DOM contain `undefined` where the entry uid should be | [cslp-tags-contain-the-literal-string-undefined](faq-setup.md#cslp-tags-contain-the-literal-string-undefined) |
-| Live Preview on a statically generated site is unreliable or simply shows build-time content: blank or black s… | [ssg-preview-needs-csr-mode](faq-setup.md#ssg-preview-needs-csr-mode) |
+| Live Preview / Visual Editor loads the site fine, but edits made in the entry form or the right-hand panel nev… | [app-fetches-from-delivery-cdn-instead-of-preview-service](faq-integration.md#app-fetches-from-delivery-cdn-instead-of-preview-service) |
+| The Live Preview / Visual Editor pane is blank or shows "`<your-host>` refused to connect" | [iframe-blocked-by-x-frame-options-or-csp-frame-ancestors](faq-integration.md#iframe-blocked-by-x-frame-options-or-csp-frame-ancestors) |
+| Preview API requests fail with `{"error_message":"Please create tracker before starting live preview session",… | [error-382-create-tracker-before-starting-live-preview-session](faq-integration.md#error-382-create-tracker-before-starting-live-preview-session) |
+| Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar | [edit-tags-not-generated-or-not-spread](faq-integration.md#edit-tags-not-generated-or-not-spread) |
+| Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited | [preview-url-does-not-resolve-to-the-app-route](faq-integration.md#preview-url-does-not-resolve-to-the-app-route) |
+| Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump break… | [sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade](faq-integration.md#sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade) |
+| The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wr… | [environment-base-url-misconfigured-or-missing-for-a-locale](faq-integration.md#environment-base-url-misconfigured-or-missing-for-a-locale) |
+| The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or t… | [edit-button-rendered-outside-a-live-preview-session](faq-integration.md#edit-button-rendered-outside-a-live-preview-session) |
+| `Access to fetch at 'https://<region>-rest-preview.contentstack.com/v3/...' from origin '<site origin>' has be… | [cors-blocked-on-preview-api-requests](faq-integration.md#cors-blocked-on-preview-api-requests) |
+| Two opposite failures from the same mistake | [ssr-stack-instance-shared-or-duplicated](faq-integration.md#ssr-stack-instance-shared-or-duplicated) |
+| In a Next.js App Router project, Live Preview never activates: no hash in the URL, no SSR-mode detection, edit… | [nextjs-app-router-init-must-run-in-a-client-component](faq-integration.md#nextjs-app-router-init-must-run-in-a-client-component) |
+| "Preview Service Not Enabled" shows in the preview panel on a setup that otherwise works | [legacy-management-token-setup-not-migrated-to-preview-token](faq-integration.md#legacy-management-token-setup-not-migrated-to-preview-token) |
+| Preview opens for pages that already exist on the main branch but never shows updates, and any page that exist… | [branch-or-alias-mismatch-between-app-token-and-entry](faq-integration.md#branch-or-alias-mismatch-between-app-token-and-entry) |
+| Live Preview never activates or the preview panel reports the service is not enabled, even though the stack se… | [wrong-region-hosts-in-sdk-and-preview-config](faq-integration.md#wrong-region-hosts-in-sdk-and-preview-config) |
+| Start Editing / the Edit button opens Visual Editor or the entry editor with `locale=en-us` even though the st… | [locale-defaults-to-en-us-in-init](faq-integration.md#locale-defaults-to-en-us-in-init) |
+| The floating "Start Editing" button appears in the bottom-right corner of the site on every environment once `… | [start-editing-button-cannot-be-hidden-in-editor-mode](faq-integration.md#start-editing-button-cannot-be-hidden-in-editor-mode) |
+| A "Preview Service Not Enabled" popup appeared for teams that had not changed anything, then disappeared days… | [onboarding-check-card-not-visible-or-appears-unexpectedly](faq-integration.md#onboarding-check-card-not-visible-or-appears-unexpectedly) |
+| The "Visual Experience" / builder-mode option does not appear in the Contentstack navigation at all, so the te… | [visual-experience-navigation-missing-for-the-stack](faq-integration.md#visual-experience-navigation-missing-for-the-stack) |
+| The site renders in the preview pane but behaves as if logged out, or without personalization, locale or curre… | [third-party-cookies-blocked-inside-the-preview-iframe](faq-integration.md#third-party-cookies-blocked-inside-the-preview-iframe) |
+| A previously working local Live Preview setup breaks with `Access to fetch at 'http://localhost:5173/' from or… | [chrome-local-network-access-blocks-preview-of-localhost](faq-integration.md#chrome-local-network-access-blocks-preview-of-localhost) |
+| `data-cslp` attributes in the DOM contain `undefined` where the entry uid should be | [cslp-tags-contain-the-literal-string-undefined](faq-integration.md#cslp-tags-contain-the-literal-string-undefined) |
+| Live Preview on a statically generated site is unreliable or simply shows build-time content: blank or black s… | [ssg-preview-needs-csr-mode](faq-integration.md#ssg-preview-needs-csr-mode) |
 
 ## Preview runtime
 
@@ -45,7 +44,6 @@ SKILL.md before reading anything below.
 | Edits only appear after manually reloading the preview | [csr-edits-need-manual-refresh](faq-preview-runtime.md#csr-edits-need-manual-refresh) |
 | Preview works on the entry's own URL, but navigating within the site inside the preview panel breaks it — "Pag… | [spa-client-navigation-loses-preview-context](faq-preview-runtime.md#spa-client-navigation-loses-preview-context) |
 | `ContentstackLivePreview.hash` logs as an empty string, so the code that gates on it never switches to the pre… | [hash-empty-outside-the-preview-iframe](faq-preview-runtime.md#hash-empty-outside-the-preview-iframe) |
-| The very first `onEntryChange` fetch after opening the preview returns published data even though the entry wa… | [stale-first-fetch-when-editing-a-referenced-entry](faq-preview-runtime.md#stale-first-fetch-when-editing-a-referenced-entry) |
 | Live Preview works for top-level fields but an edit to an entry that is referenced inside another entry does n… | [legacy-management-token-preview-breaks-on-references](faq-preview-runtime.md#legacy-management-token-preview-breaks-on-references) |
 | One user sees an empty or partly empty page in Live Preview / Visual Editor while colleagues on the same stack… | [preview-renders-empty-for-a-restricted-user](faq-preview-runtime.md#preview-renders-empty-for-a-restricted-user) |
 | Ad slots, consent widgets, or other host-dependent third-party scripts intermittently fail to render inside Li… | [third-party-scripts-misbehave-inside-the-preview-iframe](faq-preview-runtime.md#third-party-scripts-misbehave-inside-the-preview-iframe) |

From 178debdcfd36002d2144f12e52913ffe3ff66710 Mon Sep 17 00:00:00 2001
From: Hitesh Shetty <hitesh.shetty@contentstack.com>
Date: Thu, 8 Oct 2026 16:18:53 +0530
Subject: [PATCH 19/21] docs(skills): state framework support per rendering
 mode, drop hedges

The SDK has no framework-specific code, so support follows from each
route's rendering mode. Replace the "not covered / untested / not proven"
notes with the contract that applies:

- Nuxt, Angular (incl. Angular SSR), SvelteKit, Astro and Gatsby each get
  init placement and the CSR or SSR contract that applies.
- New edge runtime section: the SSR contract, with no Node-only API needed.
- Non-JavaScript backends: data-cslp is a plain attribute; .NET, Java and
  Python utils ship addEditableTags, PHP and Ruby render it directly.
- rendering-modes.md coverage table maps each framework to its modes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../references/frameworks.md                  | 121 ++++++++----------
 .../references/rendering-modes.md             |  39 +++---
 .../references/setup-docs.md                  |   2 +-
 .../references/frameworks.md                  | 121 ++++++++----------
 .../references/rendering-modes.md             |  39 +++---
 .../references/setup-docs.md                  |   2 +-
 6 files changed, 146 insertions(+), 178 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md b/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
index 16f028e..491cb18 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -124,81 +124,70 @@ route.
 
 ## Nuxt
 
-Init in a client-only plugin. For page context, `useHead()` is the natural place to emit the
-`<meta>` tags, since Nuxt produces head tags natively and has no built-in hook for injecting window
-globals. As everywhere, page context only takes effect when **Custom Preview URLs** is enabled for
-the stack.
+Init in a client-only plugin (`plugins/live-preview.client.ts`). Nuxt in SSR mode follows the SSR
+contract: read the hash from the request in the server fetch and build the Stack per request. Nuxt
+with `ssr: false` follows the CSR contract. Visual Editor overlays are drawn by the SDK inside the
+iframe, so they work in both modes once edit tags are spread onto the rendered elements.
 
-The Nuxt CSR and SSR stories differ on whether Visual Editor overlays appear, and Contentstack's
-own material is inconsistent on this point. Verify against the actual app before promising overlay
-support.
+For page context, `useHead()` is the natural place to emit the `<meta>` tags. Page context only takes
+effect when **Custom Preview URLs** is enabled for the stack.
 
 ## Angular
 
-Init in `APP_INITIALIZER` or the root component. By contract this is the same as the React SPA
-case: CSR, `stackSdk` mandatory, `onEntryChange` for refresh. Only the placement idiom differs.
+Init in `APP_INITIALIZER` or the root component. A client-rendered Angular app follows the CSR
+contract: `ssr: false`, `stackSdk` passed, `onEntryChange` for refresh.
 
-Angular Universal (SSR) is not covered by documentation. Apply the SSR contract from
-`rendering-modes.md` and verify.
+Angular with server rendering (Angular SSR, formerly Universal) follows the SSR contract: guard
+`init()` to the browser with `isPlatformBrowser`, read the hash from the server request, and build
+the Stack per request.
 
 ## SvelteKit and Astro
 
-Both are SSR with a Node adapter in their documented form, so the SSR contract applies unchanged:
-hash from the request, fresh Stack instance per request, full reload on update.
+Both follow the contract of the rendering mode in use. Server-rendered routes (SvelteKit `load` on
+the server, Astro with a server adapter) take the SSR contract: hash from the request, fresh Stack
+instance per request, full reload on update. Client-only routes take the CSR contract. Init in
+`onMount` (SvelteKit) or a client-side `<script>` (Astro).
 
-Astro on some hosting platforms has an environment-variable parsing trap where the enable flag does
-not arrive as a boolean in the deployed build. If init appears not to run there, check the parsed
-value before checking anything else.
-
-Neither has support history. Do not present either as proven.
+On some hosts the enable flag reaches the deployed Astro build as a string rather than a boolean, and
+`"false"` is truthy. If init appears not to run, check the parsed value first.
 
 ## Gatsby
 
-Gatsby uses its own path via `ContentstackGatsby`, which previews without a rebuild. It needs
-`__typename` and `uid` in the GraphQL query, plus `addContentTypeUidFromTypename`.
-
-Two cautions. The published Gatsby starter is pinned to a Live Preview Utils v1.x release that
-predates Visual Editor, so it is not a valid Visual Editor reference. And whether Visual Editor
-works on a Gatsby static architecture is undocumented and unverified, not a settled yes. Scope
-Gatsby answers to Live Preview unless the user has verified Visual Editor themselves.
-
-Note that `getGatsbyDataFormat` still appears in the SDK's README and configuration docs but has no
-implementation in the current source. It was removed in v3. Do not recommend it.
-
-## No SDK, or a non-JavaScript backend
-
-A first-class population, not a fallback. This shape covers every BFF, middleware, proxy, and
-non-JavaScript server.
-
-There is no `init()` to place on the server. The whole server-side integration is the fetch branch
-from contract 3 in the parent skill: read the hash from the request, switch host, add the
-`live_preview` and `preview_token` headers, and bypass cache for that request. If the application
-proxies Contentstack through its own backend, the hash has to be forwarded end to end, from the
-browser through the backend and into the outbound header. The JavaScript Live Preview Utils SDK is
-still required in the rendered page, whatever the backend is — it is what talks to the editor.
-
-### .NET
-
-The best-covered non-JavaScript stack. Verified against the SDK sources, not inferred:
-
-- **Live Preview** is documented for both SSR and CSR in
-  [Get Started with .Net SDK and Live Preview](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/dot-net/get-started-with-dot-net-sdk-and-live-preview).
-  The hash is applied with `await contentstackClient.LivePreviewQueryAsync(dict)`, where `dict`
-  carries the request's query parameters. The same per-request-instance rule as every SSR stack
-  applies. Timeline is supported by the same SDK.
-- **Edit tags, and therefore Visual Editor,** are supported through the `Contentstack.Utils` package:
-  `Contentstack.Utils.addEditableTags(entry, contentTypeUid, tagsAsObject, locale, options)`, with an
-  `addTags` alias and an `AddEditableTagsOptions.UseLowerCaseLocale` flag. It is written for parity
-  with the JavaScript `addEditableTags` and emits the same `data-cslp` and `data-cslp-parent-field`
-  attributes, so everything in the edit-tag entries applies unchanged.
-- **Two gaps to be honest about.** The .NET Live Preview docs page does not mention edit tags or
-  Visual Editor at all, and none of the public .NET example apps (Blazor starter, Razor Pages,
-  GraphQL) wire up Live Preview. So a user setting up Visual Editor on .NET is working from the
-  utils SDK rather than from a walkthrough. Point them at `Contentstack.Utils` and the edit-tag
-  entries, and do not promise a reference app.
-
-### Other server SDKs
-
-Java, PHP, Python and Ruby have Live Preview get-started pages in the same SSR shape. Whether their
-utils packages implement edit tags has not been verified here — check the package before promising
-Visual Editor on those stacks, and say so if it is absent.
+Gatsby pages are prerendered, so preview runs in CSR mode: `ssr: false`, `stackSdk` passed, content
+refetched on edit through `onEntryChange`. No rebuild is needed. Fetch preview content with the
+Delivery SDK on the client; GraphQL data from the build is published content.
+
+Visual Editor needs edit tags on the client-fetched entries, as in any CSR app. The published Gatsby
+starter pins Live Preview Utils v1.x, which predates Visual Editor; upgrade to v3+ before adding
+`mode: "builder"`.
+
+`getGatsbyDataFormat` still appears in the SDK's README but no longer exists in the source (removed
+in v3). Do not recommend it.
+
+## Edge runtimes
+
+Nothing in the integration depends on a Node-only API. `init()` runs in the browser, and the server
+side is the fetch from contract 3: read the hash, switch host, add the `live_preview` and
+`preview_token` headers. That works the same in an edge function. Two things to confirm: the edge
+platform does not cache the preview response, and the Stack instance is created per request.
+
+## Non-JavaScript backends, BFFs and proxies
+
+Supported. The server-side integration is the fetch branch from contract 3 in SKILL.md: read the hash
+from the request, switch host, add the `live_preview` and `preview_token` headers, and bypass cache.
+A backend that proxies Contentstack must forward the hash end to end. The JavaScript Live Preview
+Utils SDK still runs in the rendered page, whatever the backend, because it is what talks to the
+editor.
+
+Edit tags are plain attributes: `data-cslp="<content_type_uid>.<entry_uid>.<locale>.<field_path>"`.
+Any server language can render them. Where a utils package has a helper, use it:
+
+| Backend | Live Preview | Edit tags |
+|---|---|---|
+| .NET | `LivePreviewQueryAsync(dict)` on the Delivery SDK client, with the request's query parameters. [Docs](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/dot-net/get-started-with-dot-net-sdk-and-live-preview) | `Contentstack.Utils.addEditableTags(entry, contentTypeUid, tagsAsObject, locale, options)` |
+| Java | the Delivery SDK's live preview query with the request's query parameters | `Utils.addEditableTags(entry, contentTypeUid, tagsAsObject, locale)` in `contentstack-utils-java` |
+| Python | the Delivery SDK's live preview query with the request's query parameters | `addEditableTags(entry, contentTypeUid, tagsAsObject, locale)` from `contentstack_utils` |
+| PHP, Ruby | the Delivery SDK's live preview query with the request's query parameters | no helper in the utils package; render `data-cslp` with the format above |
+
+All helpers match the JavaScript `addEditableTags`, so [edit-tags.md](edit-tags.md) applies to them
+unchanged.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
index df318b1..07fd46c 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -112,25 +112,20 @@ correctly.
 
 ## Framework and mode coverage
 
-Support here means documented and exercised, not merely possible.
-
-| Framework | CSR | SSR | SSG / ISR | Edge |
-|---|---|---|---|---|
-| Next.js App Router | documented, Visual Editor supported | documented, Visual Editor supported; fragile for empty-block affordances | runs as CSR at runtime; `searchParams` conflicts with fully static routes | no coverage |
-| Next.js Pages Router | supported | supported via `getServerSideProps` | supported via `getStaticProps`, runs in CSR mode | no coverage |
-| React SPA (Vite) | reference implementation | not applicable | not applicable | not applicable |
-| Nuxt | documented | documented | not applicable | no coverage |
-| Angular | documented | Universal not covered | not applicable | no coverage |
-| SvelteKit | not covered | documented | not covered | no coverage |
-| Astro | not covered | documented, Node adapter | static mode untested | environment-variable parsing trap on some hosts |
-| Gatsby | supported without a rebuild | not applicable | the intended mode | not applicable |
-| .NET | documented | documented; Visual Editor via `Contentstack.Utils` edit tags | not covered | no coverage |
-| Other server SDKs (Java, PHP, Python, Ruby) | not covered | Live Preview documented; edit-tag support unverified | not covered | no coverage |
-
-Two honest gaps in this table:
-
-- **Edge runtimes have no coverage anywhere.** Not in the documentation, the SDK source, or the
-  issue tracker. This is absence of evidence rather than a known incompatibility. If a user is on
-  an edge runtime, say that it is untested rather than guessing.
-- **Frameworks with a starter but no support history** cannot be distinguished between "works
-  cleanly" and "nobody uses it". Both produce zero tickets. Do not present them as proven.
+Every framework is supported. The SDK has no framework-specific code, so support follows from the
+rendering mode of each route: apply that mode's contract above. [frameworks.md](frameworks.md) covers
+where `init()` goes in each one.
+
+| Framework | CSR | SSR | SSG |
+|---|---|---|---|
+| Next.js App Router | client components | server components, dynamic routes | runs as CSR at runtime |
+| Next.js Pages Router | client fetch | `getServerSideProps` | `getStaticProps`, runs as CSR |
+| React SPA (Vite) | the default | — | — |
+| Nuxt | `ssr: false` | default Nuxt | prerendered routes run as CSR |
+| Angular | default | Angular SSR | prerendered routes run as CSR |
+| SvelteKit | client-only routes | server `load` | prerendered routes run as CSR |
+| Astro | client islands | server adapter | static output runs as CSR |
+| Gatsby | runtime client fetch | — | the default; preview runs as CSR |
+| .NET, Java, Python, PHP, Ruby | — | SSR contract; edit tags per [frameworks.md](frameworks.md) | — |
+
+Edge runtimes follow the SSR contract; nothing in it needs a Node-only API.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 7192bd0..11b96d3 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -165,6 +165,6 @@ Say so plainly rather than guessing:
 
 - **ISR and framework draft or cache modes.** Caching must be off on preview routes; no official
   hybrid recipe exists. See [rendering-modes.md](rendering-modes.md).
-- **Edge runtimes.** Untested rather than unsupported.
+- **Edge runtimes.** No dedicated page; they follow the SSR contract. See [frameworks.md](frameworks.md#edge-runtimes).
 - **GraphQL with edit tags.** Needs an application-side response normaliser. See
   `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md`.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md b/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
index 16f028e..491cb18 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -124,81 +124,70 @@ route.
 
 ## Nuxt
 
-Init in a client-only plugin. For page context, `useHead()` is the natural place to emit the
-`<meta>` tags, since Nuxt produces head tags natively and has no built-in hook for injecting window
-globals. As everywhere, page context only takes effect when **Custom Preview URLs** is enabled for
-the stack.
+Init in a client-only plugin (`plugins/live-preview.client.ts`). Nuxt in SSR mode follows the SSR
+contract: read the hash from the request in the server fetch and build the Stack per request. Nuxt
+with `ssr: false` follows the CSR contract. Visual Editor overlays are drawn by the SDK inside the
+iframe, so they work in both modes once edit tags are spread onto the rendered elements.
 
-The Nuxt CSR and SSR stories differ on whether Visual Editor overlays appear, and Contentstack's
-own material is inconsistent on this point. Verify against the actual app before promising overlay
-support.
+For page context, `useHead()` is the natural place to emit the `<meta>` tags. Page context only takes
+effect when **Custom Preview URLs** is enabled for the stack.
 
 ## Angular
 
-Init in `APP_INITIALIZER` or the root component. By contract this is the same as the React SPA
-case: CSR, `stackSdk` mandatory, `onEntryChange` for refresh. Only the placement idiom differs.
+Init in `APP_INITIALIZER` or the root component. A client-rendered Angular app follows the CSR
+contract: `ssr: false`, `stackSdk` passed, `onEntryChange` for refresh.
 
-Angular Universal (SSR) is not covered by documentation. Apply the SSR contract from
-`rendering-modes.md` and verify.
+Angular with server rendering (Angular SSR, formerly Universal) follows the SSR contract: guard
+`init()` to the browser with `isPlatformBrowser`, read the hash from the server request, and build
+the Stack per request.
 
 ## SvelteKit and Astro
 
-Both are SSR with a Node adapter in their documented form, so the SSR contract applies unchanged:
-hash from the request, fresh Stack instance per request, full reload on update.
+Both follow the contract of the rendering mode in use. Server-rendered routes (SvelteKit `load` on
+the server, Astro with a server adapter) take the SSR contract: hash from the request, fresh Stack
+instance per request, full reload on update. Client-only routes take the CSR contract. Init in
+`onMount` (SvelteKit) or a client-side `<script>` (Astro).
 
-Astro on some hosting platforms has an environment-variable parsing trap where the enable flag does
-not arrive as a boolean in the deployed build. If init appears not to run there, check the parsed
-value before checking anything else.
-
-Neither has support history. Do not present either as proven.
+On some hosts the enable flag reaches the deployed Astro build as a string rather than a boolean, and
+`"false"` is truthy. If init appears not to run, check the parsed value first.
 
 ## Gatsby
 
-Gatsby uses its own path via `ContentstackGatsby`, which previews without a rebuild. It needs
-`__typename` and `uid` in the GraphQL query, plus `addContentTypeUidFromTypename`.
-
-Two cautions. The published Gatsby starter is pinned to a Live Preview Utils v1.x release that
-predates Visual Editor, so it is not a valid Visual Editor reference. And whether Visual Editor
-works on a Gatsby static architecture is undocumented and unverified, not a settled yes. Scope
-Gatsby answers to Live Preview unless the user has verified Visual Editor themselves.
-
-Note that `getGatsbyDataFormat` still appears in the SDK's README and configuration docs but has no
-implementation in the current source. It was removed in v3. Do not recommend it.
-
-## No SDK, or a non-JavaScript backend
-
-A first-class population, not a fallback. This shape covers every BFF, middleware, proxy, and
-non-JavaScript server.
-
-There is no `init()` to place on the server. The whole server-side integration is the fetch branch
-from contract 3 in the parent skill: read the hash from the request, switch host, add the
-`live_preview` and `preview_token` headers, and bypass cache for that request. If the application
-proxies Contentstack through its own backend, the hash has to be forwarded end to end, from the
-browser through the backend and into the outbound header. The JavaScript Live Preview Utils SDK is
-still required in the rendered page, whatever the backend is — it is what talks to the editor.
-
-### .NET
-
-The best-covered non-JavaScript stack. Verified against the SDK sources, not inferred:
-
-- **Live Preview** is documented for both SSR and CSR in
-  [Get Started with .Net SDK and Live Preview](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/dot-net/get-started-with-dot-net-sdk-and-live-preview).
-  The hash is applied with `await contentstackClient.LivePreviewQueryAsync(dict)`, where `dict`
-  carries the request's query parameters. The same per-request-instance rule as every SSR stack
-  applies. Timeline is supported by the same SDK.
-- **Edit tags, and therefore Visual Editor,** are supported through the `Contentstack.Utils` package:
-  `Contentstack.Utils.addEditableTags(entry, contentTypeUid, tagsAsObject, locale, options)`, with an
-  `addTags` alias and an `AddEditableTagsOptions.UseLowerCaseLocale` flag. It is written for parity
-  with the JavaScript `addEditableTags` and emits the same `data-cslp` and `data-cslp-parent-field`
-  attributes, so everything in the edit-tag entries applies unchanged.
-- **Two gaps to be honest about.** The .NET Live Preview docs page does not mention edit tags or
-  Visual Editor at all, and none of the public .NET example apps (Blazor starter, Razor Pages,
-  GraphQL) wire up Live Preview. So a user setting up Visual Editor on .NET is working from the
-  utils SDK rather than from a walkthrough. Point them at `Contentstack.Utils` and the edit-tag
-  entries, and do not promise a reference app.
-
-### Other server SDKs
-
-Java, PHP, Python and Ruby have Live Preview get-started pages in the same SSR shape. Whether their
-utils packages implement edit tags has not been verified here — check the package before promising
-Visual Editor on those stacks, and say so if it is absent.
+Gatsby pages are prerendered, so preview runs in CSR mode: `ssr: false`, `stackSdk` passed, content
+refetched on edit through `onEntryChange`. No rebuild is needed. Fetch preview content with the
+Delivery SDK on the client; GraphQL data from the build is published content.
+
+Visual Editor needs edit tags on the client-fetched entries, as in any CSR app. The published Gatsby
+starter pins Live Preview Utils v1.x, which predates Visual Editor; upgrade to v3+ before adding
+`mode: "builder"`.
+
+`getGatsbyDataFormat` still appears in the SDK's README but no longer exists in the source (removed
+in v3). Do not recommend it.
+
+## Edge runtimes
+
+Nothing in the integration depends on a Node-only API. `init()` runs in the browser, and the server
+side is the fetch from contract 3: read the hash, switch host, add the `live_preview` and
+`preview_token` headers. That works the same in an edge function. Two things to confirm: the edge
+platform does not cache the preview response, and the Stack instance is created per request.
+
+## Non-JavaScript backends, BFFs and proxies
+
+Supported. The server-side integration is the fetch branch from contract 3 in SKILL.md: read the hash
+from the request, switch host, add the `live_preview` and `preview_token` headers, and bypass cache.
+A backend that proxies Contentstack must forward the hash end to end. The JavaScript Live Preview
+Utils SDK still runs in the rendered page, whatever the backend, because it is what talks to the
+editor.
+
+Edit tags are plain attributes: `data-cslp="<content_type_uid>.<entry_uid>.<locale>.<field_path>"`.
+Any server language can render them. Where a utils package has a helper, use it:
+
+| Backend | Live Preview | Edit tags |
+|---|---|---|
+| .NET | `LivePreviewQueryAsync(dict)` on the Delivery SDK client, with the request's query parameters. [Docs](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/dot-net/get-started-with-dot-net-sdk-and-live-preview) | `Contentstack.Utils.addEditableTags(entry, contentTypeUid, tagsAsObject, locale, options)` |
+| Java | the Delivery SDK's live preview query with the request's query parameters | `Utils.addEditableTags(entry, contentTypeUid, tagsAsObject, locale)` in `contentstack-utils-java` |
+| Python | the Delivery SDK's live preview query with the request's query parameters | `addEditableTags(entry, contentTypeUid, tagsAsObject, locale)` from `contentstack_utils` |
+| PHP, Ruby | the Delivery SDK's live preview query with the request's query parameters | no helper in the utils package; render `data-cslp` with the format above |
+
+All helpers match the JavaScript `addEditableTags`, so [edit-tags.md](edit-tags.md) applies to them
+unchanged.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
index df318b1..07fd46c 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -112,25 +112,20 @@ correctly.
 
 ## Framework and mode coverage
 
-Support here means documented and exercised, not merely possible.
-
-| Framework | CSR | SSR | SSG / ISR | Edge |
-|---|---|---|---|---|
-| Next.js App Router | documented, Visual Editor supported | documented, Visual Editor supported; fragile for empty-block affordances | runs as CSR at runtime; `searchParams` conflicts with fully static routes | no coverage |
-| Next.js Pages Router | supported | supported via `getServerSideProps` | supported via `getStaticProps`, runs in CSR mode | no coverage |
-| React SPA (Vite) | reference implementation | not applicable | not applicable | not applicable |
-| Nuxt | documented | documented | not applicable | no coverage |
-| Angular | documented | Universal not covered | not applicable | no coverage |
-| SvelteKit | not covered | documented | not covered | no coverage |
-| Astro | not covered | documented, Node adapter | static mode untested | environment-variable parsing trap on some hosts |
-| Gatsby | supported without a rebuild | not applicable | the intended mode | not applicable |
-| .NET | documented | documented; Visual Editor via `Contentstack.Utils` edit tags | not covered | no coverage |
-| Other server SDKs (Java, PHP, Python, Ruby) | not covered | Live Preview documented; edit-tag support unverified | not covered | no coverage |
-
-Two honest gaps in this table:
-
-- **Edge runtimes have no coverage anywhere.** Not in the documentation, the SDK source, or the
-  issue tracker. This is absence of evidence rather than a known incompatibility. If a user is on
-  an edge runtime, say that it is untested rather than guessing.
-- **Frameworks with a starter but no support history** cannot be distinguished between "works
-  cleanly" and "nobody uses it". Both produce zero tickets. Do not present them as proven.
+Every framework is supported. The SDK has no framework-specific code, so support follows from the
+rendering mode of each route: apply that mode's contract above. [frameworks.md](frameworks.md) covers
+where `init()` goes in each one.
+
+| Framework | CSR | SSR | SSG |
+|---|---|---|---|
+| Next.js App Router | client components | server components, dynamic routes | runs as CSR at runtime |
+| Next.js Pages Router | client fetch | `getServerSideProps` | `getStaticProps`, runs as CSR |
+| React SPA (Vite) | the default | — | — |
+| Nuxt | `ssr: false` | default Nuxt | prerendered routes run as CSR |
+| Angular | default | Angular SSR | prerendered routes run as CSR |
+| SvelteKit | client-only routes | server `load` | prerendered routes run as CSR |
+| Astro | client islands | server adapter | static output runs as CSR |
+| Gatsby | runtime client fetch | — | the default; preview runs as CSR |
+| .NET, Java, Python, PHP, Ruby | — | SSR contract; edit tags per [frameworks.md](frameworks.md) | — |
+
+Edge runtimes follow the SSR contract; nothing in it needs a Node-only API.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 7192bd0..11b96d3 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -165,6 +165,6 @@ Say so plainly rather than guessing:
 
 - **ISR and framework draft or cache modes.** Caching must be off on preview routes; no official
   hybrid recipe exists. See [rendering-modes.md](rendering-modes.md).
-- **Edge runtimes.** Untested rather than unsupported.
+- **Edge runtimes.** No dedicated page; they follow the SSR contract. See [frameworks.md](frameworks.md#edge-runtimes).
 - **GraphQL with edit tags.** Needs an application-side response normaliser. See
   `graphql-connection-wrappers-break-cslp` in `faq-visual-editor.md`.

From ca37a8ab74d9aecb7959ab297f7d83f75b9d55ff Mon Sep 17 00:00:00 2001
From: Hitesh Shetty <hitesh.shetty@contentstack.com>
Date: Thu, 8 Oct 2026 16:31:30 +0530
Subject: [PATCH 20/21] docs(router): route preview questions away from
 dx-delivery-sdk

The dx-delivery-sdk row claimed Live Preview setup, Visual Builder support
and SSR preview handling, which overlaps the live-preview support skill.
Keep the row on Delivery SDK query code and point preview questions to
the Live Preview and Visual Editor Support Assistant.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 codex/AGENTS.md            | 2 +-
 cursor/rules/00-router.mdc | 2 +-
 skills/CLAUDE.md           | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/codex/AGENTS.md b/codex/AGENTS.md
index 9996622..2b1141b 100644
--- a/codex/AGENTS.md
+++ b/codex/AGENTS.md
@@ -7,7 +7,7 @@ Use the table below to route a user request to the right skill. Each row maps a
 | Use when users ask about Contentstack Brand Kit, Voice Profiles, Knowledge Vault, brand voice, tone, style rules, on-brand AI generation, setup, governance, or API usage. Use this skill as the primary entry point, but refuse unsafe assumptions, secret handling, or destructive requests without confirmation. | [Brand Kit Assistant](./brand-kit-assistant/SKILL.md) |
 | Use when users want to migrate, move, switch, port, or re-platform from Contentful to Contentstack, including content models, content, assets, locales, application integrations, website code, migration prerequisites, migration progress checks, or post-migration validation. | [contentstack-migration-companion](./migration-companion/SKILL.md) |
 | Use when a user wants to migrate Contentstack Delivery SDK code from JavaScript to TypeScript. | [dx-migrate-js-to-ts-sdk](./dx-migrate-js-to-ts-sdk/SKILL.md) |
-| Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, Live Preview setup, Visual Builder support, SSR preview handling, or debugging SDK query chains. | [dx-delivery-sdk](./dx-delivery-sdk/SKILL.md) |
+| Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, or debugging SDK query chains. For Live Preview, Visual Editor or Visual Builder, and Timeline questions, use the Live Preview and Visual Editor Support Assistant instead. | [dx-delivery-sdk](./dx-delivery-sdk/SKILL.md) |
 | Use for any Contentstack Visual Experience question: Live Preview, Visual Editor or Visual Builder (the same product), Timeline, the Onboarding Check, edit tags, preview tokens and hosts, and Visual Experience settings. Covers how they work, setting them up in any framework, configuration, and debugging: the SDK installed but nothing happening, a blank or unreachable preview pane, a stuck Onboarding Check, edits that never appear, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, nothing editable on the canvas, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](./cms-live-preview-visual-editor-support-assistant/SKILL.md) |
 | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](./cms-data-modeling-best-practices/SKILL.md) |
 | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](./cms-entries/SKILL.md) |
diff --git a/cursor/rules/00-router.mdc b/cursor/rules/00-router.mdc
index 3f26a91..4439a4f 100644
--- a/cursor/rules/00-router.mdc
+++ b/cursor/rules/00-router.mdc
@@ -12,7 +12,7 @@ Use the table below to route a user request to the right skill. Each row maps a
 | Use when users ask about Contentstack Brand Kit, Voice Profiles, Knowledge Vault, brand voice, tone, style rules, on-brand AI generation, setup, governance, or API usage. Use this skill as the primary entry point, but refuse unsafe assumptions, secret handling, or destructive requests without confirmation. | [Brand Kit Assistant](../../skills/brand-kit-assistant/SKILL.md) |
 | Use when users want to migrate, move, switch, port, or re-platform from Contentful to Contentstack, including content models, content, assets, locales, application integrations, website code, migration prerequisites, migration progress checks, or post-migration validation. | [contentstack-migration-companion](../../skills/migration-companion/SKILL.md) |
 | Use when a user wants to migrate Contentstack Delivery SDK code from JavaScript to TypeScript. | [dx-migrate-js-to-ts-sdk](../../skills/dx-migrate-js-to-ts-sdk/SKILL.md) |
-| Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, Live Preview setup, Visual Builder support, SSR preview handling, or debugging SDK query chains. | [dx-delivery-sdk](../../skills/dx-delivery-sdk/SKILL.md) |
+| Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, or debugging SDK query chains. For Live Preview, Visual Editor or Visual Builder, and Timeline questions, use the Live Preview and Visual Editor Support Assistant instead. | [dx-delivery-sdk](../../skills/dx-delivery-sdk/SKILL.md) |
 | Use for any Contentstack Visual Experience question: Live Preview, Visual Editor or Visual Builder (the same product), Timeline, the Onboarding Check, edit tags, preview tokens and hosts, and Visual Experience settings. Covers how they work, setting them up in any framework, configuration, and debugging: the SDK installed but nothing happening, a blank or unreachable preview pane, a stuck Onboarding Check, edits that never appear, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, nothing editable on the canvas, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](../../skills/cms-live-preview-visual-editor-support-assistant/SKILL.md) |
 | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](../../skills/cms-data-modeling-best-practices/SKILL.md) |
 | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](../../skills/cms-entries/SKILL.md) |
diff --git a/skills/CLAUDE.md b/skills/CLAUDE.md
index 9996622..2b1141b 100644
--- a/skills/CLAUDE.md
+++ b/skills/CLAUDE.md
@@ -7,7 +7,7 @@ Use the table below to route a user request to the right skill. Each row maps a
 | Use when users ask about Contentstack Brand Kit, Voice Profiles, Knowledge Vault, brand voice, tone, style rules, on-brand AI generation, setup, governance, or API usage. Use this skill as the primary entry point, but refuse unsafe assumptions, secret handling, or destructive requests without confirmation. | [Brand Kit Assistant](./brand-kit-assistant/SKILL.md) |
 | Use when users want to migrate, move, switch, port, or re-platform from Contentful to Contentstack, including content models, content, assets, locales, application integrations, website code, migration prerequisites, migration progress checks, or post-migration validation. | [contentstack-migration-companion](./migration-companion/SKILL.md) |
 | Use when a user wants to migrate Contentstack Delivery SDK code from JavaScript to TypeScript. | [dx-migrate-js-to-ts-sdk](./dx-migrate-js-to-ts-sdk/SKILL.md) |
-| Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, Live Preview setup, Visual Builder support, SSR preview handling, or debugging SDK query chains. | [dx-delivery-sdk](./dx-delivery-sdk/SKILL.md) |
+| Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, or debugging SDK query chains. For Live Preview, Visual Editor or Visual Builder, and Timeline questions, use the Live Preview and Visual Editor Support Assistant instead. | [dx-delivery-sdk](./dx-delivery-sdk/SKILL.md) |
 | Use for any Contentstack Visual Experience question: Live Preview, Visual Editor or Visual Builder (the same product), Timeline, the Onboarding Check, edit tags, preview tokens and hosts, and Visual Experience settings. Covers how they work, setting them up in any framework, configuration, and debugging: the SDK installed but nothing happening, a blank or unreachable preview pane, a stuck Onboarding Check, edits that never appear, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, nothing editable on the canvas, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](./cms-live-preview-visual-editor-support-assistant/SKILL.md) |
 | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](./cms-data-modeling-best-practices/SKILL.md) |
 | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](./cms-entries/SKILL.md) |

From 5a8d2ec3f6133ad842289d887c3c9fe56a3b6dac Mon Sep 17 00:00:00 2001
From: Hitesh Shetty <hitesh.shetty@contentstack.com>
Date: Wed, 14 Oct 2026 11:55:49 +0530
Subject: [PATCH 21/21] fix(skills): correct five support-assistant claims
 against the SDK code

Checked against live-preview-utils v4.5.3 and the Visual Editor and
Live Preview panel code:

- Live Preview joins the Base URL and entry url as strings, so a bypass
  token in the Base URL ends up holding the path. Drop that advice and
  add base-url-query-string-corrupts-preview-url.
- stackSdk is optional. Without it ssr defaults to true, so ssr: false
  has to be passed explicitly.
- Importing the SDK creates #cslp-tooltip before init() runs. Production
  needs PURGE_PREVIEW_SDK or a preview-only dynamic import, not
  enable: false alone.
- The "scroll" NO_REQUEST_LISTENER_FOUND message comes from clicking the
  Live Preview edit button where the parent has no scroll listener.
- The empty-block button renders only in Visual Editor, needs a field
  schema for its data-cslp path, and one invalid wrapper can stop the
  others rendering.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../references/console-noise.md               |  5 +++-
 .../references/contact-support.md             |  2 +-
 .../references/faq-integration.md             | 23 +++++++++++++++----
 .../references/faq-visual-editor.md           |  7 +++---
 .../references/frameworks.md                  |  6 +++--
 .../references/rendering-modes.md             |  4 ++--
 .../references/setup-docs.md                  |  6 +++--
 .../references/symptom-index.md               |  1 +
 .../references/console-noise.md               |  5 +++-
 .../references/contact-support.md             |  2 +-
 .../references/faq-integration.md             | 23 +++++++++++++++----
 .../references/faq-visual-editor.md           |  7 +++---
 .../references/frameworks.md                  |  6 +++--
 .../references/rendering-modes.md             |  4 ++--
 .../references/setup-docs.md                  |  6 +++--
 .../references/symptom-index.md               |  1 +
 16 files changed, 76 insertions(+), 32 deletions(-)

diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md b/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
index c629387..6d9c226 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
@@ -18,7 +18,10 @@ problem.** Say so and move to the network tab.
 Two different postMessage errors from the same library, both routine:
 
 - `NO_REQUEST_LISTENER_FOUND` ("No request listener found for event …"): one side sent a request
-  the other side has no handler for, for example a `scroll` event during load.
+  the other side has no handler for. The common one is `scroll`: the Live Preview edit button sends
+  it on click, and Visual Editor (or the Live Preview panel before the init handshake) registers no
+  `scroll` listener. It shows as an uncaught promise rejection in the site's console. It says a
+  button was clicked, nothing about whether tags resolve.
 - `No ack listener found`: an acknowledgement arrived after its sender stopped waiting, typically
   during load or teardown.
 
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md b/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
index b0ba0b4..ae730c7 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
@@ -20,7 +20,7 @@ with Contentstack Support.
 | Symptom | What it actually is |
 |---|---|
 | A previously working `localhost` preview stops working, console shows a local network access error | Chrome's Local Network Access policy now blocks the app origin from framing localhost. Only the user can grant the permission, in the browser. |
-| Preview pane blank, and the site sits behind platform password protection or third-party SSO | Those screens set `X-Frame-Options: DENY` on themselves. Contentstack cannot inject headers into a browser-originated iframe request. Workarounds, cheapest first: enable **Open in New Tab**, which renders the site outside the iframe so frame headers stop applying; otherwise disable protection on the preview deployment, put a bypass token in the Base URL (scoped to the preview deployment and rotated, since every stack user can read it), or front it with a server-side proxy that strips the header. |
+| Preview pane blank, and the site sits behind platform password protection or third-party SSO | Those screens set `X-Frame-Options: DENY` on themselves. Contentstack cannot inject headers into a browser-originated iframe request. Workarounds, cheapest first: enable **Open in New Tab**, which renders the site outside the iframe so frame headers stop applying; otherwise disable protection on the preview deployment, or front it with a server-side proxy that strips the header. A bypass token in the Base URL does not work: see `base-url-query-string-corrupts-preview-url` in faq-integration.md. |
 | Ad slots, consent widgets, or other host-dependent third-party scripts misbehave in the pane | Those scripts key off the top-level origin, which is the Contentstack app inside an iframe. Expected, not a preview defect. |
 
 ## How to hand it over
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
index 36bde9a..db45d81 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
@@ -43,7 +43,7 @@ setup, use `setup-docs.md` instead.
 - **fix**:
   1. Remove `X-Frame-Options` for the preview host and use CSP instead, allowing the Contentstack app origin for the stack's region: `Content-Security-Policy: frame-ancestors 'self' https://app.contentstack.com;` (for example `https://eu-app.contentstack.com` in EU). `https://*.contentstack.com` is the broader fallback. `X-Frame-Options` has no allowlist syntax; a bare `SAMEORIGIN` always wins.
   2. Apply the header on every route, not just the site root. A route that redirects to a different hostname than the configured Base URL will also fail.
-  3. If the deployment sits behind platform password protection, note that no header or query parameter can be injected into a browser-originated iframe request from Contentstack. Options: disable protection on the preview deployment, use a bypass token embedded in the Base URL (every stack user can read the Base URL, so scope the token to the preview deployment and rotate it), put a server-side proxy in front that injects the header, or use Live Preview → Open in New Tab (a plan-gated feature that renders outside the iframe).
+  3. If the deployment sits behind platform password protection, note that no header or query parameter can be injected into a browser-originated iframe request from Contentstack. Options: disable protection on the preview deployment, put a server-side proxy in front that injects the header, or use Live Preview → Open in New Tab (a plan-gated feature that renders outside the iframe). Do not put a bypass token in the Base URL: Live Preview appends the entry path into the last query value, so the token and the path both break. See `base-url-query-string-corrupts-preview-url`.
   4. Third-party SSO screens that themselves set `X-Frame-Options: DENY` cannot render in the iframe at all. Use Open in New Tab, which renders the preview outside the iframe so those screens can load.
   5. On the Live Preview Onboarding Check this shows as **Live Preview SDK Not Initialized**, not "Could Not Connect to Website". The reachability gate is a `no-cors` request, which succeeds on any HTTP response, so frame headers and auth screens pass it.
 - **verification**: `curl -I https://<preview-host>/<some-deep-route>` and confirm no `X-Frame-Options` and a `frame-ancestors` value that includes the Contentstack app origin. Reload Live Preview; the pane should render.
@@ -101,6 +101,19 @@ setup, use `setup-docs.md` instead.
 
 ---
 
+### base-url-query-string-corrupts-preview-url
+- **bucket**: integration
+- **symptom**: Live Preview opens the home page or the wrong page instead of the entry. The URL in the pane has the entry path glued onto the end of the last query parameter, for example `https://site.example/?token=abc/my-page` (or `abc%2Fmy-page` under SSR), instead of on the path. Most often seen when the Base URL carries a hosting-platform protection-bypass token. Visual Editor opens the same page correctly.
+- **frameworks**: framework-agnostic (stack configuration)
+- **rendering_modes**: any
+- **root_cause**: Live Preview builds the preview URL by joining the environment Base URL and the entry's `url` as strings, then parsing the result. A Base URL that ends in a query string therefore receives the path inside the last query value: the token is corrupted and the path stays `/`. Visual Editor parses the Base URL first and keeps its query string, which is why the two products disagree on the same entry.
+- **fix**:
+  1. Remove the query string from the Base URL. Keep one only when it ends in a parameter the app deliberately reads the path from (`?path=`).
+  2. For a protected deployment, do not use a bypass token in the Base URL. Remove protection on the preview deployment, front it with a proxy that adds the credential, or restrict an unprotected preview deployment another way (for example by IP).
+- **verification**: Open an entry in Live Preview. The pane URL carries the entry path on the path, not inside a query value, and the right page renders.
+
+---
+
 ### sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade
 - **bucket**: integration
 - **symptom**: Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump breaks a previously working integration: `setConfigFromParams` is no longer callable, `ReferenceError: window is not defined` in server code, the Edit button suddenly renders in production, or `Live_Preview_SDK: To use edit tags, you must provide the stack API key`.
@@ -138,12 +151,12 @@ setup, use `setup-docs.md` instead.
 - **symptom**: The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or the `#cslp-tooltip` button element is injected into `document.body` on production even when not visible (usually caught in an accessibility audit). Sometimes intermittent, correlating with client-side route changes rather than fresh page loads.
 - **frameworks**: Next.js (App Router especially), React
 - **rendering_modes**: CSR, SSR
-- **root_cause**: With `editButton.enable: true` and no `exclude`, the SDK renders the button on any page where it is initialized, inside the iframe or not. It never checks the `live_preview` hash or any session signal. `inIframe()` only matters when `exclude` is set, and a `?cslp-buttons=` query parameter overrides `exclude` unless `includeByQueryParameter: false`. Teams that gate `init()` on a server-read hash also get bitten by App Router soft navigation, which does not re-run that server-side gate while the SDK's button instance persists across route changes.
+- **root_cause**: With `editButton.enable: true` and no `exclude` (the defaults), the SDK renders the button on any page that loads it, inside the iframe or not. It creates `#cslp-tooltip` when the module is **imported**, before `init()` runs, so a production build that imports the SDK and never calls `init()` still has the element; config passed to `init()` is applied only afterwards. It never checks the `live_preview` hash or any session signal. `inIframe()` only matters when `exclude` is set, and a `?cslp-buttons=` query parameter overrides `exclude` unless `includeByQueryParameter: false`. Teams that gate `init()` on a server-read hash also get bitten by App Router soft navigation, which does not re-run that server-side gate while the SDK's button instance persists across route changes.
 - **fix**:
   1. Add `editButton: { enable: true, exclude: ['outsideLivePreviewPortal'], includeByQueryParameter: false }`. Outside the iframe the button no longer renders, a query parameter cannot bring it back, and Live Preview inside the pane keeps working.
-  2. If Live Preview is not used on production at all, do not initialize it there: `enable: false` (with the default `cleanCslpOnProduction: true`, which then strips `data-cslp`), or the `PURGE_PREVIEW_SDK=true` build flag, which no-ops the SDK entirely.
+  2. If Live Preview is not used on production at all, keep the SDK out of the production bundle: build with `PURGE_PREVIEW_SDK=true` (or `REACT_APP_PURGE_PREVIEW_SDK=true`), which swaps in a no-op SDK and skips the import-time button, or load the SDK with a dynamic import that runs only for preview requests. The flag works only if the bundler exposes `process.env` to browser code. Skipping `init()` or passing `enable: false` is not enough on its own, because the element is created at import.
   3. Do not rely on a server-side hash check alone in an App Router app; soft navigation will not re-evaluate it.
-- **verification**: Load the production URL in a normal tab with DevTools open. `document.getElementById('cslp-tooltip')` should be absent, and no `data-cslp` attributes should be present if the SDK runs with `enable: false`.
+- **verification**: Load the production URL in a normal tab with DevTools open. `document.getElementById('cslp-tooltip')` returns `null`, and no `data-cslp` attributes are present if the SDK runs with `enable: false`.
 
 ---
 
@@ -370,7 +383,7 @@ setup, use `setup-docs.md` instead.
 - **root_cause**: Two halves of the same mistake. A prerendered page cannot read query parameters at request time, so the `live_preview` hash can never reach a build-time data fetch — static output is published-only content by definition. And in SSR mode the SDK reloads the page after every edit, which on a static site just re-serves the same prerendered HTML. SSG is supported, but only in CSR mode.
 - **fix**:
   1. Initialize with `ssr: false`. Edits then fire an `onEntryChange` callback instead of a page reload.
-  2. Pass `stackSdk` in the init config. It is mandatory in CSR mode, and it is also what the SDK uses to default `ssr`, so omitting it silently selects SSR behaviour.
+  2. Pass `stackSdk` in the init config so the SDK can inject the hash into the Delivery SDK. It is optional, but it is also what the SDK uses to default `ssr`: without it, and without an explicit `ssr: false`, the SDK silently selects SSR behaviour.
   3. Implement `onEntryChange`: subscribe on the client, refetch the entry, update the UI. No rebuild is needed.
   4. Remove any `Stack.livePreviewQuery()` call from middleware. It is SSR-only and must not run on a static route.
   5. If the site mixes static and server-rendered routes, make the mode conditional per route rather than per app.
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
index 083688a..21acb23 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -9,7 +9,7 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 
 ### cslp-not-rebased-to-referenced-entry
 - **bucket**: visual-editor
-- **symptom**: Edit tags on fields that come from a **referenced** entry do nothing when clicked. Tags on the page's own fields work. Console may show `{code: 'NO_REQUEST_LISTENER_FOUND', message: 'contentstack-adv-post-message: No request listener found for event "scroll"'}`, but that message is routine and appears on healthy setups too — treat it as incidental, not as the identifying evidence. Diagnose from the tags themselves.
+- **symptom**: Edit tags on fields that come from a **referenced** entry do nothing when clicked. Tags on the page's own fields work. Console may show `{code: 'NO_REQUEST_LISTENER_FOUND', message: 'contentstack-adv-post-message: No request listener found for event "scroll"'}`, but that message only says the Live Preview edit button was clicked where the parent has no `scroll` listener, and it appears on healthy setups too — treat it as incidental, not as the identifying evidence. Diagnose from the tags themselves.
 - **frameworks**: React, Next.js, framework-agnostic
 - **rendering_modes**: CSR, SSR
 - **root_cause**: `addEditableTags()` rebases a tag onto the referenced entry only when the resolved reference object carries both `uid` and `_content_type_uid`. Without them the tag stays anchored to the parent entry (`product.<parent_entry_uid>.<locale>.<reference_field>.<index>.<field>`), so there is no entry to navigate to. Common causes: references fetched separately and merged by hand (which drops those keys), or any GraphQL response, where those keys sit under `system` instead of at the top level. Hardcoding `data-cslp` by hand is a related failure — the referenced entry's uid and content type uid are not the ones being edited.
@@ -59,12 +59,13 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 - **symptom**: A page or component with an empty modular-block / multiple field shows no "+ Add Component" affordance, so authors have to go to the form panel to add the first block.
 - **frameworks**: React, Next.js
 - **rendering_modes**: CSR, SSR
-- **root_cause**: The empty-block placeholder only renders when the wrapper carries **both** the `VB_EmptyBlockParentClass` class (exported by the SDK; its literal value is `visual-builder__empty-block-parent`) and a `data-cslp` pointing at the block field itself. Miss either and there is nothing for the canvas to attach the affordance to.
+- **root_cause**: The empty-block placeholder only renders when the wrapper carries **both** the `VB_EmptyBlockParentClass` class (exported by the SDK; its literal value is `visual-builder__empty-block-parent`) and a `data-cslp` pointing at the block field itself. Miss either and there is nothing for the canvas to attach the affordance to. Three more conditions: it renders only inside Visual Editor, not in Live Preview; Visual Editor must return a field schema for that content type and field path, so a `data-cslp` with a wrong path renders nothing; and it is drawn when the DOM changes after the editor handshake. The button label is "Add <field display name>", not a fixed string.
 - **fix**:
   1. Confirm the wrapper renders both the class and a `data-cslp` pointing at the block field (for example `<page_ct>.<entry_uid>.<locale>.components`), and that it is rendered conditionally when the array is empty.
   2. Confirm the wrapper is visible and has height. A zero-height container gives nothing to hover.
   3. For nested blocks, put the same class and `data-cslp` on the inner block container, not only at page level.
-  4. This is specifically about a **block or multiple field with zero items**, where the SDK draws the affordance for you. A scalar field that renders nothing when empty is a different problem — see `empty-fields-are-not-clickable-on-the-canvas`.
+  4. Check every empty-block wrapper on the page, not only the one that fails: an invalid `data-cslp` on one wrapper can stop the affordance rendering on the others.
+  5. This is specifically about a **block or multiple field with zero items**, where the SDK draws the affordance for you. A scalar field that renders nothing when empty is a different problem — see `empty-fields-are-not-clickable-on-the-canvas`.
 - **verification**: Open a page whose block field is empty. The "+ Add Component" placeholder appears on hover, and adding a block inserts it into both the canvas and the form.
 
 ---
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md b/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
index 491cb18..5e640d8 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -115,8 +115,10 @@ ContentstackLivePreview.init({
 });
 ```
 
-`stackSdk` is mandatory in CSR mode. Omitting it also flips the automatic `ssr` default to `true`,
-which is a silent misconfiguration rather than an error.
+`stackSdk` is optional, but omitting it flips the automatic `ssr` default to `true`, which is a
+silent misconfiguration rather than an error. Without `stackSdk`, pass `ssr: false` explicitly and
+read `ContentstackLivePreview.hash` in your own fetch. In builder mode without `stackSdk`,
+`stackDetails.apiKey` and `stackDetails.environment` are required or `init()` throws.
 
 Refresh content through `onEntryChange`. If edits only appear after a manual reload, the callback
 was never registered, or it closed over a pathname captured at mount and is refetching the previous
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
index 07fd46c..034db21 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -10,7 +10,7 @@ Diagnose against this file. Use `frameworks.md` only for where `init()` is allow
 
 | Mode | `ssr` | How the hash travels | How updates arrive | Hard requirement |
 |---|---|---|---|---|
-| CSR + REST | `false` | postMessage; the SDK injects it into `stackSdk` | `onEntryChange` / `onLiveEdit` refetch, no reload | `stackSdk` is mandatory |
+| CSR + REST | `false` | postMessage; the SDK injects it into `stackSdk` | `onEntryChange` / `onLiveEdit` refetch, no reload | `stackSdk` for hash injection; without it, pass `ssr: false` and read `ContentstackLivePreview.hash` |
 | SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload, parent-driven; `onEntryChange` never fires on edits | a fresh Delivery SDK instance per request |
 | CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch | manual host swap plus headers |
 | SSR + GraphQL | `true` | `request.query.live_preview` | full iframe reload | manual host swap plus headers |
@@ -61,7 +61,7 @@ the hash arrives by postMessage instead and never needs the URL.
 Per [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/headless-cms/set-up-live-preview-for-static-site-generator-ssg):
 
 - Initialise Live Preview Utils with `ssr: false`
-- Pass `stackSdk`, which is mandatory in CSR mode
+- Pass `stackSdk`, so the hash is injected into the Delivery SDK (without it, `ssr` defaults to `true`, so `ssr: false` must be explicit)
 - Configure the Delivery SDK with
   `live_preview: { preview_token, enable: true, host: <region preview host> }`
 - Refresh through `onLiveEdit()`, so the browser refetches on each edit
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 11b96d3..e6f6de6 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -136,9 +136,11 @@ Confirm only the sections that apply.
 
 ### Production
 
-- Do not initialize preview on the production build (`enable: false`), or add
+- Keep preview out of the production build (`PURGE_PREVIEW_SDK=true`, or a dynamic import that
+  runs only for preview requests), or add
   `editButton: { exclude: ["outsideLivePreviewPortal"], includeByQueryParameter: false }`, or the
-  Edit button renders for visitors.
+  Edit button renders for visitors. Importing the SDK creates the button element even when
+  `init()` never runs, so `enable: false` alone is not enough.
 
 ## Reply shape
 
diff --git a/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md b/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
index 35728c5..0b7e5bb 100644
--- a/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
@@ -16,6 +16,7 @@ SKILL.md before reading anything below.
 | Preview API requests fail with `{"error_message":"Please create tracker before starting live preview session",… | [error-382-create-tracker-before-starting-live-preview-session](faq-integration.md#error-382-create-tracker-before-starting-live-preview-session) |
 | Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar | [edit-tags-not-generated-or-not-spread](faq-integration.md#edit-tags-not-generated-or-not-spread) |
 | Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited | [preview-url-does-not-resolve-to-the-app-route](faq-integration.md#preview-url-does-not-resolve-to-the-app-route) |
+| Live Preview opens the home page or the wrong page; the entry path is glued onto the last query parameter of the Base URL | [base-url-query-string-corrupts-preview-url](faq-integration.md#base-url-query-string-corrupts-preview-url) |
 | Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump break… | [sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade](faq-integration.md#sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade) |
 | The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wr… | [environment-base-url-misconfigured-or-missing-for-a-locale](faq-integration.md#environment-base-url-misconfigured-or-missing-for-a-locale) |
 | The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or t… | [edit-button-rendered-outside-a-live-preview-session](faq-integration.md#edit-button-rendered-outside-a-live-preview-session) |
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md b/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
index c629387..6d9c226 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
@@ -18,7 +18,10 @@ problem.** Say so and move to the network tab.
 Two different postMessage errors from the same library, both routine:
 
 - `NO_REQUEST_LISTENER_FOUND` ("No request listener found for event …"): one side sent a request
-  the other side has no handler for, for example a `scroll` event during load.
+  the other side has no handler for. The common one is `scroll`: the Live Preview edit button sends
+  it on click, and Visual Editor (or the Live Preview panel before the init handshake) registers no
+  `scroll` listener. It shows as an uncaught promise rejection in the site's console. It says a
+  button was clicked, nothing about whether tags resolve.
 - `No ack listener found`: an acknowledgement arrived after its sender stopped waiting, typically
   during load or teardown.
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md b/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
index b0ba0b4..ae730c7 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md
@@ -20,7 +20,7 @@ with Contentstack Support.
 | Symptom | What it actually is |
 |---|---|
 | A previously working `localhost` preview stops working, console shows a local network access error | Chrome's Local Network Access policy now blocks the app origin from framing localhost. Only the user can grant the permission, in the browser. |
-| Preview pane blank, and the site sits behind platform password protection or third-party SSO | Those screens set `X-Frame-Options: DENY` on themselves. Contentstack cannot inject headers into a browser-originated iframe request. Workarounds, cheapest first: enable **Open in New Tab**, which renders the site outside the iframe so frame headers stop applying; otherwise disable protection on the preview deployment, put a bypass token in the Base URL (scoped to the preview deployment and rotated, since every stack user can read it), or front it with a server-side proxy that strips the header. |
+| Preview pane blank, and the site sits behind platform password protection or third-party SSO | Those screens set `X-Frame-Options: DENY` on themselves. Contentstack cannot inject headers into a browser-originated iframe request. Workarounds, cheapest first: enable **Open in New Tab**, which renders the site outside the iframe so frame headers stop applying; otherwise disable protection on the preview deployment, or front it with a server-side proxy that strips the header. A bypass token in the Base URL does not work: see `base-url-query-string-corrupts-preview-url` in faq-integration.md. |
 | Ad slots, consent widgets, or other host-dependent third-party scripts misbehave in the pane | Those scripts key off the top-level origin, which is the Contentstack app inside an iframe. Expected, not a preview defect. |
 
 ## How to hand it over
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
index 36bde9a..db45d81 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
@@ -43,7 +43,7 @@ setup, use `setup-docs.md` instead.
 - **fix**:
   1. Remove `X-Frame-Options` for the preview host and use CSP instead, allowing the Contentstack app origin for the stack's region: `Content-Security-Policy: frame-ancestors 'self' https://app.contentstack.com;` (for example `https://eu-app.contentstack.com` in EU). `https://*.contentstack.com` is the broader fallback. `X-Frame-Options` has no allowlist syntax; a bare `SAMEORIGIN` always wins.
   2. Apply the header on every route, not just the site root. A route that redirects to a different hostname than the configured Base URL will also fail.
-  3. If the deployment sits behind platform password protection, note that no header or query parameter can be injected into a browser-originated iframe request from Contentstack. Options: disable protection on the preview deployment, use a bypass token embedded in the Base URL (every stack user can read the Base URL, so scope the token to the preview deployment and rotate it), put a server-side proxy in front that injects the header, or use Live Preview → Open in New Tab (a plan-gated feature that renders outside the iframe).
+  3. If the deployment sits behind platform password protection, note that no header or query parameter can be injected into a browser-originated iframe request from Contentstack. Options: disable protection on the preview deployment, put a server-side proxy in front that injects the header, or use Live Preview → Open in New Tab (a plan-gated feature that renders outside the iframe). Do not put a bypass token in the Base URL: Live Preview appends the entry path into the last query value, so the token and the path both break. See `base-url-query-string-corrupts-preview-url`.
   4. Third-party SSO screens that themselves set `X-Frame-Options: DENY` cannot render in the iframe at all. Use Open in New Tab, which renders the preview outside the iframe so those screens can load.
   5. On the Live Preview Onboarding Check this shows as **Live Preview SDK Not Initialized**, not "Could Not Connect to Website". The reachability gate is a `no-cors` request, which succeeds on any HTTP response, so frame headers and auth screens pass it.
 - **verification**: `curl -I https://<preview-host>/<some-deep-route>` and confirm no `X-Frame-Options` and a `frame-ancestors` value that includes the Contentstack app origin. Reload Live Preview; the pane should render.
@@ -101,6 +101,19 @@ setup, use `setup-docs.md` instead.
 
 ---
 
+### base-url-query-string-corrupts-preview-url
+- **bucket**: integration
+- **symptom**: Live Preview opens the home page or the wrong page instead of the entry. The URL in the pane has the entry path glued onto the end of the last query parameter, for example `https://site.example/?token=abc/my-page` (or `abc%2Fmy-page` under SSR), instead of on the path. Most often seen when the Base URL carries a hosting-platform protection-bypass token. Visual Editor opens the same page correctly.
+- **frameworks**: framework-agnostic (stack configuration)
+- **rendering_modes**: any
+- **root_cause**: Live Preview builds the preview URL by joining the environment Base URL and the entry's `url` as strings, then parsing the result. A Base URL that ends in a query string therefore receives the path inside the last query value: the token is corrupted and the path stays `/`. Visual Editor parses the Base URL first and keeps its query string, which is why the two products disagree on the same entry.
+- **fix**:
+  1. Remove the query string from the Base URL. Keep one only when it ends in a parameter the app deliberately reads the path from (`?path=`).
+  2. For a protected deployment, do not use a bypass token in the Base URL. Remove protection on the preview deployment, front it with a proxy that adds the credential, or restrict an unprotected preview deployment another way (for example by IP).
+- **verification**: Open an entry in Live Preview. The pane URL carries the entry path on the path, not inside a query value, and the right page renders.
+
+---
+
 ### sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade
 - **bucket**: integration
 - **symptom**: Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump breaks a previously working integration: `setConfigFromParams` is no longer callable, `ReferenceError: window is not defined` in server code, the Edit button suddenly renders in production, or `Live_Preview_SDK: To use edit tags, you must provide the stack API key`.
@@ -138,12 +151,12 @@ setup, use `setup-docs.md` instead.
 - **symptom**: The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or the `#cslp-tooltip` button element is injected into `document.body` on production even when not visible (usually caught in an accessibility audit). Sometimes intermittent, correlating with client-side route changes rather than fresh page loads.
 - **frameworks**: Next.js (App Router especially), React
 - **rendering_modes**: CSR, SSR
-- **root_cause**: With `editButton.enable: true` and no `exclude`, the SDK renders the button on any page where it is initialized, inside the iframe or not. It never checks the `live_preview` hash or any session signal. `inIframe()` only matters when `exclude` is set, and a `?cslp-buttons=` query parameter overrides `exclude` unless `includeByQueryParameter: false`. Teams that gate `init()` on a server-read hash also get bitten by App Router soft navigation, which does not re-run that server-side gate while the SDK's button instance persists across route changes.
+- **root_cause**: With `editButton.enable: true` and no `exclude` (the defaults), the SDK renders the button on any page that loads it, inside the iframe or not. It creates `#cslp-tooltip` when the module is **imported**, before `init()` runs, so a production build that imports the SDK and never calls `init()` still has the element; config passed to `init()` is applied only afterwards. It never checks the `live_preview` hash or any session signal. `inIframe()` only matters when `exclude` is set, and a `?cslp-buttons=` query parameter overrides `exclude` unless `includeByQueryParameter: false`. Teams that gate `init()` on a server-read hash also get bitten by App Router soft navigation, which does not re-run that server-side gate while the SDK's button instance persists across route changes.
 - **fix**:
   1. Add `editButton: { enable: true, exclude: ['outsideLivePreviewPortal'], includeByQueryParameter: false }`. Outside the iframe the button no longer renders, a query parameter cannot bring it back, and Live Preview inside the pane keeps working.
-  2. If Live Preview is not used on production at all, do not initialize it there: `enable: false` (with the default `cleanCslpOnProduction: true`, which then strips `data-cslp`), or the `PURGE_PREVIEW_SDK=true` build flag, which no-ops the SDK entirely.
+  2. If Live Preview is not used on production at all, keep the SDK out of the production bundle: build with `PURGE_PREVIEW_SDK=true` (or `REACT_APP_PURGE_PREVIEW_SDK=true`), which swaps in a no-op SDK and skips the import-time button, or load the SDK with a dynamic import that runs only for preview requests. The flag works only if the bundler exposes `process.env` to browser code. Skipping `init()` or passing `enable: false` is not enough on its own, because the element is created at import.
   3. Do not rely on a server-side hash check alone in an App Router app; soft navigation will not re-evaluate it.
-- **verification**: Load the production URL in a normal tab with DevTools open. `document.getElementById('cslp-tooltip')` should be absent, and no `data-cslp` attributes should be present if the SDK runs with `enable: false`.
+- **verification**: Load the production URL in a normal tab with DevTools open. `document.getElementById('cslp-tooltip')` returns `null`, and no `data-cslp` attributes are present if the SDK runs with `enable: false`.
 
 ---
 
@@ -370,7 +383,7 @@ setup, use `setup-docs.md` instead.
 - **root_cause**: Two halves of the same mistake. A prerendered page cannot read query parameters at request time, so the `live_preview` hash can never reach a build-time data fetch — static output is published-only content by definition. And in SSR mode the SDK reloads the page after every edit, which on a static site just re-serves the same prerendered HTML. SSG is supported, but only in CSR mode.
 - **fix**:
   1. Initialize with `ssr: false`. Edits then fire an `onEntryChange` callback instead of a page reload.
-  2. Pass `stackSdk` in the init config. It is mandatory in CSR mode, and it is also what the SDK uses to default `ssr`, so omitting it silently selects SSR behaviour.
+  2. Pass `stackSdk` in the init config so the SDK can inject the hash into the Delivery SDK. It is optional, but it is also what the SDK uses to default `ssr`: without it, and without an explicit `ssr: false`, the SDK silently selects SSR behaviour.
   3. Implement `onEntryChange`: subscribe on the client, refetch the entry, update the UI. No rebuild is needed.
   4. Remove any `Stack.livePreviewQuery()` call from middleware. It is SSR-only and must not run on a static route.
   5. If the site mixes static and server-rendered routes, make the mode conditional per route rather than per app.
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
index 083688a..21acb23 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -9,7 +9,7 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 
 ### cslp-not-rebased-to-referenced-entry
 - **bucket**: visual-editor
-- **symptom**: Edit tags on fields that come from a **referenced** entry do nothing when clicked. Tags on the page's own fields work. Console may show `{code: 'NO_REQUEST_LISTENER_FOUND', message: 'contentstack-adv-post-message: No request listener found for event "scroll"'}`, but that message is routine and appears on healthy setups too — treat it as incidental, not as the identifying evidence. Diagnose from the tags themselves.
+- **symptom**: Edit tags on fields that come from a **referenced** entry do nothing when clicked. Tags on the page's own fields work. Console may show `{code: 'NO_REQUEST_LISTENER_FOUND', message: 'contentstack-adv-post-message: No request listener found for event "scroll"'}`, but that message only says the Live Preview edit button was clicked where the parent has no `scroll` listener, and it appears on healthy setups too — treat it as incidental, not as the identifying evidence. Diagnose from the tags themselves.
 - **frameworks**: React, Next.js, framework-agnostic
 - **rendering_modes**: CSR, SSR
 - **root_cause**: `addEditableTags()` rebases a tag onto the referenced entry only when the resolved reference object carries both `uid` and `_content_type_uid`. Without them the tag stays anchored to the parent entry (`product.<parent_entry_uid>.<locale>.<reference_field>.<index>.<field>`), so there is no entry to navigate to. Common causes: references fetched separately and merged by hand (which drops those keys), or any GraphQL response, where those keys sit under `system` instead of at the top level. Hardcoding `data-cslp` by hand is a related failure — the referenced entry's uid and content type uid are not the ones being edited.
@@ -59,12 +59,13 @@ If nothing on the canvas is editable at all, start with `edit-tags-not-generated
 - **symptom**: A page or component with an empty modular-block / multiple field shows no "+ Add Component" affordance, so authors have to go to the form panel to add the first block.
 - **frameworks**: React, Next.js
 - **rendering_modes**: CSR, SSR
-- **root_cause**: The empty-block placeholder only renders when the wrapper carries **both** the `VB_EmptyBlockParentClass` class (exported by the SDK; its literal value is `visual-builder__empty-block-parent`) and a `data-cslp` pointing at the block field itself. Miss either and there is nothing for the canvas to attach the affordance to.
+- **root_cause**: The empty-block placeholder only renders when the wrapper carries **both** the `VB_EmptyBlockParentClass` class (exported by the SDK; its literal value is `visual-builder__empty-block-parent`) and a `data-cslp` pointing at the block field itself. Miss either and there is nothing for the canvas to attach the affordance to. Three more conditions: it renders only inside Visual Editor, not in Live Preview; Visual Editor must return a field schema for that content type and field path, so a `data-cslp` with a wrong path renders nothing; and it is drawn when the DOM changes after the editor handshake. The button label is "Add <field display name>", not a fixed string.
 - **fix**:
   1. Confirm the wrapper renders both the class and a `data-cslp` pointing at the block field (for example `<page_ct>.<entry_uid>.<locale>.components`), and that it is rendered conditionally when the array is empty.
   2. Confirm the wrapper is visible and has height. A zero-height container gives nothing to hover.
   3. For nested blocks, put the same class and `data-cslp` on the inner block container, not only at page level.
-  4. This is specifically about a **block or multiple field with zero items**, where the SDK draws the affordance for you. A scalar field that renders nothing when empty is a different problem — see `empty-fields-are-not-clickable-on-the-canvas`.
+  4. Check every empty-block wrapper on the page, not only the one that fails: an invalid `data-cslp` on one wrapper can stop the affordance rendering on the others.
+  5. This is specifically about a **block or multiple field with zero items**, where the SDK draws the affordance for you. A scalar field that renders nothing when empty is a different problem — see `empty-fields-are-not-clickable-on-the-canvas`.
 - **verification**: Open a page whose block field is empty. The "+ Add Component" placeholder appears on hover, and adding a block inserts it into both the canvas and the form.
 
 ---
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md b/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
index 491cb18..5e640d8 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -115,8 +115,10 @@ ContentstackLivePreview.init({
 });
 ```
 
-`stackSdk` is mandatory in CSR mode. Omitting it also flips the automatic `ssr` default to `true`,
-which is a silent misconfiguration rather than an error.
+`stackSdk` is optional, but omitting it flips the automatic `ssr` default to `true`, which is a
+silent misconfiguration rather than an error. Without `stackSdk`, pass `ssr: false` explicitly and
+read `ContentstackLivePreview.hash` in your own fetch. In builder mode without `stackSdk`,
+`stackDetails.apiKey` and `stackDetails.environment` are required or `init()` throws.
 
 Refresh content through `onEntryChange`. If edits only appear after a manual reload, the callback
 was never registered, or it closed over a pathname captured at mount and is refetching the previous
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
index 07fd46c..034db21 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -10,7 +10,7 @@ Diagnose against this file. Use `frameworks.md` only for where `init()` is allow
 
 | Mode | `ssr` | How the hash travels | How updates arrive | Hard requirement |
 |---|---|---|---|---|
-| CSR + REST | `false` | postMessage; the SDK injects it into `stackSdk` | `onEntryChange` / `onLiveEdit` refetch, no reload | `stackSdk` is mandatory |
+| CSR + REST | `false` | postMessage; the SDK injects it into `stackSdk` | `onEntryChange` / `onLiveEdit` refetch, no reload | `stackSdk` for hash injection; without it, pass `ssr: false` and read `ContentstackLivePreview.hash` |
 | SSR + REST | `true` | `live_preview` query parameter on the request | full iframe reload, parent-driven; `onEntryChange` never fires on edits | a fresh Delivery SDK instance per request |
 | CSR + GraphQL | `false` | `ContentstackLivePreview.hash` | callback refetch | manual host swap plus headers |
 | SSR + GraphQL | `true` | `request.query.live_preview` | full iframe reload | manual host swap plus headers |
@@ -61,7 +61,7 @@ the hash arrives by postMessage instead and never needs the URL.
 Per [Set Up Live Preview for Static-Site Generator (SSG)](https://www.contentstack.com/docs/headless-cms/set-up-live-preview-for-static-site-generator-ssg):
 
 - Initialise Live Preview Utils with `ssr: false`
-- Pass `stackSdk`, which is mandatory in CSR mode
+- Pass `stackSdk`, so the hash is injected into the Delivery SDK (without it, `ssr` defaults to `true`, so `ssr: false` must be explicit)
 - Configure the Delivery SDK with
   `live_preview: { preview_token, enable: true, host: <region preview host> }`
 - Refresh through `onLiveEdit()`, so the browser refetches on each edit
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
index 11b96d3..e6f6de6 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -136,9 +136,11 @@ Confirm only the sections that apply.
 
 ### Production
 
-- Do not initialize preview on the production build (`enable: false`), or add
+- Keep preview out of the production build (`PURGE_PREVIEW_SDK=true`, or a dynamic import that
+  runs only for preview requests), or add
   `editButton: { exclude: ["outsideLivePreviewPortal"], includeByQueryParameter: false }`, or the
-  Edit button renders for visitors.
+  Edit button renders for visitors. Importing the SDK creates the button element even when
+  `init()` never runs, so `enable: false` alone is not enough.
 
 ## Reply shape
 
diff --git a/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md b/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
index 35728c5..0b7e5bb 100644
--- a/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
@@ -16,6 +16,7 @@ SKILL.md before reading anything below.
 | Preview API requests fail with `{"error_message":"Please create tracker before starting live preview session",… | [error-382-create-tracker-before-starting-live-preview-session](faq-integration.md#error-382-create-tracker-before-starting-live-preview-session) |
 | Nothing on the page is inline-editable: no hover highlight, no edit button, no field toolbar | [edit-tags-not-generated-or-not-spread](faq-integration.md#edit-tags-not-generated-or-not-spread) |
 | Live Preview opens the site's home page or a "Page Not Found" instead of the entry being edited | [preview-url-does-not-resolve-to-the-app-route](faq-integration.md#preview-url-does-not-resolve-to-the-app-route) |
+| Live Preview opens the home page or the wrong page; the entry path is glued onto the last query parameter of the Base URL | [base-url-query-string-corrupts-preview-url](faq-integration.md#base-url-query-string-corrupts-preview-url) |
 | Visual Editor features silently do nothing on an otherwise working Live Preview setup; or a version bump break… | [sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade](faq-integration.md#sdk-version-below-visual-editor-minimum-or-breaking-major-upgrade) |
 | The Live Preview environment selector is greyed out or shows "No environments available"; preview loads the wr… | [environment-base-url-misconfigured-or-missing-for-a-locale](faq-integration.md#environment-base-url-misconfigured-or-missing-for-a-locale) |
 | The Live Preview "Edit" pencil button appears on the normal production or UAT site for ordinary visitors, or t… | [edit-button-rendered-outside-a-live-preview-session](faq-integration.md#edit-button-rendered-outside-a-live-preview-session) |