@wix/agent-skills 1.13.0 → 1.15.0

package/skills/wix-headless/references/astro/gift-cards/COMPONENTS.md

@@ -1,119 +0,0 @@
-# Phase 3 Components — Gift Cards
-
-This is the **components** portion of the gift-cards **merged build agent** (the build wave). Your agent writes the runtime probe utility, the buy-flow React island, and scoped CSS **first**, then its pages (`/gift-cards` route + Navigation/index patches) — so the island is on disk before the page mounts it. Because the page side patches the shared shells, the whole gift-cards agent runs in the build wave's **serialized shell chain** (`BUILD-astro.md` § "Step 4.5").
-
-## Scope
-
-Files this agent OWNS:
-
-- `src/utils/gift-cards.ts` — runtime probe of the dashboard's eGift Card template + types
-- `src/components/GiftCardPurchase.tsx` — React island; recipient form + variant pills + add-to-cart
-- `src/styles/components-gift-cards.css` — scoped CSS for the form fields, amount pills, hero image frame, and home teaser
-
-Files this agent MUST NOT touch:
-- `src/utils/wix-image.ts`, `src/utils/analytics.ts` — shared utilities. Import from them; do not write copies.
-- `src/components/AddToCartButton.tsx`, `src/components/CartBadge.tsx`, `src/components/CartView.tsx` — owned by stores/ecom; gift-cards uses `currentCart.addToCurrentCart` directly inside the buy-flow island, not via `AddToCartButton`.
-- Any `.astro` page or layout — those are written by other scopes.
-- `src/styles/global.css` — owned by designer foundation.
-
-## Coordination: design tokens
-
-Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave). Reference token CSS variables (`var(--color-cream)`, `1.5rem`, etc.) from `components-gift-cards.css`.
-
-## Critical rules
-
-1. **`httpClient.fetchWithAuth` from `@wix/essentials`** — the JS SDK's gift-vouchers package only exposes redemption methods; the buy-template query is reachable only via REST.
-2. **Module-level memoization** — hold one in-flight `Promise<GiftCardProduct | null>` at module scope so Navigation, home, and `/gift-cards` calls within the same request coalesce. The plugin's `discounts.ts` skips memoization for simplicity but the gift-card template is far more cacheable, so this pack pays the small cost.
-3. **Return `null` on every failure** — non-2xx, empty `giftCardProducts[]`, network/JSON error. The page/nav/teaser callers branch on `null` to hide gracefully. Never throw.
-4. **Hardcoded `WIX_GIFT_CARDS_APP_ID`** — `d80111c5-a0f4-47a8-b63a-65b54d774a27`. Captured from a real Wix-Editor order; not in the public registry. Export it as a named constant with a provenance comment so future maintainers can find the source.
-5. **`wixGiftCardsAppNewCatalog: true`** in the cart `options` is mandatory — without it, the cart line item type is wrong and `ORDER_PAID` won't trigger gift-card issuance.
-6. **No HTML comments in `.astro` frontmatter** — frontmatter is TypeScript; use `//` or `/* */`. (Not relevant to this scope's `.ts`/`.tsx` files but mentioned because gift-cards.ts is imported into `.astro` frontmatter elsewhere.)
-
-## 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 map them differently than the defaults
-
-Do NOT modify logic, imports, or component structure.
-
-## Implementation
-
-### 1. `src/utils/gift-cards.ts`
-
-Use template `templates/gift-cards.ts`.
-
-Exports:
-- `WIX_GIFT_CARDS_APP_ID` — string constant.
-- `GiftCardImage`, `GiftCardPresetVariant`, `GiftCardProduct` — TypeScript interfaces.
-- `getGiftCardProduct(): Promise<GiftCardProduct | null>` — memoized probe. Returns the first gift-card product or null on any failure.
-
-The probe uses `httpClient.fetchWithAuth(ENDPOINT, { method: "POST", body: JSON.stringify({ query: { paging: { limit: 1 } } }) })`.
-
-### 2. `src/components/GiftCardPurchase.tsx`
-
-Use template `templates/GiftCardPurchase.tsx`.
-
-Props: `{ product: GiftCardProduct }`.
-
-State machine: `"idle" | "adding" | "added" | "error"`. Submit handler:
-1. Validate selected `variantId`, `recipientFirstName`, `recipientEmail` (regex).
-2. Call `currentCart.addToCurrentCart` with the catalogReference shape from gift-cards.md ("Wix Gift Card app reference data" section).
-3. Dispatch `cart-updated` CustomEvent (so CartBadge updates).
-4. `trackEvent("AddToCart", { … })` — fire-and-forget; same pattern as stores.
-5. `window.location.href = "/cart"` on success.
-
-Class names from contract:
-- `.gift-card-form`, `.gift-card-fieldset`, `.gift-card-amounts`, `.gift-card-grid`, `.gift-card-field`, `.gift-card-field-wide`, `.gift-card-counter`, `.gift-card-error` — defined in `components-gift-cards.css`.
-- `.option-label`, `.option-pill`, `.option-pill.selected` — shared across packs (also used by stores `ProductPurchase`).
-- `.add-to-cart-btn` — shared with stores AddToCartButton; same brand styling.
-
-### 3. `src/styles/components-gift-cards.css`
-
-Use template `templates/components-gift-cards.css`.
-
-Scoped styles for:
-- Buy-form layout (grid, fields, counter, error message).
-- `/gift-cards` page sections (`.gift-card-page`, `.gift-card-grid-wrap`, `.gift-card-hero-image`, `.gift-card-body`, `.gift-card-lede`, `.gift-card-fineprint`).
-- Home teaser (`.gift-card-teaser`, `.gift-card-teaser-link`, `.gift-card-teaser-image`, `.gift-card-teaser-body`, `.gift-card-teaser-lede`).
-
-The page-section and teaser styles live here (not inside the .astro `<style>` blocks) so the same separation as `components-stores.css` / `components-ecom.css` holds. The pages-scope agent imports this stylesheet via `Layout.astro`'s existing CSS chain (designer foundation already wires up the `components-*.css` import).
-
-Use brand `@theme` utilities (`bg-cream`, `text-ink`, etc.) where natural; fall back to `var(--color-*)` directly (spacing is Tailwind's numeric scale — `gap-4`, `py-24`) when a property isn't covered. Do not introduce new design-token names.
-
-## Return format
-
-```json
-{
-  "status": "complete",
-  "phase": "gift-cards-components",
-  "scope": "components",
-  "summary": "Wrote runtime probe util, GiftCardPurchase island, and scoped gift-cards CSS",
-  "data": {
-    "utils": ["gift-cards.ts"],
-    "islands": ["GiftCardPurchase.tsx"],
-    "scopedCssFile": "src/styles/components-gift-cards.css",
-    "globalContractClassesReferenced": ["addToCartButton"],
-    "scopedContractClassesReferenced": ["optionLabel", "optionPill"]
-  },
-  "files": [
-    "src/utils/gift-cards.ts",
-    "src/components/GiftCardPurchase.tsx",
-    "src/styles/components-gift-cards.css"
-  ],
-  "errors": []
-}
-```
-
-## Anti-patterns
-
-| WRONG | CORRECT |
-|-------|---------|
-| Use `@wix/auto_sdk_ecom_gift-vouchers` to query the buy template | That SDK only exposes redemption — use `httpClient.fetchWithAuth` against the REST endpoint |
-| Wrap `getGiftCardProduct()` in `auth.elevate(...)` | Visitor-scope is correct; elevation breaks the probe |
-| Throw or log+rethrow on probe failure | Return `null`; callers gate the UI on null |
-| Hardcode denomination amounts (€10, €25, etc.) | Always render from `product.presetVariants` |
-| Skip `wixGiftCardsAppNewCatalog: true` in cart options | Required — without it the cart line is the wrong item type and `ORDER_PAID` does not issue a gift card |
-| Write your own `wix-image.ts` / `analytics.ts` | Import from the shared utilities |

package/skills/wix-headless/references/astro/gift-cards/PAGES.md

@@ -1,129 +0,0 @@
-# Phase 4 Pages — Gift Cards
-
-The **pages** portion of the gift-cards **merged build agent** (the build wave) — written *after* its `components`. Writes the `/gift-cards` route and patches `Navigation.astro` + `index.astro` at their declared markers. Because it patches the shared shells, the gift-cards agent runs in the build wave's **serialized shell chain** (one shell-patcher at a time — `BUILD-astro.md` § "Step 4.5"). The components outputs (`src/utils/gift-cards.ts`, `src/components/GiftCardPurchase.tsx`, `src/styles/components-gift-cards.css`) were written earlier in this same agent, so they're already on disk.
-
-## Scope
-
-Files this agent OWNS (writes fresh):
-
-- `src/pages/gift-cards.astro` — landing page; redirects to `/` when probe returns null
-
-Files this agent PATCHES (insert at marker, preserve everything else):
-
-- `src/components/Navigation.astro` — insert "Gift Cards" link at `<!-- nav:links -->`
-- `src/pages/index.astro` — insert home teaser at `<!-- home:gift-cards -->`
-
-Files this agent MUST NOT touch:
-- `src/utils/gift-cards.ts`, `src/components/GiftCardPurchase.tsx`, `src/styles/components-gift-cards.css` — Components scope.
-- Any other vertical's nav/home contributions.
-- `Layout.astro`, `global.css`, or any product/cart/checkout page.
-
-## Critical rules
-
-1. **Marker-based patching.** Read the shell file, locate the exact marker comment string (`<!-- nav:links -->` or `<!-- home:gift-cards -->`), insert your snippet immediately AFTER the marker line, preserve the marker line itself. See `references/shared/IMPLEMENTER.md` § "Contributing to shared files via markers".
-2. **Inject the import + frontmatter call when patching.** When inserting at `<!-- nav:links -->` in `Navigation.astro`, also add `import { getGiftCardProduct } from "../utils/gift-cards";` and `const giftCardsEnabled = (await getGiftCardProduct()) !== null;` to the file's frontmatter (top of the file). Same for `index.astro`'s home teaser. Do NOT assume another vertical added them.
-3. **SSR error guards.** Wrap `getGiftCardProduct()` calls in try/catch with safe fallback (`giftCardsEnabled = false` / `giftCardProduct = null`). See `references/shared/IMPLEMENTER.md` § "SSR error guards". Although the helper itself never throws, the guard cost is zero and protects against future regressions.
-4. **Redirect rather than render** when the page-level probe returns null. `if (!product) return Astro.redirect("/", 302);` — same pattern as private/disabled-feature routes elsewhere.
-5. **Memoization is per-request.** Navigation, home, and the page may all call `getGiftCardProduct()` on the same request — the helper coalesces them into one fetch. You do not need to thread the result through Astro context.
-6. **No HTML comments in `.astro` frontmatter** — frontmatter is TypeScript; use `//` or `/* */`.
-7. **Image rendering uses `resolveWixImageUrl`** — the gift-card product's `image` field is a Wix media object identical in shape to product/blog images. Import from `../utils/wix-image`.
-
-## Template files
-
-Snippets to insert at markers live as standalone template fragments. Read each, substitute any contract-class adaptations, paste at the marker.
-
-- `templates/gift-cards.astro` — full landing page
-- `templates/_nav-snippet.astro` — single line for `Navigation.astro` (the `{giftCardsEnabled && <a>...</a>}` expression)
-- `templates/_home-teaser-snippet.astro` — multi-line block for `index.astro` (the `{giftCardProduct && <section>...</section>}` block)
-
-## Implementation
-
-### 1. `src/pages/gift-cards.astro`
-
-Use template `templates/gift-cards.astro`.
-
-Frontmatter:
-```astro
----
-import Layout from "../layouts/Layout.astro";
-import GiftCardPurchase from "../components/GiftCardPurchase.tsx";
-import { getGiftCardProduct } from "../utils/gift-cards";
-import { resolveWixImageUrl } from "../utils/wix-image";
-
-const product = await getGiftCardProduct();
-if (!product) return Astro.redirect("/", 302);
-
-const heroImage = resolveWixImageUrl(product.image, 800, 800);
----
-```
-
-Body: hero image + name + description + `<GiftCardPurchase client:load product={product} />` + fineprint paragraph. All page-level CSS is already shipped via `components-gift-cards.css` (Components scope) — do not duplicate styles inside the `.astro` file's `<style>` block.
-
-### 2. Patch `src/components/Navigation.astro`
-
-1. Read the file.
-2. Add to frontmatter (above the `---` close): `import { getGiftCardProduct } from "../utils/gift-cards"; const giftCardsEnabled = (await getGiftCardProduct()) !== null;` (split across two lines as needed).
-3. Locate the line containing `<!-- nav:links -->`. Insert immediately after it:
-   ```astro
-   {giftCardsEnabled && <a href="/gift-cards">Gift Cards</a>}
-   ```
-4. If other verticals (stores, blog, forms) already inserted at the same marker, preserve every existing line — your snippet appends.
-
-### 3. Patch `src/pages/index.astro`
-
-1. Read the file.
-2. Add to frontmatter:
-   ```astro
-   import { getGiftCardProduct } from "../utils/gift-cards";
-   import { resolveWixImageUrl } from "../utils/wix-image";
-
-   const giftCardProduct = await getGiftCardProduct();
-   const giftCardImage = giftCardProduct
-     ? resolveWixImageUrl(giftCardProduct.image, 800, 600)
-     : null;
-   ```
-   (`resolveWixImageUrl` import may already be present from the stores patcher — if so, do not re-import.)
-3. Locate the line containing `<!-- home:gift-cards -->`. Insert the teaser snippet immediately after it (see `templates/_home-teaser-snippet.astro`).
-
-## Verification
-
-After writing/patching, grep the project to confirm:
-- `Navigation.astro` contains both the marker and the new link expression.
-- `index.astro` contains both the marker and the new `<section class="gift-card-teaser">` block.
-- `/gift-cards.astro` exists and references `GiftCardPurchase` (Components scope's island).
-
-## Return format
-
-```json
-{
-  "status": "complete",
-  "phase": "gift-cards-pages",
-  "scope": "pages",
-  "summary": "Wrote /gift-cards page; patched Navigation + home with conditional gift-card surfaces",
-  "data": {
-    "pageWritten": true,
-    "navigationPatched": true,
-    "homePatched": true,
-    "markersFound": ["<!-- nav:links -->", "<!-- home:gift-cards -->"]
-  },
-  "files": [
-    "src/pages/gift-cards.astro",
-    "src/components/Navigation.astro",
-    "src/pages/index.astro"
-  ],
-  "errors": []
-}
-```
-
-If a marker is missing, return `status: "partial"` with `errors: [{ code: "MARKER_NOT_FOUND", file: "<path>", marker: "<marker>" }]`. Do NOT invent your own insertion point — that signals the designer foundation didn't scaffold the shell correctly and should be fixed upstream.
-
-## Anti-patterns
-
-| WRONG | CORRECT |
-|-------|---------|
-| Render the page when probe returns null | `Astro.redirect("/", 302)` |
-| Skip the import-injection step (assume another vertical added `getGiftCardProduct`) | Always inject the import + the `await` call when patching, scoped to the file you're touching |
-| Replace the marker comment with the inserted snippet | Insert AFTER the marker; preserve the marker line |
-| Move CSS into `<style>` blocks inside `.astro` files | Page/teaser CSS lives in `components-gift-cards.css` (Components scope) |
-| Hardcode `<title>"Gift Cards"</title>` | Use `title={\`${product.name}\`}` so the dashboard owner controls naming |
-| Conditionally re-render the page when the app is enabled later | The Astro page is server-rendered each request — the probe runs every time, so dashboard changes are picked up without rebuild |

package/skills/wix-headless/references/astro/stores/BACK_IN_STOCK.md

@@ -1,178 +0,0 @@
-# Phase 3 Components — Back in Stock (Stores)
-
-The stores `components` scope writes the TSX/util files; the CSS rules ship in the **pre-copied** `components-stores.css` template (no agent authors them). The matching page wiring lives in `PRODUCT_PAGES.md` (SSR probe import + new props on `<ProductPurchase>`). Both the components and that page wiring run inside the **same stores merged build agent** (the build wave), components first.
-
-## Scope
-
-Files written for back-in-stock, by scope:
-
-**`components` scope** (see `./SHARED_WIRING.md`):
-- `src/components/BackInStockForm.tsx` — React island that posts via `@wix/ecom`'s `backInStockNotifications.createBackInStockNotificationRequest`
-
-**Pre-copied by the orchestrator** (do NOT author — same treatment as `categories.ts`):
-- `src/utils/back-in-stock.ts` — SSR-elevated probe of the Wix back-in-stock service, plus the canonical Stores app id constant. Pre-copied into the project in the build-wave pre-batch (BUILD-astro.md § "Step 4.5"). **Import** `getBackInStockEnabled`/the app-id constants from `../utils/back-in-stock`; never `Write` it yourself (racing the pre-copy trips the harness staleness guard).
-
-**`components-css` scope** (see `./COMPONENTS_CSS.md`):
-- `src/styles/components-stores.css` — appends the back-in-stock form CSS rules at the end of the file (see § 3 below)
-
-This file is read by both scopes. Sections covering the SDK / probe / form island are for the `components` scope; § 3 (CSS append) is for the `components-css` scope.
-
-## Critical rules
-
-These come from live trials on Catalog-V3 sites. Encode them verbatim — none of them are in the public docs.
-
-1. **Two app ids — pick the right one.**
-   - The Wix Stores **install** app id is `215238eb-22a5-4c36-9e7b-e7c08025e04e` (used in `catalogReference.appId` for cart adds, app install, `Phase 1`).
-   - The Wix Stores **back-in-stock** app id is `1380b703-ce81-ff05-f115-39571d94dfcd` (the Stores sub-page registration id).
-   - The back-in-stock service rejects `215238eb-…` (`428 NOT_SUPPORTED_APP_DEF_ID` on `start-collecting`, `428 REQUEST_COLLECTION_DISABLED` on the create endpoint) and accepts `1380b703-…`. Both are correct in their own contexts; do not unify them.
-
-2. **Bare-fields rule for the SDK subscribe call.** `backInStockNotifications.createBackInStockNotificationRequest(request, itemDetails)` throws an opaque `TypeError: Failed to construct 'URL': Invalid URL` when the optional `request.itemUrl` or `itemDetails.image` fields are present, even with browser-valid URLs. Send only the four required fields: `catalogReference`, `email`, `name`, `price`. The notification email and the dashboard view both work without them.
-
-3. **Numeric price only.** `itemDetails.price` must be a numeric string (e.g. `"385"`). Currency-formatted strings (`"$385"`) fail with `400 DECIMAL_GTE`. The `normalizePrice` helper in the form template strips `$`/`,` and falls back to `"0"`.
-
-4. **Visitor scope from the client; SSR-only elevation for the probe.**
-   - The form's subscribe call uses `@wix/ecom` straight from the React island — no `auth.elevate`, no Astro API route. The visitor token is enough.
-   - The settings probe uses `auth.elevate(httpClient.fetchWithAuth)` because `getSettings` requires Manage Stores. Run it in `[slug].astro` frontmatter, **never from the client**.
-   - Do NOT invent an Astro `src/pages/api/...` POST route. The `@wix/cloud-provider-fetch-adapter` that ships with the scaffold returned 403 to the browser on app-defined POST routes during the trial. Stay on the SDK.
-
-5. **Module-memoize the probe.** `getBackInStockEnabled()` holds one in-flight `Promise<boolean>` at module scope so multiple SSR awaits in the same request coalesce. Same pattern as `gift-cards.ts`'s `getGiftCardProduct()`.
-
-## Template files
-
-This scope uses **template files** instead of inline code. For each file below:
-
-1. Read the template from `<Agent location>/templates/<path>`
-2. Write it to the project at the target path
-3. Adapt CSS class names if the design tokens map them differently
-
-Do NOT modify logic, imports, the bare-fields request shape, or the app-id constants.
-
-### 1. `src/utils/back-in-stock.ts` — pre-copied, not owned by this scope
-
-> Pre-copied by the orchestrator in the build-wave pre-batch (BUILD-astro.md § "Step 4.5") — same treatment as `categories.ts`. **Import** from `../utils/back-in-stock`; do NOT write it yourself. The exports below are documented here so callers (the form island, the `[slug].astro` probe) know the surface.
-
-Exports:
-- `WIX_STORES_BACK_IN_STOCK_APP_ID` — string constant. Use this for the `catalogReference.appId` in the form.
-- `WIX_STORES_INSTALL_APP_ID` — string constant. Exported for completeness; unused by this file.
-- `getBackInStockEnabled(): Promise<boolean>` — memoized SSR probe.
-- `SETTINGS_URL` — the `getSettings` REST URL, exported in case future scopes need it.
-
-The probe header comment block documents the app-id discrepancy in detail. Keep that block intact when copying — it's the only place the next maintainer will see the rationale.
-
-### 2. `src/components/BackInStockForm.tsx`
-
-Use template `templates/BackInStockForm.tsx`.
-
-Props: `{ productId, variantId?, productName, productPrice: number | string, variantLabel? }`. The form accepts price as either a number or a numeric string and normalizes internally.
-
-State machine: `idle → submitting → (success | error)` with `success` carrying an optional `alreadySubscribed` flag for the duplicate-detection branch (`BACK_IN_STOCK_NOTIFICATION_REQUEST_ALREADY_EXISTS` → "You're already on the list").
-
-Class names:
-- `.back-in-stock-form`, `.back-in-stock-headline`, `.back-in-stock-eyebrow`, `.back-in-stock-lede`, `.back-in-stock-label`, `.back-in-stock-row`, `.back-in-stock-input`, `.back-in-stock-submit`, `.back-in-stock-error`, `.back-in-stock-success`, `.back-in-stock-success-headline`, `.back-in-stock-success-detail` — defined in the CSS append below.
-
-### 3. `src/styles/components-stores.css` — append
-
-The `components-stores.css` template already covers options/quantity/modifiers/stock-status. Append the back-in-stock rules at the end. Use the existing pack token vocabulary (`bark`, `cream`, `parchment`, `ink`, `rule`) so the styling lands on every brand without per-site rewrites.
-
-```css
-/* --- Back-in-stock subscribe form (BackInStockForm.tsx) --- */
-.back-in-stock-form {
-  @apply flex flex-col gap-4 mt-4 p-6 border border-rule rounded;
-  background-color: var(--color-cream);
-}
-.back-in-stock-headline {
-  @apply flex flex-col gap-3;
-}
-.back-in-stock-eyebrow {
-  @apply font-heading text-xs uppercase tracking-wider text-bark/70;
-}
-.back-in-stock-lede {
-  @apply font-body text-sm text-ink;
-  line-height: 1.5;
-}
-.back-in-stock-label {
-  @apply font-heading text-xs uppercase tracking-wider text-bark/70;
-}
-.back-in-stock-row {
-  @apply flex flex-row flex-wrap gap-3;
-}
-.back-in-stock-input {
-  @apply flex-1 px-4 py-3 font-body text-sm border border-rule rounded bg-parchment text-ink;
-  min-width: 0;
-  transition: border-color 0.15s ease;
-}
-.back-in-stock-input:focus {
-  @apply outline-none border-ink;
-}
-.back-in-stock-input[aria-invalid="true"] {
-  @apply border-rust;
-}
-.back-in-stock-submit {
-  @apply px-6 py-3 font-heading text-xs uppercase tracking-wider bg-bark text-cream rounded cursor-pointer transition-colors;
-  border: 1px solid var(--color-bark);
-}
-.back-in-stock-submit:hover:not(:disabled) {
-  @apply bg-ink;
-}
-.back-in-stock-submit:disabled {
-  @apply opacity-50 cursor-not-allowed;
-}
-.back-in-stock-error {
-  @apply font-body text-sm text-rust;
-}
-.back-in-stock-success {
-  @apply mt-4 p-6 border border-rule rounded;
-  background-color: var(--color-cream);
-}
-.back-in-stock-success-headline {
-  @apply font-heading text-base text-ink;
-  margin: 0 0 0.5rem 0;
-}
-.back-in-stock-success-detail {
-  @apply font-body text-sm text-ink;
-  line-height: 1.55;
-  margin: 0;
-}
-.stock-status.back-in-stock-alt {
-  @apply mt-3 font-body text-sm italic text-bark/70;
-}
-```
-
-If the brand's design tokens don't include a `rust` (error) color, fall back to a neutral `text-ink` on the error state — the `aria-invalid` border still flags it visually.
-
-## Return format
-
-The full components scope return must mention back-in-stock:
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-components",
-  "scope": "components",
-  "summary": "Wrote stores islands, scoped CSS, back-in-stock probe + form",
-  "data": {
-    "islands": ["ProductPurchase.tsx", "AddToCartButton.tsx", "BackInStockForm.tsx"],
-    "scopedCssFile": "src/styles/components-stores.css",
-    "backInStockWired": true
-  },
-  "files": [
-    "src/components/SeoTags.astro",
-    "src/components/AddToCartButton.tsx",
-    "src/components/ProductPurchase.tsx",
-    "src/components/BackInStockForm.tsx",
-    "src/styles/components-stores.css"
-  ],
-  "errors": []
-}
-```
-
-## Anti-patterns
-
-| WRONG | CORRECT |
-|---|---|
-| Use `215238eb-…` (Stores install id) as `catalogReference.appId` for back-in-stock | Use `WIX_STORES_BACK_IN_STOCK_APP_ID` (`1380b703-…`); the install id is rejected on V3 |
-| Pass `itemUrl` or `image` to `createBackInStockNotificationRequest` | Send only `catalogReference`, `email`, `name`, numeric `price` — the SDK throws `Failed to construct 'URL': Invalid URL` on either optional field |
-| Send `"$385"` as `price` | Numeric string `"385"` only; the API rejects formatted prices with `400 DECIMAL_GTE` |
-| Wrap the subscribe call in `auth.elevate(...)` from the React island | Visitor scope is enough; elevation belongs only to the SSR probe |
-| Add a custom `src/pages/api/back-in-stock-subscribe.ts` route | Not needed — SDK from the island works. The Wix cloud adapter returned 403 on app-defined POST routes during the trial. |
-| Drop the module-memoization in `back-in-stock.ts` | Keep it; multiple SSR awaits in the same request coalesce into one `getSettings` call |

package/skills/wix-headless/references/astro/stores/CATEGORY_PAGES.md

@@ -1,85 +0,0 @@
-# Phase 4 Category Pages — Stores
-
-Scope: `pages-categories` — written by the stores **merged build agent** (the build wave) *before* its `pages-products` scope, so `<CategoryRail/>` is on disk before that scope mounts it. This scope writes the dedicated category landing route and the shared `<CategoryRail/>`. The `categories.ts` helper is **pre-copied by the orchestrator in the build-wave pre-batch** (BUILD-astro.md § "Step 4.5") — do NOT write it here.
-
-**Within-agent order:** the merged stores agent writes `components` → `pages-categories` (this scope) → `pages-products`. `pages-home-and-nav` is a *separate* serialized agent (it patches the shared shells) and resolves `<CategoryRail/>` at build time (Step 8). Each scope only needs its own declared files to exist by the time `astro build` runs.
-
-## Scope
-
-Files this agent OWNS (writes):
-
-- `src/pages/category/[slug].astro` — category landing (server-side filtered, cursor-paginated)
-- `src/components/CategoryRail.astro` — shared rail + Prev/Next pagination, persisted across `<ClientRouter />` swaps
-
-Files this agent imports but MUST NOT write:
-- `src/utils/categories.ts` — TTL-cached helpers (`listStoreCategories`, `getCategoryBySlug`, `listProductsInCategory`). **Pre-copied by the orchestrator** before this phase (it's a static, brand-agnostic SDK wrapper); import the helpers, never author the file. Writing it races `pages-products`/`pages-home-and-nav`, which import the same path.
-
-Files this agent MUST NOT touch:
-- `src/pages/products/index.astro`, `[slug].astro`, `src/components/ProductCard.astro` — owned by `pages-products`
-- `src/pages/index.astro`, `src/components/Navigation.astro` — owned by `pages-home-and-nav`
-- `src/layouts/Layout.astro`, `global.css` — owned by designer (View Transitions + loading bar live there)
-- `src/components/ProductPurchase.tsx`, `AddToCartButton.tsx`, `BackInStockForm.tsx` — owned by `components`
-
-## Inputs (from parent prompt)
-
-- **Phase 1 return data** — `categories: []`. Phase 1 does not seed categories (they're merchant-driven). This scope still writes the helper + rail + route — they're harmless when no categories exist, and they light up automatically once the merchant creates visible categories with items in the dashboard. `listStoreCategories()` queries the API live at SSR time (5-min TTL cache), so no redeploy is needed when categories are added later.
-- **Design tokens** — read the design tokens (the DESIGN.md vocabulary) from `.wix/design-tokens.css` (on disk). Page header / breadcrumbs / pill / pagination styling should follow `references/shared/STYLING.md` (utilities derived from tokens, semantic classes only for primitives).
-- **Designer output summary** — confirm `Layout.astro` already includes `<ClientRouter />`, `transition:persist` markers on nav/footer, and the `[data-nav-progress]` element + after-swap hook. If any of those is missing, return `status: "partial"` with `errors: [{ code: "DESIGNER_LAYOUT_MISSING_TRANSITIONS", path: "src/layouts/Layout.astro" }]`.
-
-## Critical rules (all must be honored)
-
-1. **Server-side filter only.** Do NOT ship a client-side filter that hides cards via `card.hidden = true` or `data-category-ids`. That pattern doesn't scale past a few hundred products and breaks SEO. Filtering is by URL: `/category/<slug>` is the canonical filter, server-renders only matching products. The rail click is a real navigation that `<ClientRouter />` swaps in place.
-2. **Use `@wix/auto_sdk_categories_categories`**, not `@wix/categories` (the published name) — the auto_sdk package is already on disk via every other `@wix/*` package's transitive deps. Importing `@wix/categories` triggers a fresh `npm install`. The provided template uses `import * as categories from "@wix/auto_sdk_categories_categories"` already; do not rewrite.
-3. **`queryCategories(...)` rejects empty filters.** The SDK builder's `.find()` validates that at least one predicate has been chained. Always include `.eq("visible", true)` (the constraint we want anyway). Provided template already does this.
-4. **Filter out the auto-managed "All Products" category** by `handle === "online_stores_all_products"`. It's installed by Wix Stores automatically and contains every product; surfacing it in the rail makes the All pill duplicate.
-5. **Filter out empty categories** by `itemCounter === 0` so the rail doesn't show buckets that 404 in practice (the route still works, but the pill leads to "Nothing in <name> just now").
-6. **`STORES_APP_ID` lives in the pre-copied `categories.ts`** — the template already sets it to the Stores app id `215238eb-22a5-4c36-9e7b-e7c08025e04e` (same id used for cart ops and Phase 1 product seed; NOT the back-in-stock id `1380b703-…`). You do not write that file; this is documented so the helpers you import behave as expected.
-7. **Cursor pagination** uses `productsV3.queryProducts().limit(24).skipTo(cursor)`. Cursor lives in `?cursor=…` on the URL, surfaced from `result.cursors.next` / `result.cursors.prev`. Prev/Next links use `data-astro-prefetch="hover"` so hovering them warms the cache.
-8. **Module-level TTL cache (5 min)** in `categories.ts` is opportunistic; safe under the Cloudflare-style fetch adapter (each worker isolate is single-tenant). Errors don't poison the cache.
-9. **Two-call pipeline** in `listProductsInCategory`: first `listItemsInCategory(categoryId, { appNamespace: "@wix/stores" })` for IDs, then `productsV3.queryProducts().in("_id", ids).limit(24).skipTo(cursor).find()`. There is no Wix endpoint that does category filter + cursor paging in one shot — don't attempt `listCategoriesForItems` from the SDK; it ships items via GET querystring and breaks on arrays. If you need product → categories mapping (e.g. for breadcrumbs on product detail), call the REST POST endpoint directly: `POST /categories/v1/categories/list-categories-for-items`.
-
-## Writing the templates
-
-Read each template at `references/astro/templates/stores/` and write it verbatim to the corresponding `src/` path, with three small adjustments. (`categories.ts` is **not** in this list — the orchestrator pre-copies it; you only import its helpers.)
-
-| Template path | Site path |
-|---|---|
-| `templates/CategoryRail.astro` | `src/components/CategoryRail.astro` |
-| `templates/category/[slug].astro` | `src/pages/category/[slug].astro` |
-
-Adjustments at the call site:
-
-1. The category page header copy ("Shop", breadcrumbs, lede) should adapt to brand tone. The template ships generic ("Browse our X collection"); rewrite the breadcrumb middle anchor and the empty-state line to match the rest of the site's voice. Keep semantics — same elements, same classes, same `data-*` markers.
-2. If the brand uses an editorial eyebrow pattern on `/products` (e.g. "Issue No. 01 · The Collection"), mirror it on `/category/[slug]` (e.g. "Category · Lounge Chairs"). Otherwise omit.
-3. Page-header CSS class names (`page-header`, `page-header-title`, `page-header-lede`, `breadcrumbs`, `page-header-image`) must match what the designer published. If the designer used different names, rename inside the template — do NOT introduce new ones.
-
-## Pre-return file-existence assertion
-
-Before returning `status: "complete"`, verify the two files you write exist:
-
-- `src/components/CategoryRail.astro`
-- `src/pages/category/[slug].astro`
-
-If either is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]`. The orchestrator's manifest check will also catch this, but an agent-side assertion gives a faster and more precise failure. Also confirm the pre-copied `src/utils/categories.ts` is on disk (you import it); if it's missing, that's an orchestrator-side bug — return `status: "partial"` with `errors: [{ code: "UTILITY_TEMPLATE_NOT_PRECOPIED", path: "src/utils/categories.ts" }]` and do NOT write your own.
-
-## Return contract
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-pages",
-  "scope": "pages-categories",
-  "summary": "Wrote shared CategoryRail + /category/[slug] route (imports the pre-copied categories helper); route renders M categories.",
-  "data": {
-    "categoriesRendered": 0,
-    "filesWritten": [
-      "src/components/CategoryRail.astro",
-      "src/pages/category/[slug].astro"
-    ]
-  },
-  "files": [],
-  "errors": []
-}
-```
-
-Phase 1 always reports zero categories (it does not seed them). Set `categoriesRendered: 0` and return `status: "complete"` — the helper, rail, and route are still written so the storefront lights up automatically the first time the merchant creates a visible category with items in the dashboard, with no code change needed.

package/skills/wix-headless/references/astro/stores/COMPONENTS_CSS.md

@@ -1,129 +0,0 @@
-# Phase 3 Components-CSS — Stores
-
-**This stylesheet is pre-copied from the skill template by the orchestrator** (build-wave pre-batch, BUILD-astro.md § "Step 4.5") — there is no `components-css` subagent to dispatch. This file documents the CSS for reference so the stores `components` scope (in the merged build agent) knows the class-name surface it targets.
-
-## What this scope owns
-
-Exactly one file:
-
-- `src/styles/components-stores.css` — scoped CSS for stores-specific contract keys (option pills, quantity stepper, stock status, modifier free-text input, product card, product grid, offer callout panel). 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 (`./SHARED_WIRING.md`).
-- `src/styles/global.css` — owned by the designer foundation. **You read it (to audit for stores-class leaks) but never write it.**
-- `src/styles/components-ecom.css`, `src/styles/components-gift-cards.css` — owned by other packs' `components` (or `components-css`) scopes.
-- `src/utils/back-in-stock.ts` — pre-copied by the orchestrator before this dispatch; not your concern.
-
-## Reading set
-
-You only need:
-
-1. **`<SKILL_ROOT>/references/astro/templates/stores/components-stores.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 stores-class leaks (see § "Global-CSS leak audit" below).
-5. **Design tokens (on disk)** — read the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`rounded`/`containers`; spacing is Tailwind's numeric scale, not a token) from `.wix/design-tokens.css` (gate-verified present before the wave). They are NOT inlined in your prompt.
-
-You do NOT need to read `INSTRUCTIONS.md`, `SHARED_WIRING.md`, `BACK_IN_STOCK.md`, the TSX templates, the back-in-stock util, or any other reference. Skipping those reads is the point of the split — they would consume tokens for context this scope doesn't use.
-
-## Implementation
-
-### 1. Read the template
-
-```
-<SKILL_ROOT>/references/astro/templates/stores/components-stores.css
-```
-
-This is the canonical scoped CSS for the stores pack. Adapt sizing/spacing to the brand's aesthetic — use the design tokens from your prompt (`--color-bark`, `--color-cream`, `--radius-md`, `--font-display`, etc.); spacing uses Tailwind's numeric scale (`gap-4`, `py-24`), not a token. **Do not rename the class names or state modifiers** — they must match the contract keys the TSX components reference.
-
-### 2. Use `@apply` with brand `@theme` utilities
-
-The `@theme` block in `global.css` (written by the designer foundation) exposes the brand tokens as Tailwind utilities (e.g., `bg-bark`, `text-cream`, `font-body`). They are globally available because `global.css` is imported first in `Layout.astro`.
-
-Use `@apply` for color, font, and spacing properties. Drop to `var(--color-bark)` directly when `@apply` doesn't cover a property (e.g., border-color via custom property).
-
-Do **NOT** use default Tailwind colors (`bg-green-50`, `text-red-600`). The brand palette is the only allowed source.
-
-### 3. Class ownership
-
-Classes you own (define rules in `components-stores.css`):
-
-- **`.product-card`, `.product-card-media`, `.product-card-ribbon`, `.product-card-index`** — the product card itself, including the `overflow: hidden` + `border-radius` clipping context. Whoever writes the `border-radius` here also writes any inner padding required to keep child content inside the rounded edges. Without inner padding, a price `<p>` sits flush against the rounded bottom corner and descenders get clipped. Add `padding-bottom: 1rem` on the card plus horizontal padding on each text block when you set the radius.
-- **`.product-grid`** — the layout that lists product cards. Both `/products` (pages-products scope) and `/category/[slug]` (pages-categories scope) consume it from one place. Include `display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 2rem;` plus the View-Transitions opacity fade for in-flight navigations.
-- **`.offer-callout` family (`.offer-callout`, `-item`, `-badge`, `-name`, `-detail`, `-foot`)** — discount panel rendered above `<ProductPurchase>` on `/products/[slug]`.
-- **Option-selector contract classes** — `option-group`, `option-label`, `option-choices`, `option-pill` (with `.selected` state modifier).
-- **Quantity-stepper contract classes** — `quantity-selector`, `quantity-btn`, `quantity-value`.
-- **Stock status** — `stock-status`.
-- **Back-in-stock form** (`.back-in-stock-form` and child classes) — append the rules from `./BACK_IN_STOCK.md` § 3 to the end of `components-stores.css`. The TSX form island is written by the `components` sibling; this file owns its styling.
-
-Classes you do NOT own:
-
-- `.btn`, `.btn-primary`, `.btn-secondary` — designer's `global.css`.
-- `addToCartButton` → `.add-to-cart-btn` — designer's `global.css` (it's a global contract key).
-- `productPurchase` → `.product-purchase` outer wrapper — designer's `global.css`.
-- Anything in `components-ecom.css` (CartBadge, CartView, CartLine) — owned by ecom pack.
-
-The boundary: **rules referenced by exactly one pack's TSX live in that pack's scoped CSS; rules referenced by every page (buttons, links, type) live in the designer's `global.css`.**
-
-### 4. Global-CSS leak audit
-
-Before writing your file, **read `src/styles/global.css`** and grep for any class your scope owns. Stores-specific rules sometimes leak into the designer's foundation:
-
-- `.product-grid` and `body[data-navigating="true"] .product-grid` — designer drift; should be in `components-stores.css`, not `global.css`.
-- Any `.product-card-*` rule.
-- Any `.offer-callout-*` rule.
-- Any contract class that maps to a key in `contractKeys.scoped.stores`.
-
-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-stores.css` (later imports win in CSS cascade because Layout.astro imports `components-stores.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-stores.css`. The first line must be `@reference "./global.css";` so Tailwind's `@apply` resolves the `@theme` utilities. The orchestrator's post-Phase-3 manifest check verifies the file exists; it does not verify the `@reference` line.
-
-## Coordination: design tokens
-
-Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave) — they are NOT inlined in your prompt.
-
-## Return format
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-components-css",
-  "scope": "components-css",
-  "summary": "Wrote components-stores.css from template, adapted to brand tokens",
-  "data": {
-    "scopedCssFile": "src/styles/components-stores.css",
-    "scopedCssRules": 18,
-    "scopedContractClassesDefined": [
-      "option-group", "option-label", "option-choices", "option-pill",
-      "quantity-selector", "quantity-btn", "quantity-value",
-      "stock-status",
-      "product-card", "product-card-media", "product-card-ribbon", "product-card-index",
-      "product-grid",
-      "offer-callout", "offer-callout-item", "offer-callout-badge", "offer-callout-name", "offer-callout-detail", "offer-callout-foot"
-    ]
-  },
-  "files": [
-    "src/styles/components-stores.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`, `SHARED_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-stores.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-...)` |
-| Write rules for `.add-to-cart-btn` here | That's a global contract class — owned by the designer's `global.css` |
-| Rename a class because the brand is "more elegant" with kebab-cased 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 |