diff --git a/README.md b/README.md
index a6cbbbd..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-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 | 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 e86f870..2b1141b 100644
--- a/codex/AGENTS.md
+++ b/codex/AGENTS.md
@@ -7,9 +7,9 @@ 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 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..b5cf392
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -0,0 +1,283 @@
+# cms-live-preview-visual-editor-support-assistant
+
+
+# Live Preview and Visual Editor Support Assistant
+
+## Description
+
+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 Visual Experience question: how a feature works or behaves, what a setting or check
+means, setting up an integration, or an integration that misbehaves.
+
+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.** 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 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
+
+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 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 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
+
+- 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
+- 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
+
+Report this back ticked. An unticked step is a visible gap.
+
+- [ ] 1. Identify the product.
+- [ ] 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 and verify, or hand to Contentstack Support.
+
+## Instructions
+
+### Step 1. Which product?
+
+Ask explicitly. Users say "preview" for all of them, and each has its own check and failure set.
+
+| 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 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.
+
+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.**
+
+Live Preview shows one card:
+
+| Card | Localises to |
+|---|---|
+| 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 |
+
+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 decide the branch:
+
+- **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. Detect framework, mode and fetch layer
+
+Read the code instead of asking. State what you found and ask only for confirmation.
+
+| Check | Where | Why |
+|---|---|---|
+| 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 (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 what is still open
+
+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.
+
+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 | 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
+
+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 evidence is still missing, ask for the one artifact that separates the remaining candidates and
+say what each answer would mean.
+
+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 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+ for Visual Editor (legacy `contentstack` JavaScript SDK
+v3.20.3+); Live Preview Utils v4.4.4+ for `setPageContext()`.
+
+Without repository access, run the same steps against described code and screenshots. Do not claim
+to have inspected code.
+
+## Security
+
+### Defaults
+
+- 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.
+- 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 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
new file mode 100644
index 0000000..6d9c226
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
@@ -0,0 +1,49 @@
+# 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` and `No ack listener found`
+
+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. 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.
+
+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.
+
+### 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..ae730c7
--- /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, 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
+
+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. "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" |
+
+**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/edit-tags.md b/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
new file mode 100644
index 0000000..2a5d030
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
@@ -0,0 +1,134 @@
+# 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 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`. 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.
+
+## 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.
+
+## Variants
+
+Highlight Variant and audience mode key on v2 tags:
+`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
+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
+```
+
+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
+  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/faq-integration.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
new file mode 100644
index 0000000..db45d81
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
@@ -0,0 +1,391 @@
+# Integration FAQ
+
+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 SKILL.md. For first-time
+setup, use `setup-docs.md` instead.
+
+### app-fetches-from-delivery-cdn-instead-of-preview-service
+- **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
+- **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**: 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, 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, 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.
+
+---
+
+### error-382-create-tracker-before-starting-live-preview-session
+- **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.
+- **frameworks**: Next.js, React, framework-agnostic REST/GraphQL clients
+- **rendering_modes**: CSR, SSR
+- **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 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 site's content requests go to the preview host and return 200, and the 382 error is gone.
+
+---
+
+### edit-tags-not-generated-or-not-spread
+- **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 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. 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.
+
+---
+
+### preview-url-does-not-resolve-to-the-app-route
+- **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/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.
+- **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.
+
+---
+
+### 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`.
+- **frameworks**: Next.js, React, Gatsby, Angular
+- **rendering_modes**: any
+- **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+** 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.
+- **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**: 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
+- **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**: 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` 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, 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')` returns `null`, and no `data-cslp` attributes are present if the SDK runs with `enable: false`.
+
+---
+
+### cors-blocked-on-preview-api-requests
+- **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. 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.
+
+---
+
+### ssr-stack-instance-shared-or-duplicated
+- **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
+- **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 })`.
+  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**: 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
+- **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
+     "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**: 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
+- **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; 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**: 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
+- **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**: 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
+- **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. 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**: 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**: 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>' } })`.
+  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**: 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 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
+     ContentstackLivePreview.init({
+       mode: "builder",
+       editInVisualBuilderButton: { enable: false },
+     });
+     ```
+  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**: 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 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.
+  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 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.
+
+---
+
+### visual-experience-navigation-missing-for-the-stack
+- **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
+- **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**: 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
+- **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**: 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.
+- **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**: 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
+- **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**: 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
+- **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 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.
+  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-preview-runtime.md b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
new file mode 100644
index 0000000..c80ccb7
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -0,0 +1,146 @@
+# Preview runtime FAQ
+
+Content correctness once the integration is confirmed wired up: staleness, lost preview context,
+caching, locale, variants and roles. Timeline is in `faq-timeline.md`.
+
+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.
+
+### 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-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. 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.
+- **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 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.
+- **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**: 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 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.
+
+---
+
+### 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.
+
+---
+
+### 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+, 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.
+
+---
+
+### 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-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.
+
+---
+
+### 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. 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
new file mode 100644
index 0000000..7299acc
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
@@ -0,0 +1,38 @@
+# 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 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
+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 `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. 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.
+
+---
+
+### 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-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.
+  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..21acb23
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -0,0 +1,115 @@
+# 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-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 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.
+- **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, 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.
+
+---
+
+### 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. 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. 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.
+
+---
+
+### 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, 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. 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.
+
+---
+
+### 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.
+- **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. 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.
+
+---
+
+### 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..5e640d8
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -0,0 +1,195 @@
+# 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 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. The options differ by mode.
+
+CSR (content fetched in the browser):
+
+```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;
+}
+```
+
+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
+  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. 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.
+
+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.
+
+## 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 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
+route.
+
+## Nuxt
+
+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.
+
+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. A client-rendered Angular app follows the CSR
+contract: `ssr: false`, `stackSdk` passed, `onEntryChange` for refresh.
+
+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 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).
+
+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 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/onboarding-check.md b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
new file mode 100644
index 0000000..75dfeb6
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -0,0 +1,131 @@
+# The Onboarding Check
+
+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.
+
+**Ask for a screenshot before anything else.** The first failing item localises the problem to one
+gate and proves every earlier gate passed.
+
+## The chain property
+
+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 "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.
+
+## Live Preview
+
+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** | 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. |
+
+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
+
+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:
+
+| # | Overlay item | Passes when |
+|---|---|---|
+| 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 |
+
+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
+
+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: `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 |
+
+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.
+
+"Configure" opens the stack's Live Preview settings page. The footer links to the Set Up Timeline
+documentation.
+
+## Minimum SDK versions differ
+
+| Product | The check fails below |
+|---|---|
+| Live Preview | 1.4.0 |
+| Timeline | major version 2 |
+| Visual Editor | major version 3 |
+
+So an SDK can pass Live Preview's check and fail Visual Editor's.
+
+## What the checks do not cover
+
+"Setup Complete" with a broken experience is a real and informative combination. None of the three
+checks looks at:
+
+- **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 check does not appear
+
+Absence is not a pass. Rule out:
+
+- **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.**
+
+The stack settings disagree on what an unset value means:
+
+| Product | Setting | Unset resolves to |
+|---|---|---|
+| Live Preview | `live_preview.lp-onboarding-setup-visible` | hidden |
+| 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 |
+
+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.
+
+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 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/rendering-modes.md b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
new file mode 100644
index 0000000..034db21
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -0,0 +1,131 @@
+# 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` 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 |
+| SSG | `false` | postMessage | runs in CSR mode at runtime | `stackSdk`, and `init()` must be browser-only |
+
+## `onEntryChange` does not fire on edits under `ssr: true`
+
+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.
+
+- 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 `ssr` explicitly, in one place.
+
+## 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/headless-cms/set-up-live-preview-for-static-site-generator-ssg):
+
+- Initialise Live Preview Utils with `ssr: false`
+- 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
+
+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 running with `ssr: true`, which
+reloads into the same prerendered HTML on every edit.
+
+### 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
+
+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
new file mode 100644
index 0000000..e6f6de6
--- /dev/null
+++ b/codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -0,0 +1,172 @@
+# New integrations
+
+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 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.
+
+## Steps
+
+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.
+
+## Documentation pages
+
+### 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/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` |
+
+Where `init()` goes in each framework: [frameworks.md](frameworks.md).
+
+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
+
+- [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
+
+- [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
+
+- 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.
+
+### Visual Editor (on top of Live Preview)
+
+- `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.
+
+### Timeline (on top of Live Preview)
+
+- Forward `preview_timestamp` next to the hash on every request, and keep both on the URL across
+  client-side navigation.
+
+### Production
+
+- 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. Importing the SDK creates the button element even when
+  `init()` never runs, so `enable: false` alone is not enough.
+
+## Reply shape
+
+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).
+
+## Verify
+
+- **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.** 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/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..0b7e5bb
--- /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.
+
+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.
+
+## 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-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) |
+| 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) |
+| `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
+
+| 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) |
+| 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) |
+| 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
+
+| 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..4439a4f 100644
--- a/cursor/rules/00-router.mdc
+++ b/cursor/rules/00-router.mdc
@@ -12,9 +12,9 @@ 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 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..f773280
--- /dev/null
+++ b/cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
@@ -0,0 +1,286 @@
+---
+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
+---
+
+
+# Live Preview and Visual Editor Support Assistant
+
+## Description
+
+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 Visual Experience question: how a feature works or behaves, what a setting or check
+means, setting up an integration, or an integration that misbehaves.
+
+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.** 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 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
+
+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 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 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
+
+- 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
+- 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
+
+Report this back ticked. An unticked step is a visible gap.
+
+- [ ] 1. Identify the product.
+- [ ] 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 and verify, or hand to Contentstack Support.
+
+## Instructions
+
+### Step 1. Which product?
+
+Ask explicitly. Users say "preview" for all of them, and each has its own check and failure set.
+
+| 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 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.
+
+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.**
+
+Live Preview shows one card:
+
+| Card | Localises to |
+|---|---|
+| 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 |
+
+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 decide the branch:
+
+- **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. Detect framework, mode and fetch layer
+
+Read the code instead of asking. State what you found and ask only for confirmation.
+
+| Check | Where | Why |
+|---|---|---|
+| 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 (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 what is still open
+
+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.
+
+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 | 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
+
+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 evidence is still missing, ask for the one artifact that separates the remaining candidates and
+say what each answer would mean.
+
+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 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+ for Visual Editor (legacy `contentstack` JavaScript SDK
+v3.20.3+); Live Preview Utils v4.4.4+ for `setPageContext()`.
+
+Without repository access, run the same steps against described code and screenshots. Do not claim
+to have inspected code.
+
+## Security
+
+### Defaults
+
+- 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.
+- 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 or environment configuration automatically.
+Propose the change, state the blast radius, and require confirmation.
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/CLAUDE.md b/skills/CLAUDE.md
index e86f870..2b1141b 100644
--- a/skills/CLAUDE.md
+++ b/skills/CLAUDE.md
@@ -7,9 +7,9 @@ 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 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..660517d
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
@@ -0,0 +1,286 @@
+---
+name: cms-live-preview-visual-editor-support-assistant
+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
+---
+
+# Live Preview and Visual Editor Support Assistant
+
+## Description
+
+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 Visual Experience question: how a feature works or behaves, what a setting or check
+means, setting up an integration, or an integration that misbehaves.
+
+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.** 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 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
+
+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 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 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
+
+- 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
+- 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
+
+Report this back ticked. An unticked step is a visible gap.
+
+- [ ] 1. Identify the product.
+- [ ] 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 and verify, or hand to Contentstack Support.
+
+## Instructions
+
+### Step 1. Which product?
+
+Ask explicitly. Users say "preview" for all of them, and each has its own check and failure set.
+
+| 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 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.
+
+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.**
+
+Live Preview shows one card:
+
+| Card | Localises to |
+|---|---|
+| 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 |
+
+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 decide the branch:
+
+- **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. Detect framework, mode and fetch layer
+
+Read the code instead of asking. State what you found and ask only for confirmation.
+
+| Check | Where | Why |
+|---|---|---|
+| 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 (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 what is still open
+
+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.
+
+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 | 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
+
+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 evidence is still missing, ask for the one artifact that separates the remaining candidates and
+say what each answer would mean.
+
+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 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+ for Visual Editor (legacy `contentstack` JavaScript SDK
+v3.20.3+); Live Preview Utils v4.4.4+ for `setPageContext()`.
+
+Without repository access, run the same steps against described code and screenshots. Do not claim
+to have inspected code.
+
+## Security
+
+### Defaults
+
+- 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.
+- 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 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
new file mode 100644
index 0000000..6d9c226
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md
@@ -0,0 +1,49 @@
+# 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` and `No ack listener found`
+
+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. 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.
+
+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.
+
+### 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..ae730c7
--- /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, 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
+
+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. "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" |
+
+**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/edit-tags.md b/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
new file mode 100644
index 0000000..2a5d030
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md
@@ -0,0 +1,134 @@
+# 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 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`. 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.
+
+## 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.
+
+## Variants
+
+Highlight Variant and audience mode key on v2 tags:
+`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
+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
+```
+
+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
+  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/faq-integration.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
new file mode 100644
index 0000000..db45d81
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
@@ -0,0 +1,391 @@
+# Integration FAQ
+
+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 SKILL.md. For first-time
+setup, use `setup-docs.md` instead.
+
+### app-fetches-from-delivery-cdn-instead-of-preview-service
+- **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
+- **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**: 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, 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, 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.
+
+---
+
+### error-382-create-tracker-before-starting-live-preview-session
+- **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.
+- **frameworks**: Next.js, React, framework-agnostic REST/GraphQL clients
+- **rendering_modes**: CSR, SSR
+- **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 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 site's content requests go to the preview host and return 200, and the 382 error is gone.
+
+---
+
+### edit-tags-not-generated-or-not-spread
+- **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 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. 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.
+
+---
+
+### preview-url-does-not-resolve-to-the-app-route
+- **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/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.
+- **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.
+
+---
+
+### 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`.
+- **frameworks**: Next.js, React, Gatsby, Angular
+- **rendering_modes**: any
+- **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+** 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.
+- **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**: 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
+- **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**: 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` 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, 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')` returns `null`, and no `data-cslp` attributes are present if the SDK runs with `enable: false`.
+
+---
+
+### cors-blocked-on-preview-api-requests
+- **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. 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.
+
+---
+
+### ssr-stack-instance-shared-or-duplicated
+- **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
+- **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 })`.
+  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**: 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
+- **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
+     "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**: 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
+- **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; 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**: 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
+- **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**: 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
+- **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. 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**: 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**: 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>' } })`.
+  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**: 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 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
+     ContentstackLivePreview.init({
+       mode: "builder",
+       editInVisualBuilderButton: { enable: false },
+     });
+     ```
+  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**: 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 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.
+  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 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.
+
+---
+
+### visual-experience-navigation-missing-for-the-stack
+- **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
+- **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**: 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
+- **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**: 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.
+- **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**: 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
+- **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**: 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
+- **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 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.
+  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-preview-runtime.md b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
new file mode 100644
index 0000000..c80ccb7
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
@@ -0,0 +1,146 @@
+# Preview runtime FAQ
+
+Content correctness once the integration is confirmed wired up: staleness, lost preview context,
+caching, locale, variants and roles. Timeline is in `faq-timeline.md`.
+
+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.
+
+### 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-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. 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.
+- **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 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.
+- **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**: 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 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.
+
+---
+
+### 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.
+
+---
+
+### 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+, 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.
+
+---
+
+### 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-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.
+
+---
+
+### 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. 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
new file mode 100644
index 0000000..7299acc
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md
@@ -0,0 +1,38 @@
+# 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 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
+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 `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. 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.
+
+---
+
+### 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-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.
+  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..21acb23
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@@ -0,0 +1,115 @@
+# 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-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 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.
+- **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, 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.
+
+---
+
+### 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. 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. 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.
+
+---
+
+### 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, 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. 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.
+
+---
+
+### 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.
+- **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. 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.
+
+---
+
+### 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..5e640d8
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md
@@ -0,0 +1,195 @@
+# 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 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. The options differ by mode.
+
+CSR (content fetched in the browser):
+
+```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;
+}
+```
+
+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
+  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. 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.
+
+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.
+
+## 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 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
+route.
+
+## Nuxt
+
+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.
+
+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. A client-rendered Angular app follows the CSR
+contract: `ssr: false`, `stackSdk` passed, `onEntryChange` for refresh.
+
+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 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).
+
+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 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/onboarding-check.md b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
new file mode 100644
index 0000000..75dfeb6
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md
@@ -0,0 +1,131 @@
+# The Onboarding Check
+
+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.
+
+**Ask for a screenshot before anything else.** The first failing item localises the problem to one
+gate and proves every earlier gate passed.
+
+## The chain property
+
+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 "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.
+
+## Live Preview
+
+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** | 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. |
+
+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
+
+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:
+
+| # | Overlay item | Passes when |
+|---|---|---|
+| 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 |
+
+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
+
+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: `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 |
+
+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.
+
+"Configure" opens the stack's Live Preview settings page. The footer links to the Set Up Timeline
+documentation.
+
+## Minimum SDK versions differ
+
+| Product | The check fails below |
+|---|---|
+| Live Preview | 1.4.0 |
+| Timeline | major version 2 |
+| Visual Editor | major version 3 |
+
+So an SDK can pass Live Preview's check and fail Visual Editor's.
+
+## What the checks do not cover
+
+"Setup Complete" with a broken experience is a real and informative combination. None of the three
+checks looks at:
+
+- **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 check does not appear
+
+Absence is not a pass. Rule out:
+
+- **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.**
+
+The stack settings disagree on what an unset value means:
+
+| Product | Setting | Unset resolves to |
+|---|---|---|
+| Live Preview | `live_preview.lp-onboarding-setup-visible` | hidden |
+| 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 |
+
+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.
+
+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 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/rendering-modes.md b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
new file mode 100644
index 0000000..034db21
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md
@@ -0,0 +1,131 @@
+# 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` 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 |
+| SSG | `false` | postMessage | runs in CSR mode at runtime | `stackSdk`, and `init()` must be browser-only |
+
+## `onEntryChange` does not fire on edits under `ssr: true`
+
+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.
+
+- 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 `ssr` explicitly, in one place.
+
+## 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/headless-cms/set-up-live-preview-for-static-site-generator-ssg):
+
+- Initialise Live Preview Utils with `ssr: false`
+- 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
+
+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 running with `ssr: true`, which
+reloads into the same prerendered HTML on every edit.
+
+### 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
+
+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
new file mode 100644
index 0000000..e6f6de6
--- /dev/null
+++ b/skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md
@@ -0,0 +1,172 @@
+# New integrations
+
+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 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.
+
+## Steps
+
+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.
+
+## Documentation pages
+
+### 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/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` |
+
+Where `init()` goes in each framework: [frameworks.md](frameworks.md).
+
+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
+
+- [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
+
+- [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
+
+- 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.
+
+### Visual Editor (on top of Live Preview)
+
+- `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.
+
+### Timeline (on top of Live Preview)
+
+- Forward `preview_timestamp` next to the hash on every request, and keep both on the URL across
+  client-side navigation.
+
+### Production
+
+- 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. Importing the SDK creates the button element even when
+  `init()` never runs, so `enable: false` alone is not enough.
+
+## Reply shape
+
+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).
+
+## Verify
+
+- **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.** 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/symptom-index.md b/skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md
new file mode 100644
index 0000000..0b7e5bb
--- /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.
+
+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.
+
+## 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-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) |
+| 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) |
+| `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
+
+| 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) |
+| 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) |
+| 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
+
+| 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) |