Skip to content

feat(skills): rebuild live-preview support skill as a diagnostic protocol - #18

Closed
hitesh-shetty-cstk wants to merge 23 commits into
contentstack:mainfrom
hitesh-shetty-cstk:feat/visual-editor-support-assistant
Closed

feat(skills): rebuild live-preview support skill as a diagnostic protocol#18
hitesh-shetty-cstk wants to merge 23 commits into
contentstack:mainfrom
hitesh-shetty-cstk:feat/visual-editor-support-assistant

Conversation

@hitesh-shetty-cstk

@hitesh-shetty-cstk hitesh-shetty-cstk commented Sep 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

Restructures cms-live-preview-visual-builder-support-assistant into cms-live-preview-visual-editor-support-assistant: a fixed debugging protocol backed by reference files, in place of one prose file.

Visual Builder and Visual Editor are the same product. The public docs say Visual Builder; the app UI and stack settings say Visual Editor. The skill uses Visual Editor and states the equivalence in a Terminology section, so a user can say either and the router matches both.

What changed

SKILL.md is now a 7-step intake protocol: identify the product, setup or regression, read the Onboarding Check, detect framework and rendering mode from the code, collect only the evidence detection cannot supply, localise to one of four setup contracts, then fix, verify, or hand to Support. A stop rule ends evidence collection once a contract is localised.

Twelve reference files carry the detail, so SKILL.md stays small and depth loads only when a step needs it.

onboarding-check.md documents the setup-status gates as implemented in the editor. The chain stops at the first failing gate, so the card shown proves every earlier gate passed. It also records that Live Preview, Visual Editor and Timeline each store their own visibility setting and resolve an unset value differently, which is why the settings toggle can read on while the card never appears.

rendering-modes.md gives the contract per rendering mode (CSR, SSR, SSG, GraphQL) and the failures specific to each. frameworks.md covers where init() may run per framework. setup-docs.md maps framework and mode to the official Contentstack page, since setup should follow the docs rather than be reconstructed from memory.

faq-setup.md, faq-preview-runtime.md, faq-visual-editor.md and faq-timeline.md hold 40 entries. Each gives the symptom as users report it, the cause, the fix and a verification step. symptom-index.md indexes them by symptom.

contact-support.md lists causes outside the customer's application (stack provisioning, plan gating, browser policy) and a handover-note template to paste into a Support ticket. console-noise.md lists console output that appears on healthy setups so it is not chased as a cause.

The router row is updated and cursor/ and codex/ are regenerated from skills/.

What was left out on purpose

Entries asserting product bugs, fix versions or fix dates were removed. Bugs get fixed, and the skill would then carry stale data. Launch-hosting specifics for ISR were removed for the same reason. Every remaining entry describes a customer-side cause with a customer-side fix, or states plainly that the cause is outside the application and what to send Support.

Corrections checked against the code

Five claims were checked against live-preview-utils v4.5.3 and the editor code, and fixed:

  • A bypass token in the Base URL does not work for Live Preview. The preview URL is built by joining the Base URL and the entry url as strings, so the path lands inside the token's query value. The advice is gone and base-url-query-string-corrupts-preview-url explains the symptom.
  • stackSdk is optional. Leaving it out flips the ssr default to true, so a CSR site without it must pass ssr: false.
  • The SDK creates #cslp-tooltip on import, before init(). Keeping it off production takes PURGE_PREVIEW_SDK or a preview-only dynamic import; enable: false alone does not.
  • NO_REQUEST_LISTENER_FOUND for scroll comes from clicking the Live Preview edit button when the parent has no scroll listener.
  • The empty-block button renders only in Visual Editor and needs a field schema for its data-cslp path. One invalid wrapper can stop the others from rendering.

