Aetheria-Labs1/storefront-skills / skills/publish
publish
VerifiedPublish a Lexsis storefront draft version that carries DESIGN_APPROVED from /design-page, /quiz, or /optimize. Use only when the user explicitly asks to release a specific page version.
references/cart-profile-management.md
View on GitHub# Cart Profile MCP Management
The Storefront MCP exposes cart inspection, draft design/promotion editing,
previews and approved lifecycle operations through the same backend as the app.
## `lexsis_cart.get`
Inspect the effective cart for a page or one editable profile.
Inputs:
- `page_id`
- `cart_profile_id`
- `store_id` as an optional multi-store hint
- `include_available_profiles`
- `include_history` for the latest 100 lifecycle events, authenticated actor/client and diff summaries
- `fields` for selected profile fields/dotted paths; unknown paths fail
- `response:"full"` for complete source; metadata is the default
Pass `page_id` to get the published snapshot a shopper receives and its
`resolution_source`. Pass `cart_profile_id` to inspect the draft.
Always call this tool before assigning or editing.
## `lexsis_cart.capabilities`
Read the current cart composition contract before authoring a custom module.
The response describes:
- supported layout schema and module types
- protected renderer-owned cart modules
- source compilation and placement operations
- design token and custom CSS capabilities
- promotion access boundaries
- the frozen `lifecycle.cart` snapshot schema and settled `onCart` subscriptions
- managed line, code, attribute, note, gift and variant commands with scoped responses
- module `visible_when`, condition fields/operators and no-JS binding paths
## `lexsis_cart.promotions`
Read configured profile offers plus active Shopify discount codes and automatic
discounts. Pass `cart_profile_id` alone to infer its store; `store_id` is an
optional explicit scope. A store-only call lists Shopify discounts without
profile readiness. This operation is read-only. Use `cart_promotions_edit` for requested
draft edits and explicitly approved `cart_publish` for Shopify synchronization.
## `lexsis_cart.preview`
Pass `page_id`, `cart_profile_id`, and a fixture name: `empty`,
`below_first_reward`, `between_rewards`, `all_unlocked`, `gift_chosen`, or
`code_applied`. Optional `cart_version` pins a saved version. Explicit fixture:
`{lines:[{variantId,quantity,sellingPlanId?}],codes?:[]}` (real store GIDs,
12 lines, quantity 1-999, 10 codes). Default fixture is empty.
The URL carries `preview=1`, `cart_version` and a signed `fixture` token,
expiring in 15 minutes. Omit `page_id` for an isolated sample cart. No browser
is started. Open the URL in your own browser. Samples are computed from synced
catalogue prices and shared reward calculations, marked `source:"computed"`.
They do not mutate Shopify, restore/write `lx_cartId`, or permit checkout.
Tracking is suppressed. Tampering/expiry logs `fixture_invalid` and falls back
to normal cart: confirm fixture mode before interacting. The sample badge is
at the top, dismissible, and omitted with `preview_badge=0` for screenshots.
Removing the badge does not change fixture isolation. Fixture country and
language use Shopify's configured default region and primary locale, independent
of request geolocation or currency. Missing market access is reported as unknown.
## `lexsis_cart.preview_states`
Pass `{page_id,cart_profile_id}` for all six signed URLs. `response:"compact"`
is the default: each state has `url`, `total`, `savings`, `visible_modules`,
`warnings` and `status`. Use `response:"full"` for CartSnapshots, module
definitions and detailed static checks. Checks: setting warnings,
configured color contrast, shown unready rewards, custom compilation and
hardcoded checkout links. No screenshots or DOM measurements. Unavailable
fixtures/checks are explicit warnings or `not_run`, not proof of success.
For animation QA after opening the cart, call `window.__lx.celebrate(rewardId)`.
This replays the normal configured unlock effect without changing commerce.
The readiness and reduced-motion checks remain active. It bypasses only the
once-per-cart/session limit.
`setting_not_rendered` warnings describe only fields present in the edit's
`design_patch`. Server-injected defaults and untouched stored settings do not
produce repeated edit, preview or publish warnings.
Publish responses return consistent top-level and `profile.used_by`, plus
`changed_fields` and `pages_affected` (live pages using this profile). Replaying
an already-published version returns no changed fields.
## Edit-loop response and CSS contract
Draft writes return compact summaries by default; `response:"full"` returns
full profile source. `cart_edit dry_run:true` runs the same compiler, returns
errors/warnings, a module tree and signed uncommitted URL without saving a
version. Module visibility uses an empty fixture; an unavailable evaluator is
reported explicitly. Saved edits with `preview_error` should retry preview,
not the write.
`custom_css` replaces all CSS, including named blocks; null clears it.
`css_ops:[{op:"upsert",id:"checkout",css:"..."},{op:"remove",id:"old"}]` updates
named blocks in insertion order. Upsert keeps the position; removal requires
an existing ID. First use preserves old CSS as `legacy`. Both together fail.
Each block and their concatenation are sanitized and scoped.
`island_schema` defaults to a compact overview with shared `$defs.iconName`.
`fields:["rewards"]` expands a prop; `verbose:true` adds full styling/examples.
`type_expression` definitions preserve the authoring DSL with `$ref(...)`
aliases; they are not standalone JSON Schema.
## `lexsis_drafts.cart_set`
Assign a published profile to a page:
```json
{
"page_id": "PAGE_UUID",
"cart_profile_id": "PROFILE_UUID"
}
```
Remove the page assignment and restore fallback resolution:
```json
{
"page_id": "PAGE_UUID",
"cart_profile_id": null
}
```
The page and profile must belong to the same store. Draft and archived profiles
cannot be assigned.
## `lexsis_drafts.cart_edit`
Apply a design or composition patch to a profile draft:
```json
{
"cart_profile_id": "PROFILE_UUID",
"expected_version": 12,
"change_note": "Add a cart reminder above checkout",
"patch": {
"design_patch": {
"shell": {"title": "Your cart"}
},
"custom_css": "[data-part=\"checkout\"] { font-weight: 700; }",
"composition_ops": [
{
"operation": "upsert",
"module_id": "checkout-reminder",
"region": "footer",
"source": "<!-- section: checkout-reminder -->\n<section><p>Review your cart before checkout.</p></section>",
"before_module_id": "checkout",
"visible_when": {
"op": "AND",
"clauses": [{"field": "cart.item_count", "op": "gt", "value": 0}]
}
}
]
}
}
```
Supported patch fields:
- `cart_mode`
- `design_patch`
- `custom_css`
- `composition_ops`
Composition operations support `upsert`, `move`, `set_enabled`, and `remove`.
An upsert compiles the same section source shape used by normal storefront
pages: HTML, CSS, JavaScript, and managed motion. It may use active storefront
islands, but it cannot replace or nest renderer-owned cart modules such as cart
lines, summary, or checkout. Existing custom and optional built-in modules may
omit source when upserting `visible_when`; pass null to clear the condition.
Custom scripts read the frozen `lifecycle.cart` snapshot and subscribe with
`lifecycle.onCart((snapshot, previous) => ...)`. Subscriptions wait for confirmed
currency/prices and completed cart settlement, coalesce per frame, and clean up
on unmount. Money is `{amount, currencyCode, minor}` and matches CartSummary.
No default currency is invented.
Dispatch managed commands from `section` with `bubbles: true` and a unique
`requestId`: `lx:cart:add-items`, `update-line`, `remove-line`, `apply-code`,
`remove-code`, `set-attributes`, `set-note`, `choose-gift`, `swap-variant`
(all use the `lx:cart:` prefix). Read the exact payload and error contract from
capabilities. Responses return to the originating module. Identical replay
does not write again; a changed payload under the same ID is rejected.
`visible_when` uses AND/OR clauses over typed cart, reward and context fields.
Money comparisons use minor units; membership `neq` hides an offer when the
given variant is present. It sets `hidden`, including for inline offers and
inside-checkout payment logos. `data-lx-if` supports validated comparisons and
predicates; `data-lx-text="rewards.next.remaining"` formats real Money without
JavaScript. Unknown fields, types and expression paths fail before saving.
Customer context requires a host provider; collection membership requires
Shopify metadata access. Missing metadata is not proof of exclusion.
Design objects merge. Composition operations are applied in order. Pass
`custom_css: null` to remove profile CSS. The tool validates and compiles the
complete merged configuration and never publishes.
Presentation edits rebuild cart sections. `shell.title` controls the visible
header and dialog label. Disabled optional modules stay absent; product-offer
visibility is mirrored into offer slots so inline offers also disappear.
Use `design_patch.modules.payment_options.placement` for `inside_checkout`,
`below_checkout`, or `hidden`, and `providers` for a unique, ordered provider
list. The payment module's enabled flag gates both placements. Variant,
alignment, colors, and icon styling apply inside checkout too.
Read the returned `warnings` array. Entries with `code: "setting_not_rendered"`
identify a stored path with no effect. Responsive overrides support tokens,
`shell.width`, and module/state CSS; use base settings for island props.
Deprecated gift `lock_quantity` and the unused `warning` color token have no
effect. Confirmed gift quantities remain controlled by reward rules.
Promotion configuration, cart rules, raw commerce configuration, and raw layout
schema are deliberately absent from the MCP edit contract.
## Lifecycle and promotion actions
Capabilities report `lifecycle_access: "mcp_with_approval"` and
`promotion_access: "draft_then_publish"`. The custom-module lifecycle is under
`module_lifecycle`, alongside the unchanged snapshot and command schemas.
| Router | Action | Arguments |
|---|---|---|
| `lexsis_drafts` | `cart_create` | `store_id`, `name`, optional `from_preset` or `from_profile_id` |
| `lexsis_drafts` | `cart_duplicate` | `cart_profile_id`, `name` |
| `lexsis_drafts` | `cart_promotions_edit` | `cart_profile_id`, `expected_version`, `patch` |
| `lexsis_drafts` | `cart_archive` | `cart_profile_id`, optional `reassign_to` |
| `lexsis_drafts` | `cart_assign_campaign` | `campaign_id`, `cart_profile_id` (nullable) |
| `lexsis_live_ops` | `cart_publish` | `cart_profile_id`, `expected_version`, `allow_partial:false`, `skip_reward_ids:[]` |
| `lexsis_live_ops` | `cart_rollback` | `cart_profile_id`, `target_version` |
| `lexsis_live_ops` | `cart_set_default` | `store_id`, `cart_profile_id` |
Presets: `default`, `subscription`, `aov_booster`. Creation and duplication are
unpublished. Optional `store_id` speeds profile/campaign lookup.
Promotion patches merge `rewards`, `offer_slots`, `quantity_promotions` and
`cart_rules` by ID. Omitted rows remain. `{id,operation:"remove"}` removes one
existing row; an empty patch array is a no-op. New rows need complete required
fields. `coupon_settings` and `payment_settings` merge objects; nested arrays
replace. Coupon allow-list is `coupon_settings.coupons`; manual entry is
`allow_manual_entry`. Payment `placement` is `inside_checkout | below_checkout |
hidden`; `providers` is an ordered unique list. Monetary thresholds use minor
currency units. Gift/qualifying products and collections use verified Shopify IDs.
`qualification_basis` (`whole_cart | scoped`) switches the profile between the
whole-cart milestone Function and per-reward native codes.
## Choosing a reward mode
Every milestone setup answers one question first: **who makes the reward free
at checkout?** Pick exactly one mode per profile. Mixing them shows "unlocked"
while the shopper is charged, or gives a gift twice.
### Decide in this order
1. **Is checkout a third-party app** (GoKwik, Shiprocket, Razorpay Magic,
Simpl, etc.)? Look for its script or a checkout-button override in the theme,
or ask the merchant. Shopify Functions and most Shopify codes do not run
there. -> **External**, and configure the offer in that app.
2. **Does another app already give these gifts** (Rebuy, GoKwik offers, a
Shopify automatic discount)? -> **External**, with identical thresholds and
gifts. Never let Lexsis add a second gift.
3. **Shopify checkout, and the store uses the public Lexsis app**, and you need
tiers that replace each other (5% -> 10%, not 15%), a single free-shipping
tier, or gift + discount on the same ladder? -> **Milestone Function**.
4. **Otherwise** -> **Native codes** (the default).
| | Native codes | Milestone Function | External | Display-only module |
|---|---|---|---|---|
| Select with | No `milestone_program`; `discount_source` `managed` (Lexsis creates the code) or `existing` (merchant code, verified, never edited) | `qualification_basis:"whole_cart"` (adds `commerce_config.milestone_program`) | `discount_source:"external"` on each reward | A custom module (`composition_ops`) that reads `cart.rewards` |
| Who gives the reward | Shopify discount engine; one code per reward | The `lexsis-cart-milestones` Rust Function via one `LXM-` code | The checkout or offer app | Nobody: presentation only |
| Gift line in the bag | Added by Lexsis (automatic for one-variant gifts; multi-variant and fixed-price gifts need the shopper's choice) | Added by Lexsis; the Function prices it | A display-only row for the highest unlocked gift, "Added at checkout"; never sent to Shopify | Whatever the module draws |
| Tiers | **All earned tiers stack** (codes combine) | Highest discount tier only; all earned gifts and shipping apply | Highest gift replaces lower ones | Module's own copy |
| Shopper coupons | Combine with reward codes | **Replace the whole ladder** (program code does not combine) | Handled by the checkout app | n/a |
| Requirements | Any plan; `write_discounts`. Free gifts need a qualifying collection or products | Shopify checkout **and** the public Lexsis app. Enterprise/custom apps (e.g. Tilt, XAGO) ship no Function, so readiness reports `milestone_function_unavailable` on every plan, including Plus. Base-currency carts only | Nothing in Lexsis. Thresholds and gifts must match the app's offer | Must not contradict the mode above |
| Never | Use when a checkout app also gives the gift | Mix with `external` rewards (rejected) or publish while `milestone_function_unavailable` | Expect Lexsis to enforce or price anything | Change prices or set `_lx_*` attributes |
### Rules for custom milestone copy
A custom module (for example a branded milestone bar) only displays. Its words
must match the mode: with External or the Function, write "upgrade to" or
"replaces" for higher tiers, never "X + Y", unless checkout really gives both.
Read `cart.rewards.next` and `cart.rewards.unlocked` rather than hard-coding
amounts. `unlocked` means earned, not applied. Turn off the built-in
`reward-progress` module when a custom bar replaces it, so the bag shows one bar.
### Verify before publishing
1. `lexsis_cart.promotions` readiness is `ready` for every enabled reward.
2. Preview the cart below, between and above each threshold.
3. For External: open the real checkout with a test bag (stop before paying) and
confirm it gives the same gift the bag shows.
Readiness rows only carry `qualification_basis:"whole_cart"` in Function mode;
a missing value means native codes.
The promotion edit response includes `profile` and `readiness`. Incomplete setup
can be saved; malformed values and stale versions fail. Shopify transport
failure returns a saved draft with `readiness_unavailable`. No promotion edit
writes to Shopify. Readiness uses the same validator as publication.
Publishing requires explicit approval and publish access. It checks the exact
version, provisions the managed contracts, then commits the live pointer.
`CART_NOT_READY` includes issues; `VERSION_CONFLICT` includes the current version.
Partial publication disables only the explicitly approved `skip_reward_ids`,
then reruns readiness. Remaining/global issues still block publication. The
response gives `published_version`, created/updated/disabled Shopify discount IDs
and warnings. Contract resolution can add a version. Use the returned version.
Rollback makes a new forward draft and leaves the live version unchanged.
Preview it, then obtain separate approval for `cart_publish`. Default and
campaign/page assignment change live resolution and require approval plus
publish access. Campaign assignment is under drafts but is not draft-only.
Archive blocks default or assigned profiles unless `reassign_to` is a published
replacement in the same store. It preserves assignment priority/enabled state.
Shopify has no cross-mutation transaction. On failure the publisher compensates
created/retired discounts; an unconfirmed cleanup returns
`CART_PUBLISH_RECOVERY_REQUIRED` and must be resolved before retrying. A discount
still shared by another published profile remains active with a warning.
## Verification
After a mutation, re-read the draft with `lexsis_cart.get`, then call
`lexsis_cart.preview`. Confirm the profile ID and version, and visually inspect
the preview at desktop and mobile widths. Assignment and publication remain separate approved actions.
Use `get` with `include_history:true` to inspect the actor/client and diff summary.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |