@wix/agent-skills 1.0.0

package/skills/wix-headless/references/ecom/CART_PAGES.md

@@ -0,0 +1,120 @@
+# Phase 4 Cart Pages — Ecom
+
+Scope: `ecom-pages`. Launched in **Step 7**. Mounts `CartView` island on the cart page, wires the thank-you page, and mounts `CartBadge` in Navigation.
+
+## Scope
+
+Files this agent OWNS (rewrites from designer output):
+
+- `src/pages/cart.astro` — mount `CartView.tsx` (client-only, no server-side cart fetch)
+- `src/pages/thank-you.astro` — read `orderId` from URL, fire `Purchase` event
+
+Files this agent PATCHES (does NOT rewrite):
+
+- `src/components/Navigation.astro` — mount `CartBadge` in the `nav-actions` area
+
+Files this agent MUST NOT touch:
+- `src/components/CartView.tsx` — owned by `ecom-shared` (already written)
+- `src/components/CartBadge.tsx` — owned by `ecom-shared`
+- Any product page, home page, or stores-specific component
+- `global.css`, any designed component
+
+## Critical rules
+
+1. **No server-side cart fetch** — cart is per-visitor and must not break SSR caching. `CartView` fetches its own data on mount.
+2. **Mount `CartView` with `client:load`** — no props needed, the island is self-contained.
+3. **Fire `Purchase` event in `thank-you.astro`** only when `?orderId=` is present.
+4. **Mount `CartBadge` in `Navigation.astro`** (not Layout.astro, not a page-specific header).
+5. **No HTML comments in `.astro` frontmatter** — frontmatter is TypeScript.
+6. **Preserve designer layout and classes.** Only mount islands and wire data; do not restructure markup.
+7. **Do NOT add static HTML alongside `<CartView>`** — the island handles empty/loading/cart states internally.
+
+## Implementation
+
+### 1. `src/pages/cart.astro`
+
+Use template `templates/cart.astro`.
+
+Mounts `CartView` as a client-only island. **No server-side cart fetch** — cart data is per-visitor and would break SSR caching. CartView fetches the cart client-side on mount. Key requirements:
+
+- **No `currentCart` import in frontmatter** — do not fetch cart data server-side
+- Mount `<CartView client:load />` — no props needed, the island fetches its own data
+- Preserve whatever the designer wrote around the mount (headings, breadcrumbs, section wrappers)
+- Do NOT add static HTML alongside `<CartView>` — the island handles empty/loading/cart states internally
+
+### 2. `src/pages/thank-you.astro`
+
+Use template `templates/thank-you.astro`.
+
+Wix redirects here after successful checkout with `?orderId=<id>`. Fires `Purchase` analytics event when orderId is present. Preserve whatever the designer wrote around the order confirmation content (headings, layout wrappers). The key requirements:
+
+- Read `orderId` from URL search params
+- Display order confirmation with the orderId
+- Fire `Purchase` event via the analytics helper (client-side script)
+- Only fire when `orderId` is present — refreshing without it should not re-fire
+
+### 3. Mount CartBadge in `Navigation.astro`
+
+Mount `CartBadge` inside the `nav-actions` area. The designer creates this with a `<slot name="actions" />` or similar placeholder. Because Navigation is in the shared Layout, the badge appears on every page.
+
+```astro
+---
+// Add to Navigation.astro frontmatter:
+import CartBadge from "./CartBadge.tsx";
+---
+
+<!-- Replace the nav-actions slot with the CartBadge island: -->
+<div class="nav-actions">
+  <CartBadge client:only="react" />
+</div>
+```
+
+Use `client:only="react"` — never SSR the badge. SSR would render `count: 0` (sessionStorage is a browser-only API), then hydration would read the cached count and flip to the real number, causing a visible blink on every page navigation. Skipping SSR means the badge renders once on the client with the cached count already populated. No flash.
+
+## Checkout flow summary
+
+CartView's `handleCheckout` runs:
+
+```
+Cart page → "Proceed to Checkout"
+  → currentCart.createCheckoutFromCurrentCart({ channelType: WEB })
+  → redirects.createRedirectSession({ ecomCheckout: { checkoutId }, callbacks: { thankYouPageUrl, cartPageUrl } })
+  → window.location.href = redirectSession.fullUrl
+  → User completes payment on Wix-hosted checkout
+  → Redirect back to /thank-you?orderId=<id>
+```
+
+**Going-live note** (emitted by the skill, not this agent):
+> Checkout is hosted by Wix and will show "we aren't accepting payments" until: (1) upgrade to premium eCommerce plan, (2) connect a payment provider.
+
+## Analytics fired from this scope
+
+| Event | Fires from | When | Payload |
+|-------|------------|------|---------|
+| `Purchase` | `thank-you.astro` | On mount when `?orderId=` is present | `{ id: orderId, origin: "Thank You Page" }` |
+
+`RemoveFromCart` and `InitiateCheckout` fire from `CartView.tsx` (owned by `ecom-shared`).
+
+## Return format
+
+```json
+{
+  "status": "complete",
+  "phase": "ecom-pages",
+  "scope": "ecom-pages",
+  "summary": "Mounted CartView (client-only fetch); wired Purchase event; mounted CartBadge in Navigation",
+  "data": {
+    "pagesWired": 2,
+    "cartViewMounted": true,
+    "purchaseEventWired": true,
+    "cartBadgeMounted": true,
+    "analyticsEvents": ["Purchase"]
+  },
+  "files": [
+    "src/pages/cart.astro",
+    "src/pages/thank-you.astro",
+    "src/components/Navigation.astro"
+  ],
+  "errors": []
+}
+```