Test plan

  • bash scripts/build-cursor-rules.sh && bash scripts/build-codex-skills.sh regenerate cleanly, and codex/ matches skills/ under diff -rq
  • Every references/*.md link in SKILL.md resolves; every symptom-index.md anchor resolves to an entry; no reference file is orphaned
  • All files are valid UTF-8
  • No Jira keys, Slack links, stack UIDs, email addresses or customer names anywhere in the diff
  • Router row matches both "Visual Builder" and "Visual Editor" phrasing

🤖 Generated with Claude Code

@hitesh-shetty-cstk @claude
feat(skills): rebuild live-preview support skill as a diagnostic prot…
6fbf600 
…ocol

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

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

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

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk
hitesh-shetty-cstk requested a review from a team September 2, 2026 12:57
@hitesh-shetty-cstk
hitesh-shetty-cstk marked this pull request as draft September 2, 2026 12:59
hitesh-shetty-cstk and others added 11 commits September 4, 2026 15:01
@hitesh-shetty-cstk @claude
fix(skills): make the Onboarding Check mandatory and warn that onEntr…
53a14b9 
…yChange is inert under ssr: true

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

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

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
fix(skills): add the reproduction rule; no code change without a repr…
7caef3a 
…oduced failure

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

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
fix(skills): add the transition rule; any regression restarts at step 2
2440e8e 
Worked then broke, a gate that advanced then regressed, a new error
replacing an old one: each restarts at step 2 with "what changed since it
last worked", and the answer must include the agent's own edits since the
last known-good state, not only the user's. Step 2 now says the question
applies to every mid-session transition, not only at intake. From the same
dry run as the previous two commits.

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
fix(skills): document the Visual Editor onboarding check and the mode…
62515b3 
…: "builder" requirement

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

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

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

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
fix(skills): state the mode: "builder" requirement in SKILL.md and th…
096d026 
…e edit-tags entry

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

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
fix(skills): carry the mode: "builder" requirement into setup-docs an…
29b41d2 
…d the preflight checklist

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

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
docs(skills): document edit-tag key convention and container tagging
9960b5a 
Contract 2 told the reader to "tag the leaf element" and to call
addEditableTags on referenced entries as well. Both were wrong for the
common case, and the FAQ already said otherwise:

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

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

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

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
docs(skills): add no-resilience rule and backwards-gate note
0cf6360 
Two process rules from a dry run against the Next.js example, where the
diagnosis went wrong in ways the existing rules did not catch:

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

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
docs(skills): say where include_applied_variants has to be passed
ef91c65 
The skill mentioned the flag once, as an aside claiming it "only adds
metadata to the response body". That undersells it: the metadata is
_applied_variants, which is what makes addEditableTags emit v2 tags,
which is what Highlight Variant and audience mode key on. Without the
flag the variant content renders and both features silently do nothing.

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

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

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
docs(skills): keep only the working include_applied_variants form
8614c2d 
Drop the two "accepted but never sent" examples and the version-pinned
note about them. The skill documents the query-parameter form that
works; the SDK-side gap is tracked in Jira instead, so the skill does
not carry bug state that goes stale once it is fixed.

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
docs(skills): describe the Timeline onboarding check as it renders
e94588f 
The skill described Timeline's check as one card whose failure labels
were "Set default environment", "Use updated SDK" and "Use preview
token". Those are the Heap analytics strings, not what the editor shows.

Rewrite from OnboardingOverlay.tsx and useOnboardingValidations.tsx:

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

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

Co-Authored-By: Claude <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings September 8, 2026 07:00
Copilot AI reviewed Sep 8, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The old skill slug is still referenced by the repo’s inventory (e.g., manifest/README), and the new slug isn’t registered there, which can break downstream discovery/packaging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR rebuilds the Live Preview/Visual Builder support skill into a structured “Visual Editor” diagnostic protocol with supporting reference files, then updates routing and regenerated downstream artifacts (Cursor rules + Codex).

Changes:

  • Replaces the prior single-file skill with a 7-step intake/debugging protocol and a set of reference markdowns (onboarding gates, rendering modes, frameworks, edit-tags, FAQs, escalation).
  • Updates the router to route Live Preview + Visual Editor/Builder questions to the new skill slug.
  • Regenerates cursor/rules/ and codex/ outputs to reflect the new skill structure.
File summaries
File Description
skills/cms-live-preview-visual-editor-support-assistant/SKILL.md New canonical skill defining the fixed 7-step diagnostic protocol.
skills/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md Reference for interpreting product-specific onboarding checks and gates.
skills/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md Rendering-mode contracts and common failure modes (CSR/SSR/SSG/GraphQL).
skills/cms-live-preview-visual-editor-support-assistant/references/frameworks.md Framework-specific guidance on correct init() placement.
skills/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md Routing to official setup docs by framework and mode.
skills/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md Edit-tag (addEditableTags) conventions and DOM placement checklist.
skills/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md Ordered checklist to validate contracts end-to-end.
skills/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md Symptom-to-FAQ index for quicker diagnosis.
skills/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md Setup-focused FAQ entries referenced by the symptom index.
skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md Runtime behavior FAQ (caching, locale, variants, navigation, etc.).
skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md Visual Editor canvas/edit-tag behavior FAQ.
skills/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md Timeline-specific FAQ (timestamp forwarding, compare highlighting).
skills/cms-live-preview-visual-editor-support-assistant/references/contact-support.md Escalation criteria + Support handover template.
skills/cms-live-preview-visual-editor-support-assistant/references/console-noise.md Known-benign console messages to de-risk false leads.
skills/cms-live-preview-visual-builder-support-assistant/SKILL.md Removes the previous Visual Builder skill file (superseded).
skills/CLAUDE.md Router updated to point Live Preview/Visual Editor/Builder to the new skill.
cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc Regenerated Cursor rule for the new skill.
cursor/rules/07-cms-live-preview-visual-builder-support-assistant.mdc Removes the old Cursor rule for the removed skill.
cursor/rules/00-router.mdc Regenerated Cursor router rule to route to the new skill.
codex/cms-live-preview-visual-editor-support-assistant/SKILL.md Regenerated Codex version of the new skill.
codex/cms-live-preview-visual-editor-support-assistant/references/onboarding-check.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/rendering-modes.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/frameworks.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/setup-docs.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/edit-tags.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/preflight-checklist.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/symptom-index.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/faq-setup.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/faq-timeline.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/contact-support.md Regenerated Codex reference.
codex/cms-live-preview-visual-editor-support-assistant/references/console-noise.md Regenerated Codex reference.
codex/cms-live-preview-visual-builder-support-assistant/SKILL.md Removes the old Codex skill artifact for the removed skill.
codex/AGENTS.md Updates Codex router table to reference the new skill.
Review details
  • Files reviewed: 35/35 changed files
  • Comments generated: 5
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread skills/CLAUDE.md Outdated
Comment thread codex/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md Outdated
Comment thread codex/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
Comment thread skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md Outdated
Comment thread skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md
@hitesh-shetty-cstk @claude
docs(skills): link the Custom Preview URLs docs instead of restating …
beab56f 
…syntax

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

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings September 8, 2026 11:38
Copilot AI reviewed Sep 8, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Repo metadata/docs still reference the removed Visual Builder skill and there’s a small formatting defect (duplicate section separator) in the new reference content.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

skills/cms-live-preview-visual-editor-support-assistant/references/faq-visual-editor.md:58

  • There are two consecutive horizontal-rule separators here (two --- blocks with only blank lines between). This renders oddly and looks like an accidental duplicate section break; keep only a single separator before the next FAQ entry.

skills/CLAUDE.md:11

  • The router entry was updated to the new cms-live-preview-visual-editor-support-assistant, but other repo metadata still references the removed cms-live-preview-visual-builder-support-assistant (e.g. manifest.json:36 and README.md:60). This leaves the repository’s published skill list inconsistent and may omit the new skill from any tooling that reads those files; update them to use the new slug/title and remove the old one.
| Use for any Contentstack Live Preview, Visual Editor or Visual Builder question (Visual Editor and Visual Builder are the same product), whether setting it up or debugging it: first-time integration in any framework, SDK upgrades, the SDK installed but nothing happening, a blank preview pane, stale or published-only preview, preview context lost after navigation, cache contamination, a variant rendering the base entry, blank locales, Timeline showing the wrong version, canvas or edit-tag resolution failures, or one user seeing empty content where colleagues do not. | [Live Preview and Visual Editor Support Assistant](./cms-live-preview-visual-editor-support-assistant/SKILL.md) |
  • Files reviewed: 35/35 changed files
  • Comments generated: 0 new
  • Review effort level: Lite

hitesh-shetty-cstk and others added 3 commits September 8, 2026 17:15
@hitesh-shetty-cstk @claude
docs(skills): separate the HTTP and untrusted-certificate cases
39c13c7 
Both blank the preview frame at the first Live Preview gate, but they
differ in what the customer can do. Plain HTTP inside the HTTPS app is
mixed content and the browser blocks it with no bypass. An untrusted
certificate (self-signed localhost, corporate CA) can be accepted by
opening the preview URL in its own tab and proceeding past the warning;
the browser keeps that exception for the origin and the pane loads on
reload. State both in preflight item 6 and the gate-1 row.

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
docs(skills): localhost over HTTP is fine; mixed content has a bypass
2522442 
The previous wording said any http:// preview URL is blocked with no
bypass. Two corrections: browsers treat http://localhost as a secure
context, so a plain-HTTP dev server loads in the pane, which is the
common local setup. For other http:// hosts the frame is mixed content
and blocked, but the user can allow insecure content for the
Contentstack app origin (Chrome shield icon or the Insecure content site
setting). Certificate wording unchanged.

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
docs(skills): only ask the customer for things they can observe
d30117f 
The skill pointed readers at Contentstack-app internals as if they were
their own site's evidence. Worst case was contract 1, whose one-look
check was "POST /live-preview/tracker returns 2xx" — a request the
Contentstack app issues, never the customer's site, and one that
succeeds even when init() never ran, so it could not fail for the reason
it existed to detect.

Swept all fourteen files. Removed or re-anchored:

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

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

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

Regenerate the cursor and codex trees.

Co-Authored-By: Claude <noreply@anthropic.com>
@snyk-io

snyk-io Bot commented Sep 8, 2026

Copy link
Copy Markdown

✅ Snyk checks have passed. No issues have been found so far.

Status Scan Engine Critical High Medium Low Total (0)
✅ Code Security 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

@snyk-io

snyk-io Bot commented Sep 11, 2026 •
edited
Loading

Copy link
Copy Markdown

✅ Snyk checks have passed. No issues have been found so far.

Status Scan Engine Critical High Medium Low Total (0)
✅ Code Security 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

hitesh-shetty-cstk and others added 3 commits September 11, 2026 16:34
@hitesh-shetty-cstk @claude
fix(skills): update skill inventory for the visual-editor rename
a7fef8a 
manifest.json and README.md still listed the old
cms-live-preview-visual-builder-support-assistant slug after the
directory and router row moved to the visual-editor name, so tooling
that reads the inventory advertised a skill that no longer exists.

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

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
fix(skills): correct SDK and onboarding claims, slim the live-preview…
ae24426 
… skill

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

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

Restructure:

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@hitesh-shetty-cstk
Merge branch 'main' into feat/visual-editor-support-assistant
37be546
hitesh-shetty-cstk and others added 2 commits October 8, 2026 16:19
@hitesh-shetty-cstk @claude
docs(skills): state framework support per rendering mode, drop hedges
178debd 
The SDK has no framework-specific code, so support follows from each
route's rendering mode. Replace the "not covered / untested / not proven"
notes with the contract that applies:

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@hitesh-shetty-cstk @claude
docs(router): route preview questions away from dx-delivery-sdk
ca37a8a 
The dx-delivery-sdk row claimed Live Preview setup, Visual Builder support
and SSR preview handling, which overlaps the live-preview support skill.
Keep the row on Delivery SDK query code and point preview questions to
the Live Preview and Visual Editor Support Assistant.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@hitesh-shetty-cstk
hitesh-shetty-cstk marked this pull request as ready for review October 8, 2026 11:53
@hitesh-shetty-cstk
hitesh-shetty-cstk requested a review from a team as a code owner October 8, 2026 11:53
@hitesh-shetty-cstk @claude
fix(skills): correct five support-assistant claims against the SDK code
5a8d2ec 
Checked against live-preview-utils v4.5.3 and the Visual Editor and
Live Preview panel code:

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings October 14, 2026 06:25
Copilot AI reviewed Oct 14, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Cursor cannot resolve the new references, and the protocol still contains conflicting intake and sensitive-hash logging instructions.

6 open findings
5 resolved since last review

🧠 Review effort: Lite

Comment thread skills/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
Comment thread skills/cms-live-preview-visual-editor-support-assistant/references/faq-preview-runtime.md
Comment thread cursor/rules/07-cms-live-preview-visual-editor-support-assistant.mdc
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

@hitesh-shetty-cstk hitesh-shetty-cstk Oct 14, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. The Cursor build ships only .mdc files, so reference links in the rule do not resolve. Bundling references changes the build script and README for every skill, so it will go in a separate PR rather than this one. Leaving this open until then.

Comment thread skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
Comment thread skills/cms-live-preview-visual-editor-support-assistant/SKILL.md
Comment thread skills/cms-live-preview-visual-editor-support-assistant/references/faq-integration.md
timbenniks-contentstack added a commit that referenced this pull request Oct 14, 2026
@timbenniks-contentstack @hitesh-shetty-cstk @claude
Apply PR #18: Live Preview / Visual Editor diagnostic protocol
31cc512 
Rebuilds the support skill as a 7-step evidence-first protocol with 12
reference files, renamed to cms-live-preview-visual-editor-support-assistant.

On top of the PR: description keeps the previous triggers (SSR state,
cache contamination, edit-tag mapping, lost context, code review) and says
"Use when"; never log hash values (log presence only); Management Token
write access depends on scope; regressions read the Onboarding Check before
asking what changed; SSR evidence comes from server logs or a proxy trace.
Docs and README updated for the new slug.

Co-authored-by: Hitesh Shetty <hitesh.shetty@contentstack.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@timbenniks-contentstack timbenniks-contentstack mentioned this pull request Oct 14, 2026
Merged
@timbenniks-contentstack

timbenniks-contentstack commented Oct 14, 2026

Copy link
Copy Markdown
Contributor

Thanks @hitesh-shetty-cstk, this rebuild is a big step up! It's now in #21, the combined 0.2.0 release PR, keeping your folder name and all 12 reference files. A few small changes on top, mostly from the Copilot review:

  • The description keeps the old triggers (shared SSR state, cache contamination, edit-tag mapping, lost context, code review) and says "Use when".
  • The skill now only checks whether a hash is present and never logs its value.
  • Management Token write access is described as depending on scope.
  • Regressions read the Onboarding Check before asking what changed.
  • SSR evidence comes from server logs or a proxy trace instead of the browser Network tab.

You're credited as co-author. Closing in favour of #21.

@hitesh-shetty-cstk hitesh-shetty-cstk mentioned this pull request Oct 14, 2026
Open
3 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@hitesh-shetty-cstk @timbenniks-contentstack