package/skills/wix-headless/references/ecom/CART_WIRING.md

@@ -0,0 +1,103 @@
+# Phase 3 Components — Ecom (TSX)
+
+Scope: `components`. Launched in **Step 4.5** (after Phase 2 Design System completes, parallel to stores components and the `components-css` sibling). Writes code that depends on the **design tokens** but NOT on Phase 4 page markup.
+
+> **CSS lives in a sibling scope.** `src/styles/components-ecom.css` is owned by the `components-css` scope (see `./COMPONENTS_CSS.md`), which runs concurrently with this one in the same Step 4.5 batch. This scope does NOT write the CSS file. Reference contract class names from the design tokens here; the CSS sibling defines the rules.
+
+## Scope
+
+Files this agent OWNS (creates fresh):
+
+- `src/components/CartView.tsx` — React island; full cart display + checkout redirect
+- `src/components/CartBadge.tsx` — React island; nav-wide cart count badge
+
+Files this agent MUST NOT touch:
+- `src/styles/components-ecom.css` — owned by the **`components-css`** sibling scope (see `./COMPONENTS_CSS.md`). Reference its class names; do not write the file.
+- Any `.astro` page — designed and later rewritten by other scopes
+- `src/styles/global.css` — owned by designer foundation
+- `src/layouts/Layout.astro` — owned by designer foundation
+- Any stores-specific component (AddToCartButton, ProductPurchase, etc.)
+
+## Coordination: design tokens
+
+Your parent prompt includes the design tokens inline. Use it directly — do not read `.wix/design-tokens.css` + `.wix/site.d.ts` from disk.
+
+For layout/spacing/typography, compose Tailwind utilities derived from `@theme` tokens at the call site (`<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-2xl">`). For published global semantic classes (`cart-summary`, `cart-total`, `checkout-btn`, `cart-empty` — the compound + interactive-state patterns), use the ACTUAL class name verbatim. Row-internal class names (`cart-item-qty`, `qty-btn`, etc.) come from the template — keep them as-is and live in `components-ecom.css`. See `references/shared/STYLING.md` and `references/shared/IMPLEMENTER.md` § "Styling: tokens-first, classes as exception".
+
+## Template files
+
+This scope uses **template files** instead of inline code. For each file below:
+
+1. Read the template from `<Agent location>/templates/<filename>`
+2. Write it to the project at the target path
+3. Adapt CSS class names if the design tokens maps them differently than the defaults
+
+Do NOT modify logic, imports, or component structure.
+
+## Implementation
+
+### 1. `src/components/CartView.tsx`
+
+Use template `templates/CartView.tsx`.
+
+Full cart display with two-column layout, quantity editing, remove, unavailable item detection, and checkout redirect. **No server-side props** — cart is per-visitor and fetched client-side on mount to keep pages SSR-cache-friendly. Key behaviors:
+
+- **Always use `currentCart` APIs** — never the `cart` namespace that requires a cart ID
+- **Image resolution** — `resolveCartImage()` handles `wix:image://` strings (SDK returns image as a string, not an object)
+- **Description lines** — `formatDescriptionLine()` handles both `plainText` and `colorInfo` types
+- **Per-line price display** — `fullPrice` and `price` are per-unit (shown side by side; `fullPrice` is struck through when an automatic discount is applied to that line); `lineItemPrice` is total (shown below only when qty > 1)
+- **Clickable product link** — the image and product name link back to the product detail page. `item.url` shape varies by caller: the `@wix/ecom` SDK returns it as an absolute URL **string** (e.g. `https://<site>.wixsite.com/<name>/product-page/<slug>`), while REST returns an object `{ relativePath, url }`. `resolveProductHref` accepts both, extracts the slug after `/product-page/`, and rewrites to the headless `/products/<slug>` route. Link is suppressed on unavailable lines (nothing to navigate to for NOT_FOUND/NOT_AVAILABLE items).
+- **Cart-level totals + discount surfaces (API-sourced)** — `extractSummary()` reads `cart.priceSummary.{subtotal, discount, total}` and `cart.appliedDiscounts[].discountName` in one pass. Three distinct surfaces, each sourced directly from the API (no client-side amount math):
+   1. `cart-discount` row — amount + optional name — rendered when `priceSummary.discount` is populated (coupons, cart-level promos).
+   2. `cart-applied-discounts` row — name-only — rendered when `priceSummary.discount` is empty but `appliedDiscounts[].discountName` is populated. This is the common case for **line-item automatic discounts**, where Wix bakes the discount into each line's `price` (with `fullPrice` preserved for the strikethrough). The per-line savings amount already shows inline via the `cart-item-full-price`/`cart-item-unit-price` strikethrough; the summary row just names the promotion.
+   3. `cart-total` row — rendered when `priceSummary.total` differs from `priceSummary.subtotal`.
+  If `priceSummary.subtotal` is missing (some early-stage carts return an empty summary before checkout creation), the subtotal is computed client-side from `lineItemPrice.amount` — do not leave the slot blank. Do NOT aggregate line-item savings into a summary row; shoppers see the strikethrough inline and that is the API's canonical visualization.
+- **Availability** — `isItemUnavailable()` checks for `NOT_AVAILABLE` and `NOT_FOUND` status; hides qty selector, blocks checkout
+- **Optimistic UI** — quantity changes and item removal update local state immediately before the API responds. Quantity changes are debounced (300ms) so rapid clicks coalesce into a single request. On API error, the cart reconciles from the server via `loadCart()`
+- **Instant re-render via sessionStorage snapshot** — every successful cart fetch/update writes `{ lineItems, summary }` to `sessionStorage[CART_CACHE_KEY]`. On mount, CartView reads the snapshot synchronously and renders it before the authoritative fetch completes. Eliminates the empty/loading flash when re-navigating to `/cart`. Per-tab scope (sessionStorage not localStorage) so logout / shared-device scenarios can't leak stale carts to a different identity.
+- **Dispatches `cart-updated`** events so CartBadge updates instantly
+- **LineItem type** — local structural type mirroring the fields the component consumes. `_id` is declared `string | null | undefined` to match `@wix/ecom`'s `currentCart` return so `cart.lineItems as LineItem[]` type-checks cleanly. If you add new fields, mirror the SDK nullability or narrow at the use site.
+
+Class names used (template provides them — do not invent):
+- **Global semantic classes** (in `global.css`, designer-owned): `cart-summary`, `cart-total`, `checkout-btn`, `cart-empty` — compound patterns + interactive states
+- **Row-internal classes** (in `components-ecom.css`, written by this scope): `cart-item-qty`, `qty-btn`, `qty-value`, `cart-item-unavailable`, `cart-item-actions`, `cart-item-prices`, `cart-item-full-price`, `cart-item-unit-price`, `cart-item-line-total`, `cart-item-remove`, `cart-item-image-link`, `cart-item-name-link`, `cart-discount`, `cart-discount-name`, `cart-discount-amount`, `cart-applied-discounts`, `cart-applied-discounts-name`, `cart-item-option`, `cart-item-modifiers`
+- **Layout/spacing in markup as utilities**: `cart-grid` → `<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-2xl md:gap-3xl md:items-start">`; `cart-items` → `<div class="flex flex-col gap-lg">`; `cart-item` → `<div class="flex gap-lg pb-lg border-b border-rule last:border-0">`; `cart-subtotal` → `<div class="flex justify-between items-baseline">`; `cart-item-image` → utilities; `cart-item-info` → utilities; `cart-item-name` → `class="font-display text-lg leading-tight"`
+
+### 2. `src/components/CartBadge.tsx`
+
+Use template `templates/CartBadge.tsx`.
+
+Mounted once in `Navigation.astro` (by `ecom-pages` scope). Shows cart item count; listens for `cart-updated` custom event.
+
+**No `initialCount` prop.** Cart is per-visitor — server-rendering the count breaks SSR caching. On mount, CartBadge reads the sessionStorage snapshot that CartView maintains (same `CART_CACHE_KEY`) to seed the initial count without a visible zero-flash between page navigations, then fetches fresh from the SDK and reconciles. If no snapshot exists (first-ever page load), count starts at 0 like before.
+
+**Mount with `client:only="react"`, never `client:load`.** sessionStorage is browser-only, so SSR would render `count: 0`, then hydration would read the cache and flip to the real number — a visible blink on every page navigation. `client:only` skips SSR entirely; the badge renders once on the client with the cached count already populated.
+
+Contract keys: `cartBadge`, `cartBadgeCount`
+
+### 3. `src/utils/analytics.ts` — not owned by this scope
+
+> `analytics.ts` is a shared utility (see `references/shared/analytics.ts`). Import from it (`import { trackEvent } from "../utils/analytics"`) but do not write it.
+
+### 4. `src/styles/components-ecom.css` — not owned by this scope
+
+> Owned by the **`components-css`** sibling scope. See `./COMPONENTS_CSS.md`. Reference the contract class names from the design tokens in your TSX files; the CSS sibling defines the rules.
+
+## Return format
+
+```json
+{
+  "status": "complete",
+  "phase": "ecom-components",
+  "scope": "components",
+  "summary": "Wrote CartView and CartBadge from templates (CSS handled by components-css sibling)",
+  "data": {
+    "islands": ["CartView.tsx", "CartBadge.tsx"]
+  },
+  "files": [
+    "src/components/CartView.tsx",
+    "src/components/CartBadge.tsx"
+  ],
+  "errors": []
+}
+```

package/skills/wix-headless/references/ecom/COMPONENTS_CSS.md

@@ -0,0 +1,132 @@
+# Phase 3 Components-CSS — Ecom
+
+Sibling of the `components` scope. Launched in **Step 4.5** in the same concurrent batch — runs in parallel with the TSX work, stores components, gift-cards components, and Image Phase 2.
+
+## What this scope owns
+
+Exactly one file:
+
+- `src/styles/components-ecom.css` — scoped CSS for cart/checkout: cart-summary panel, cart-total row, checkout button (with `:disabled` and `:hover` states), empty state, cart-item line layout (image, name, qty controls, prices, modifiers, unavailable state, remove button), discount/applied-discount rows, and the cart-badge nav element. Imported by `Layout.astro` (the designer foundation sets up the import).
+
+## What this scope does NOT own
+
+- Any `.tsx` or `.astro` file. Those are the `components` sibling scope (`./CART_WIRING.md`).
+- `src/styles/global.css` — owned by the designer foundation. **You read it (to audit for ecom-class leaks) but never write it.**
+- `src/styles/components-stores.css`, `src/styles/components-gift-cards.css` — owned by other packs' `components-css` (or `components`) scopes.
+- `src/utils/discounts.ts` — pre-copied by the orchestrator before this dispatch; not your concern.
+
+## Reading set
+
+You only need:
+
+1. **`<SKILL_ROOT>/templates/ecom/components-ecom.css`** — the canonical template. Read it once.
+2. **`<SKILL_ROOT>/references/shared/STYLING.md`** — the styling-contract conventions (how to use `@apply`, the `@theme` token utilities, the no-default-Tailwind-colors rule, and the global-vs-scoped CSS ownership boundary).
+3. **`<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md`** — the return JSON shape.
+4. **`src/styles/global.css`** in the project — read to audit for ecom-class leaks (see § "Global-CSS leak audit" below).
+5. **Design tokens (inline in your prompt)** — the parent skill pastes the full `designTokens` JSON into your dispatch prompt. Use it directly; do NOT read `.wix/design-tokens.css` or `.wix/site.d.ts` from disk.
+
+You do NOT need to read `INSTRUCTIONS.md`, `CART_WIRING.md`, the TSX templates, the `discounts.ts` util, or any other reference. Skipping those reads is the point of the split.
+
+## Implementation
+
+### 1. Read the template
+
+```
+<SKILL_ROOT>/templates/ecom/components-ecom.css
+```
+
+This is the canonical scoped CSS for the ecom pack. Adapt sizing/spacing to the brand's aesthetic — use the design tokens from your prompt (`--color-bark`, `--color-cream`, `--spacing-md`, `--font-display`, etc.). **Do not rename the class names or state modifiers** — they must match the contract keys the TSX components reference.
+
+### 2. The two `@reference` directives are mandatory
+
+The first two non-comment lines of `components-ecom.css` MUST be:
+
+```css
+@reference "tailwindcss";
+@reference "./global.css";
+```
+
+Without these, Tailwind v4 fails the build with `"Cannot apply unknown utility class"` on any `@apply` rule that uses a utility like `size-6` or `gap-md`. The template ships them; do not remove.
+
+### 3. Class ownership
+
+Classes defined in `components-ecom.css` (this is the **single source of truth** — the designer's `global.css` does NOT publish these):
+
+- **`.cart-summary` / `.cart-total` / `.cart-empty`** — the `/cart` page summary panel (sticky on desktop), total row, and empty-state. The `.cart-empty .checkout-btn` rule scopes the empty-state CTA to inline-flex with a max-width so it doesn't render full-width.
+- **`.checkout-btn`** — primary checkout button, with `:disabled` and `:hover:not(:disabled)` states. **Composes from `.btn-primary`** (which IS a designer-owned plain-CSS rule in `global.css`). Do **NOT** use `@apply btn-primary` here — Tailwind v4 only `@apply`s utilities declared with `@utility` (which `btn` is in `global.css`), not plain custom classes. The build fails with `Cannot apply unknown utility class 'btn-primary'` if you try. Use `composes` via flat property repetition or extend manually.
+- **`.cart-item-*`** — full row primitives: `cart-item-qty`, `qty-btn`, `qty-value`, `cart-item-unavailable`, `cart-item-actions`, `cart-item-prices`, `cart-item-full-price`, `cart-item-unit-price`, `cart-item-line-total`, `cart-item-remove`, `cart-item-image-link`, `cart-item-name-link`, `cart-item-option`, `cart-item-modifiers`. CartView.tsx references these by name; renaming breaks the page.
+- **`.cart-discount` / `.cart-discount-name` / `.cart-discount-amount`** — the discount row in the summary.
+- **`.cart-applied-discounts` / `.cart-applied-discounts-name`** — the name-only applied-discounts row (line-item automatic discounts).
+- **`.cart-badge` / `.cart-badge-count`** — the nav badge (mounted in `Navigation.astro` via the ecom `pages` scope's CartBadge).
+
+Classes you do NOT own:
+
+- `.btn`, `.btn-primary`, `.btn-secondary` — designer's `global.css` (`.btn` is a Tailwind v4 `@utility`).
+- Anything in `components-stores.css` (option pills, product card, product grid, offer callout) — owned by stores pack.
+- Anything in `components-gift-cards.css` — owned by gift-cards pack.
+
+### 4. Global-CSS leak audit
+
+Before writing your file, **read `src/styles/global.css`** and grep for any class your scope owns. Ecom-specific rules sometimes leak into the designer's foundation:
+
+- Any `.cart-summary`, `.cart-total`, `.cart-empty`, `.checkout-btn` rule.
+- Any `.cart-item-*` rule.
+- Any `.cart-badge` rule.
+- Any `.cart-discount` / `.cart-applied-discounts` rule.
+
+If you find a leak, do NOT edit `global.css` (the designer owns it). Instead:
+
+1. Override the rule with the complete declaration in `components-ecom.css` (later imports win in CSS cascade because Layout.astro imports `components-ecom.css` AFTER `global.css`).
+2. Add `{code: "GLOBAL_CSS_LEAK", class: "<name>", file: "src/styles/global.css"}` to your return JSON's `errors` array — non-fatal but tracked.
+
+### 5. Write the file
+
+Write the adapted CSS to `src/styles/components-ecom.css`. The orchestrator's post-Phase-3 manifest check verifies the file exists.
+
+## Coordination: design tokens
+
+Your parent prompt includes the design tokens JSON inline. Use it directly — do **not** read `.wix/design-tokens.css` or `.wix/site.d.ts` from disk and do not poll for them.
+
+## Return format
+
+```json
+{
+  "status": "complete",
+  "phase": "ecom-components-css",
+  "scope": "components-css",
+  "summary": "Wrote components-ecom.css from template, adapted to brand tokens",
+  "data": {
+    "scopedCssFile": "src/styles/components-ecom.css",
+    "scopedCssRules": 22,
+    "scopedContractClassesDefined": [
+      "cart-summary", "cart-total", "cart-empty", "checkout-btn",
+      "cart-item-qty", "qty-btn", "qty-value", "cart-item-unavailable",
+      "cart-item-actions", "cart-item-prices", "cart-item-full-price",
+      "cart-item-unit-price", "cart-item-line-total", "cart-item-remove",
+      "cart-item-image-link", "cart-item-name-link",
+      "cart-item-option", "cart-item-modifiers",
+      "cart-discount", "cart-discount-name", "cart-discount-amount",
+      "cart-applied-discounts", "cart-applied-discounts-name",
+      "cart-badge", "cart-badge-count"
+    ]
+  },
+  "files": [
+    "src/styles/components-ecom.css"
+  ],
+  "errors": []
+}
+```
+
+If a leak was found and overridden, include `errors: [{code: "GLOBAL_CSS_LEAK", class: "<name>", file: "src/styles/global.css"}]`.
+
+## Anti-patterns
+
+| WRONG | CORRECT |
+|-------|---------|
+| Read `INSTRUCTIONS.md`, `CART_WIRING.md`, or any `.tsx` template | Not needed — this scope only writes CSS |
+| Edit `src/styles/global.css` to fix a leak | Override in `components-ecom.css`; report the leak in `errors` |
+| Use default Tailwind colors (`bg-green-50`, `text-red-600`) | Brand `@theme` utilities (`bg-bark`, `text-cream`) or `var(--color-...)` |
+| `@apply btn-primary` on `.checkout-btn` | Tailwind v4 only `@apply`s `@utility` declarations, not plain CSS rules — build fails. Either repeat the properties manually or compose via `composes` |
+| Rename a class because the brand is "more elegant" with kebab variants | Class names are contract keys; renaming breaks every TSX import that references them |
+| Skip the leak audit | Skipping ships double-defined rules; the audit is < 5 s and prevents downstream visual regressions |
+| Drop the `@reference` directives | Tailwind v4 needs both — without them, `@apply size-6` and similar fail at build |

package/skills/wix-headless/references/ecom/INSTRUCTIONS.md

@@ -0,0 +1,59 @@
+---
+name: ecom-implementer
+description: "Implements vertical-agnostic ecommerce — cart page, checkout redirect, thank-you page, cart badge. Scopes: components, components-css, pages. Extends references/shared/IMPLEMENTER.md."
+---
+
+# Ecom Implementer
+
+Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, MCP prefix, site.json read pattern, return contract, style conventions, and common failure modes.
+
+## Scope routing
+
+| Scope | Phase | Reference |
+|-------|-------|-----------|
+| `components` | Components (CartView, CartBadge — TSX only, **no CSS**) — `src/utils/discounts.ts` is pre-copied by the orchestrator | `./CART_WIRING.md` |
+| `components-css` | Components (scoped CSS — `components-ecom.css` only; runs concurrently with `components`) | `./COMPONENTS_CSS.md` |
+| `pages` | Pages (cart.astro, thank-you.astro, Navigation CartBadge mount) | `./CART_PAGES.md` |
+
+> **Why `components` is split.** A single agent writing the .tsx islands plus the scoped CSS was Phase 3's critical path on the most recent run (204 s for ecom alone). The CSS file has no runtime coupling to the TSX components — it's referenced only by class name at build time — so it splits cleanly into a sibling agent that runs in the same dispatch batch. Mirrors the stores split. See `./COMPONENTS_CSS.md` § "What this scope owns".
+
+Note: `ecom` is never triggered independently — it's co-loaded by verticals that require it (`stores` today; `bookings`, `events` in the future). No `seed` scope — ecom has no data of its own; it works off line items from whichever catalog app is installed.
+
+## Files this vertical creates / contributes
+
+See `<SKILL_ROOT>/references/verticals/ecom.md` frontmatter.
+
+## Templates
+
+Components (`components` scope — TSX only):
+- `<SKILL_ROOT>/templates/ecom/CartView.tsx`
+- `<SKILL_ROOT>/templates/ecom/CartBadge.tsx`
+
+Components CSS (`components-css` scope — scoped CSS only):
+- `<SKILL_ROOT>/templates/ecom/components-ecom.css`
+
+### Pre-copied by the orchestrator (do NOT write this yourself)
+
+- `src/utils/discounts.ts` — pre-copied from `<SKILL_ROOT>/templates/ecom/discounts.ts` BEFORE your `components` scope dispatches. Wix Ecom Discount Rules fetch + per-product match utility; consumers are stores `pages-products` / `pages-home-and-nav` (ProductCard ribbon + product-detail offer callout). Uses `auth.elevate()` from `@wix/essentials` — `discountRules.queryDiscountRules` requires `ECOM.DISCOUNT_RULES_READ`, a visitor client returns empty silently without elevation.
+
+  Just import from this path; never rewrite the file. Regenerating it has shipped a no-op stub that satisfied the manifest but caused the discount ribbon to silently never render. The pre-copy makes that regression structurally impossible.
+
+## CSS ownership — ecom pack
+
+Ecom-specific component CSS lives in `src/styles/components-ecom.css` (written by your `components` scope), NOT in the designer's `global.css`. The classes you own:
+
+- `.cart-summary` — the bordered/sticky summary panel on `/cart`. Compound bordered card; sticky on desktop.
+- `.cart-total` — the row inside the summary that anchors the total amount with a top rule and display-serif typography.
+- `.cart-empty` — the centered empty-state on `/cart` when the cart is empty. Includes the inline override of `.checkout-btn` so the "Browse Products" CTA isn't a full-width brick.
+- `.checkout-btn` — primary checkout button with `:disabled` and `:hover:not(:disabled)` states. Composes from `.btn-primary` (which IS designer-owned in `global.css`).
+- `.cart-item-*` — row, image, name, qty controls — all live here. Most are utility-only; the few that need scoped rules (e.g. line-item separator borders) belong here, not in `global.css`.
+
+The designer's `global.css` declares only tokens, the `.btn` family, decorative slots, the editorial-rule, and the site-shell shells. If `global.css` ships with a partial rule for any class above, that's a designer bug — flag it in your return JSON's `errors` array (`{code: "GLOBAL_CSS_LEAK", class: "<name>"}`) and override with the complete rule in `components-ecom.css`.
+
+See `references/shared/STYLING.md` § "Component-specific CSS is owned by the component, not the designer" for the boundary rule.
+
+## Cross-vertical event contract
+
+`cart-updated` CustomEvent on `window`:
+- **Dispatchers:** `AddToCartButton` (stores), `CartView` (ecom)
+- **Listener:** `CartBadge` (ecom)