@wix/agent-skills 1.0.0

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

@@ -0,0 +1,96 @@
+---
+name: stores-implementer
+description: "Implements Wix Stores vertical — product catalog, categories, add-to-cart, product pages. Scopes: seed, components, components-css, pages-products, pages-categories, pages-home-and-nav. Extends references/shared/IMPLEMENTER.md."
+---
+
+# Stores 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 |
+|-------|-------|-----------|
+| `seed` | Seed (MCP catalog setup — products only; categories are merchant-driven, not seeded) | `./PRODUCT_CATALOG_DATA.md` |
+| `components` | Components (React islands + SeoTags + back-in-stock util — TSX/Astro only, **no CSS**) | `./SHARED_WIRING.md` |
+| `components-css` | Components (scoped CSS — `components-stores.css` only; runs concurrently with `components`) | `./COMPONENTS_CSS.md` |
+| `pages-categories` | Pages (`/category/[slug]` listing + shared CategoryRail + `utils/categories.ts`) | `./CATEGORY_PAGES.md` |
+| `pages-products` | Pages (products listing + detail + ProductCard; mounts the rail written by `pages-categories`) | `./PRODUCT_PAGES.md` |
+| `pages-home-and-nav` | Pages (home-page contribution + Shop submenu in Navigation) | `./HOME_AND_NAV.md` |
+
+> **Why `components` is split.** A single agent writing five .tsx/.astro files plus the scoped CSS dominated Phase 3 wall time (228 s on a 3-product run, 320 s on an 8-product run). 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. Each scope gets a smaller reading set and a smaller write list. See `./COMPONENTS_CSS.md` § "What this scope owns".
+
+## Files this vertical creates / contributes
+
+See `<SKILL_ROOT>/references/verticals/stores.md` frontmatter (`creates:` and `contributes:` blocks).
+
+## Pre-return file-existence assertion (all page scopes)
+
+Before returning `status: "complete"` from any `pages-*` scope, verify every file listed in your scope's `files:` block (see verticals/stores.md) exists on disk. Silently dropping a file (e.g. `[slug].astro` from `pages-products`) reports `complete` to the orchestrator, but every product link 404s at runtime.
+
+If a declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]` rather than claiming success. The orchestrator's Step 8.0.5 manifest check will also catch this, but an agent-side assertion gives a faster and more precise failure.
+
+## Templates
+
+Canonical templates live at `<SKILL_ROOT>/templates/stores/`. Your `components` and `pages-*` scopes read these and adapt them — don't invent markup or logic.
+
+Components (`components` scope — TSX/Astro only):
+- `<SKILL_ROOT>/templates/stores/AddToCartButton.tsx`
+- `<SKILL_ROOT>/templates/stores/ProductPurchase.tsx`
+- `<SKILL_ROOT>/templates/stores/BackInStockForm.tsx`
+- `<SKILL_ROOT>/templates/stores/SeoTags.astro`
+
+Components CSS (`components-css` scope — scoped CSS only):
+- `<SKILL_ROOT>/templates/stores/components-stores.css`
+
+Pages (`pages-products` scope):
+- `<SKILL_ROOT>/templates/stores/ProductCard.astro`
+- `<SKILL_ROOT>/templates/stores/products/index.astro`
+- `<SKILL_ROOT>/templates/stores/products/[slug].astro`
+
+Pages (`pages-categories` scope):
+- `<SKILL_ROOT>/templates/stores/CategoryRail.astro`
+- `<SKILL_ROOT>/templates/stores/category/[slug].astro`
+
+### Pre-copied by the orchestrator (do NOT write these yourself)
+
+The following utility files are deterministically copied by the orchestrator BEFORE your phase dispatches (`components` for the first, `pages` for the second). They are mechanical SDK wrappers with no brand-specific content; reading or rewriting them as part of your scope wastes tokens and risks drift. Just import the helpers at the listed paths:
+
+- `src/utils/back-in-stock.ts` — pre-copied from `<SKILL_ROOT>/templates/stores/back-in-stock.ts` before `components` dispatches.
+- `src/utils/categories.ts` — pre-copied from `<SKILL_ROOT>/templates/stores/categories.ts` before `pages` dispatches.
+
+If you find one of these missing at runtime, that's an orchestrator-side bug — return `status: "partial"` with `errors: [{code: "UTILITY_TEMPLATE_NOT_PRECOPIED", path: "<missing>"}]` and continue. Do NOT write your own version; the post-phase manifest check will recover by template-copy and the right helper lands on disk.
+
+## CSS ownership — stores pack
+
+Stores-specific component CSS lives in `src/styles/components-stores.css` (written by the `components-css` scope — see `./COMPONENTS_CSS.md`), NOT in the designer's `global.css`. The classes the pack owns:
+
+- `.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: var(--spacing-md)` on the card plus horizontal padding on each text block when you set the radius. See `references/shared/STYLING.md` § "Component-specific CSS is owned by the component, not the designer".
+- `.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: var(--spacing-xl);` 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]`.
+
+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-stores.css`.
+
+## Back-in-stock subscribe — components + pages wiring split
+
+Back-in-stock is a dashboard-toggleable feature: it ships in every stores build but only lights up when the merchant clicks "Start Collecting Requests" in the Back in Stock dashboard. The implementation is split across the two scopes the same way every other stores feature is:
+
+- **`components` scope** writes the SSR probe (`src/utils/back-in-stock.ts`) and the React form island (`src/components/BackInStockForm.tsx`). See `./BACK_IN_STOCK.md` for the full rules — especially the two app ids (use `1380b703-…` for back-in-stock, NOT the Stores install id `215238eb-…`) and the bare-fields rule (no `itemUrl`, no `image` on the SDK call).
+- **`components-css` scope** appends the back-in-stock form rules to `src/styles/components-stores.css` as part of writing that file. See `./BACK_IN_STOCK.md` § 3 for the CSS append.
+- **`pages-products` scope** imports `getBackInStockEnabled` in `[slug].astro`, awaits the probe, and passes `backInStockEnabled` + `priceAmount` to `<ProductPurchase>`. ProductPurchase renders the form in its three OOS branches when the prop is true.
+
+If the merchant hasn't enabled "Start Collecting Requests", the probe returns `false`, the prop stays `false`, and the form never mounts — no rebuild needed when the merchant flips the toggle in the dashboard.
+
+## Stores-specific failure modes
+
+| Wrong | Right |
+|---|---|
+| `import { products }` | `import { productsV3 }` — V1 silently returns 0 on V3 catalogs |
+| Skip `variantId` on cart add | Always include — single-variant products have one |
+| Omit `wixMetadata` on `/products/[slug]` | Required for Wix sitemap/SEO/deep-link routing |
+| Mount CartBadge on a page component | Mount via ecom's `contributes:` marker in `Navigation.astro` so it appears on all pages |
+| Hit `/stores/v3/categories/...` for category endpoints | Categories live under `/categories/v1/` — `POST /categories/v1/categories`, `POST /categories/v1/bulk/categories/{id}/add-items`, `POST /categories/v1/categories/query` |
+| Use the back-in-stock app id `1380b703-…` when adding items to a category | Use the **Stores install id** `215238eb-22a5-4c36-9e7b-e7c08025e04e` for `appId` on `bulkAddItemsToCategory` items — it's the same id Wix Stores writes to its products |
+| Call `categories.queryCategories(...).limit(N).find()` with no filter | The SDK builder rejects empty filter expressions with `INVALID_FILTER`. Always chain at least `.eq("visible", true)` before `.find()` |
+| Call `categories.listCategoriesForItems(items, ...)` from the SDK | The SDK function ships items via GET querystring and breaks on arrays. Use `POST /categories/v1/categories/list-categories-for-items` directly, or fan out per-category via `listItemsInCategory` |
+| Ship a client-side filter (`data-category-ids` + JS hide) on the product grid | Filter server-side via `/category/[slug]` routes; client-side filtering doesn't scale past ~100 products and breaks SEO. The `<CategoryRail/>` swaps cards via `<ClientRouter />`, not by hiding them |

package/skills/wix-headless/references/stores/PRODUCT_CATALOG_DATA.md

@@ -0,0 +1,249 @@
+# Recipe: Product Catalog Data Setup (Phase 1)
+
+Replace the default sample products Wix Stores installs with on-brand products via MCP. This file covers the `seed-seed` scope — data seeding only. Frontend wiring lives in the Phase 2 scope references (`SHARED_WIRING.md`, `PRODUCT_PAGES.md`, `CART_CHECKOUT.md`, `HOME_AND_NAV.md`) and should not be read by `seed-seed`.
+
+> **Critical Rules — Read Before Starting**
+> 1. **V3 only** — all endpoints under `/stores/v3/...` for products.
+> 2. **No improvised endpoints** — if an MCP call returns 404, stop and report. Do not guess alternative URLs. Do not loop on `SearchWixRESTDocumentation` more than twice on the same topic.
+> 3. **Do not seed categories.** Categories are merchant-driven — created in the Wix dashboard, not by this scope. The storefront's rail, Shop submenu, and `/category/[slug]` route are still wired (Phase 4) and light up automatically once the merchant adds at least one visible category with items (≤ 5 min after creation, the helper's TTL).
+
+> **V3 Catalog:** New Wix sites use Catalog V3. All endpoints below live under `/stores/v3/...`. The V1 product endpoints should not be used — they silently return 0 results on V3 catalogs.
+
+## Prerequisites
+
+- Wix Stores app must be installed on the site (via MCP after scaffolding, or installed via MCP if missing — see Step 0)
+
+## Setup: Replace Default Products via MCP
+
+> **Conditional:** This section only applies when ALL of these are true:
+> - The Stores app was just installed (default sample products exist)
+> - Wix MCP tools are available (`mcp__wix-mcp-remote__CallWixSiteAPI` exists)
+> - Discovery context is available in your prompt (business type, brand name, style)
+>
+> **If MCP tools are not available, skip this entire section.** The 12 default products remain and can be customized later in the Wix dashboard.
+
+> **API error guard:** If any MCP call in Phase 1 returns a 404 or an unexpected error, do **not** retry the same call with a guessed alternative URL or namespace. Report the failing endpoint, request body, and error verbatim to the user, then stop. Improvised endpoints have caused multi-minute silent stalls in past runs.
+
+> **Stores appDefId** for install and `catalogReference.appId`: `215238eb-22a5-4c36-9e7b-e7c08025e04e`. (A different defId — `1380b703-ce81-ff05-f115-39571d94dfcd` — is used for `wixMetadata.appDefId` in Phase 2. Do not swap them.)
+
+### Step 0: Ensure Stores App Is Installed
+
+Before querying products, verify the Stores app is installed:
+
+1. **Probe** — `CallWixSiteAPI: POST /stores/v3/products/query` with body `{ "query": { "paging": { "limit": 1 } } }`
+2. **If the API returns a "REQUIRED_APP_NOT_INSTALLED" error** → install the Wix Stores app:
+   ```
+   CallWixSiteAPI: POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install
+   body: {
+     "tenant": { "tenantType": "SITE", "id": "<siteId>" },
+     "appInstance": { "appDefId": "215238eb-22a5-4c36-9e7b-e7c08025e04e", "enabled": true }
+   }
+   ```
+   > Translate this prose-HTTP form into the full `CallWixSiteAPI` tool-call shape — include `siteId`, `reason`, `sourceDocUrl` wrapper fields and pass `body` as a real object (NOT a stringified JSON). See `../../shared/MCP_PREFIX.md` § "CallWixSiteAPI call conventions".
+
+   Then retry the probe query to confirm installation succeeded.
+3. **If the probe succeeds** → proceed to Step 1.
+
+---
+
+Replace the 12 generic sample products with 3 on-brand products that match the user's business before building any code.
+
+### Step 1: Query Default Products
+
+```
+CallWixSiteAPI: POST /stores/v3/products/query
+body: {
+  "query": {
+    "paging": { "limit": 50 }
+  }
+}
+```
+
+Collect all product IDs from the response.
+
+### Step 2: Bulk Delete Defaults
+
+```
+CallWixSiteAPI: POST /stores/v3/bulk/products/delete
+body: {
+  "productIds": ["<id1>", "<id2>", ..., "<id12>"]
+}
+```
+
+### Step 3: Design 3 On-Brand Products
+
+No API call — use discovery context (business type, brand name, style, industry) to plan 3 products:
+
+- Product names, descriptions, and pricing appropriate for the business
+- Product type: `PHYSICAL`
+- Options (size, color, etc.) if appropriate for the business type
+
+**Product design guidelines by business type:**
+
+| Business Type | Product 1 | Product 2 | Product 3 |
+|--------------|-----------|-----------|-----------|
+| Skincare / beauty | Signature serum or moisturizer | Cleansing product | Gift set or bundle |
+| Clothing / fashion | Signature top or dress | Accessory item | Seasonal piece |
+| Food / bakery | Signature item (cake, bread) | Sampler or variety pack | Gift box |
+| Home / decor | Statement piece | Functional item | Set or collection |
+| Fitness / wellness | Core product (mat, equipment) | Accessory | Starter kit |
+| General retail | Best-seller item | Complementary item | Value bundle |
+
+Adapt names, descriptions, and pricing to match the brand's tone and style. Use the brand name in product descriptions where natural.
+
+### Step 4: Bulk Create Products
+
+> **V3 bulk create body format:** Each item in the `products` array is a flat product object — do NOT wrap in a `"product"` key. Only include `options` and `variantsInfo` when the product has meaningful variants (multiple sizes, colors, etc.). Simple products with no real variants should omit these fields — the API creates a default variant automatically using the product-level price.
+
+**Product with variants** (e.g., skincare with 30ml/50ml sizes):
+
+```
+CallWixSiteAPI: POST /stores/v3/bulk/products-with-inventory/create
+body: {
+  "products": [
+    {
+      "name": "<Product Name>",
+      "productType": "PHYSICAL",
+      "description": {
+        "nodes": [
+          {
+            "type": "PARAGRAPH",
+            "id": "<unique-id>",
+            "nodes": [
+              { "type": "TEXT", "textData": { "text": "<Product description>" } }
+            ],
+            "paragraphData": { "textStyle": { "textAlignment": "AUTO" } }
+          }
+        ],
+        "metadata": { "version": 1, "id": "<unique-id>" }
+      },
+      "visible": true,
+      "visibleInPos": true,
+      "physicalProperties": {},
+      "options": [
+        {
+          "name": "Size",
+          "optionRenderType": "TEXT_CHOICES",
+          "choicesSettings": {
+            "choices": [
+              { "choiceType": "CHOICE_TEXT", "name": "30ml" },
+              { "choiceType": "CHOICE_TEXT", "name": "50ml" }
+            ]
+          }
+        }
+      ],
+      "variantsInfo": {
+        "variants": [
+          {
+            "choices": [
+              {
+                "optionChoiceNames": {
+                  "optionName": "Size",
+                  "choiceName": "30ml",
+                  "renderType": "TEXT_CHOICES"
+                }
+              }
+            ],
+            "price": { "actualPrice": { "amount": "48.00" } },
+            "visible": true,
+            "inventoryItem": { "quantity": 50, "preorderInfo": { "enabled": false } },
+            "physicalProperties": {}
+          }
+        ]
+      }
+    }
+  ],
+  "returnEntity": true
+}
+```
+
+Add one more variant object per size in the `variants` array (one per choice combination). Use the Ricos format for descriptions (PARAGRAPH > TEXT > textData).
+
+**Simple product without real variants** (e.g., a gift set with one price and no size/color choices):
+
+Omit `options` and `variantsInfo` entirely. Set the price at the product level. The API creates a default variant automatically:
+
+```json
+{
+  "name": "Complete Gift Set",
+  "productType": "PHYSICAL",
+  "visible": true,
+  "visibleInPos": true,
+  "physicalProperties": {},
+  "priceData": { "price": 89.00 },
+  "manageVariants": false,
+  "inventoryItem": { "trackQuantity": true, "quantity": 30 }
+}
+```
+
+> **Do NOT create dummy options** (e.g., "Type: Standard") for simple products. Only add `options` and `variantsInfo` when the product genuinely has multiple variants. Phase 2's `ProductPurchase` component detects products without meaningful options and renders just the "Add to Cart" button — no unnecessary selection step for the buyer.
+
+Include all products in the same `products` array. Do not include `media` — product images are handled separately by the image agent after product creation.
+
+### Step 5: Verify
+
+```
+CallWixSiteAPI: POST /stores/v3/products/query
+body: {
+  "query": { "paging": { "limit": 50 } }
+}
+```
+
+Confirm exactly 3 products exist. Report the product names and prices to the user.
+
+### Step 6: Categories are NOT seeded
+
+This scope does **not** create categories. The default Wix Stores install ships one auto-managed category (`online_stores_all_products`) — leave it; the frontend filters it out by handle.
+
+If the merchant later creates visible categories in the Wix dashboard and assigns products to them, the storefront wires up automatically:
+
+- `<CategoryRail/>` renders pills above `/products` and `/category/[slug]`.
+- The `Navigation` Shop submenu lists the categories.
+- `/category/<slug>` becomes a reachable, server-side-filtered listing.
+
+This works because the frontend (`src/utils/categories.ts`, written by the `pages-categories` scope in Phase 4) live-queries the Wix API at SSR time with a 5-min cache — no redeploy or regen is needed.
+
+### Step 7: Return Results
+
+Emit a structured JSON block at the end of your completion message per `../../shared/RETURN_CONTRACT.md`. Do NOT write a sidecar file.
+
+```json
+{
+  "status": "complete",
+  "phase": "stores-seed",
+  "scope": "seed-seed",
+  "summary": "Deleted {N} default products; created {N} on-brand products with variants",
+  "data": {
+    "products": [
+      {
+        "id": "<uuid>",
+        "name": "<name>",
+        "slug": "<slug>",
+        "variantId": "<uuid>",
+        "price": 0,
+        "inventory": 0,
+        "sku": "<sku>"
+      }
+    ],
+    "categories": [],
+    "deletedCount": 0,
+    "createdCount": 0
+  },
+  "files": [],
+  "errors": []
+}
+```
+
+`data.categories` is always `[]` — this scope does not seed categories. The field is retained for shape stability so downstream consumers don't need a new schema.
+
+The JSON block MUST be the last content in your message. Parent skill consumes `data.products[*].slug` and `data.products[*].variantId` for the Phase 4 Pages scopes.
+
+### Phase 1 Boundary — Do Not Touch Other Site Data
+
+Phase 1 is complete after Step 7. Do **not** attempt any of the following, even if they seem like reasonable polish:
+
+- Cleaning up "orphan customizations", "All Products" containers, brand records, or any other catalog metadata you didn't create.
+- Creating, renaming, or deleting any category — categories are merchant-driven (see Step 6). The auto-managed "All Products" category (handle `online_stores_all_products`) stays in place; the frontend filters it out by handle.
+- Verifying your work via additional `query` calls beyond the Step 5 verification already performed.
+
+Phase 2+ (frontend wiring) is covered in the scope-specific references (`SHARED_WIRING.md`, `PRODUCT_PAGES.md`, `CATEGORY_PAGES.md`, `CART_CHECKOUT.md`, `HOME_AND_NAV.md`) — do not read them during `seed-seed`.

package/skills/wix-headless/references/stores/PRODUCT_PAGES.md

@@ -0,0 +1,213 @@
+# Phase 4 Product Pages — Stores
+
+Scope: `product-pages`. Launched in **Step 7** after designer page scopes have written placeholder `.astro` files. This scope rewrites the product listing, product detail, and ProductCard component with live `productsV3` queries.
+
+## Scope
+
+Files this agent OWNS (rewrites from designer output):
+
+- `src/pages/products/index.astro` — product listing
+- `src/pages/products/[slug].astro` — product detail with `wixMetadata` + SEO tags
+- `src/components/ProductCard.astro` — reusable card used by listing + home
+
+Files this agent MUST NOT touch:
+- `src/components/ProductPurchase.tsx`, `src/components/AddToCartButton.tsx` — owned by `components`
+- `src/pages/cart.astro`, `src/pages/thank-you.astro` — owned by `pages-cart-checkout`
+- `src/pages/index.astro`, `src/components/Navigation.astro` — owned by `pages-home-and-nav`
+- `global.css`, any other `.astro` page, any other component — owned by designers
+
+## Inputs (from parent prompt)
+
+- **Phase 1 return data** — `products: [{id, name, slug, variantId, price, inventory, sku}]` — use slugs when needed (rarely; `queryProducts` returns them already).
+- **Design tokens** — read `.wix/site.json.designTokens` for the published color/spacing/typography vocabulary; compose Tailwind utilities derived from those tokens (`class="py-4xl flex flex-col gap-md font-display"`) at the call site rather than inventing semantic classes for layout/spacing/typography. Retained global semantic classes are limited to compound patterns (`offer-callout`, `cart-summary`), interactive primitives (`btn-primary`, `product-card`), and JS targets — see `references/shared/STYLING.md`.
+- **Designer output summary** — paths of existing `products/index.astro`, `products/[slug].astro`, `ProductCard.astro` with placeholder data.
+
+## Critical rules (all must be honored)
+
+1. **Use `productsV3`, not `products`** — V1 silently returns 0 on V3 catalogs.
+2. **Product detail MUST use `getProductBySlug()`**, not `queryProducts()`. `queryProducts` omits variant data (`options`, `variantsInfo`), making add-to-cart silently fail.
+3. **Product detail MUST export `wixMetadata`** — required for Wix sitemap, SEO editor, and dashboard deep links. Without it, the sitemap has zero product entries.
+4. **Mount `SeoTags` on the detail page** — pipe `product.seoData.tags` through `Layout`'s `head` slot so merchant SEO edits in the Wix dashboard reach the live site. `seoData` is returned by default — no `fields` flag needed.
+5. **Mount `ProductPurchase` with `client:load` and a single `product` prop, plus the back-in-stock probe + price props.** `<ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} backInStockEnabled={backInStockEnabled} priceAmount={priceAmount} />`. The component destructures internally; passing flat props (`productId={product._id}`, `options={product.options}`, …) silently renders nothing because the new contract expects `product`. The `backInStockEnabled` boolean comes from `await getBackInStockEnabled()` (template imports it from `../../utils/back-in-stock`); `priceAmount` is the numeric price already computed in the frontmatter. See `BACK_IN_STOCK.md` for why both are needed.
+6. **SSR only — do NOT add `export const prerender = true` or `getStaticPaths()`.** The productsV3 SDK depends on request-context auth (tenant resolution, site headers). At prerender time there is no request, and `.queryProducts().limit()` short-circuits to `"is not a function"`. Keep `[slug].astro` server-rendered with `Astro.params.slug`.
+7. **No HTML comments in `.astro` frontmatter.** Build fails with "Legacy HTML single-line comments are not allowed".
+8. **Default to tokens-as-utilities for layout/spacing/typography.** When you need a section padding, a flex column, a typographic treatment — write Tailwind utilities derived from `@theme` tokens (`<section class="py-4xl flex flex-col gap-md">`, `<h1 class="font-display text-4xl">`). Do NOT invent semantic classes like `.featured-section`, `.page-header`, `.products-header-image` — Tailwind v4 silently drops undeclared classes. Use a global semantic class only when one is published in designer `INSTRUCTIONS.md`'s always-required list (`product-card`, `product-card-ribbon`, `offer-callout` family). For one-off page decoration, write a co-located `<style>` block at the bottom of the same `.astro` file using `var(--color-foo)` token references.
+9. **Preserve designer classes.** When the designer used a published global semantic class on existing markup, keep it; don't rename. Add Tailwind utilities alongside if you need additional layout adjustment.
+
+## Wix Site Structure — `wixMetadata` + `@wix/astro-pages`
+
+`@wix/astro-pages` is already wired into the blank scaffold's `astro.config.mjs` as `wixPages()`. It injects a `/_wix/pages.json` endpoint enumerating every page and reading each page's `wixMetadata` export. Wix platform services use this JSON to:
+
+- Generate server-side sitemap entries for dynamic product URLs (via `@wix/auto_sdk_seo_seo-sitemap-entries`)
+- Power the dashboard SEO editor ("Edit SEO for Product pages")
+- Resolve deep links from dashboard / email / analytics surfaces back to the right headless URL
+
+> **Two different Stores appDefIds — do not confuse:**
+> - `215238eb-22a5-4c36-9e7b-e7c08025e04e` — for `catalogReference.appId` in cart operations (same value used for app install in Phase 1).
+> - `1380b703-ce81-ff05-f115-39571d94dfcd` — for **`wixMetadata.appDefId`** on Stores sub-pages (product, category).
+>
+> Both are correct. They identify different entities.
+
+## 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 class names only if the styling contract maps them differently than the defaults
+
+Do NOT modify logic, imports, SDK calls, `wixMetadata` export, or prop-passing. The templates encode non-negotiable Wix platform integrations (sitemap registration, inventoryItemsV3 OOS truth, SSR-only constraint, analytics payloads).
+
+## Implementation
+
+> Every Wix SDK `await` in the templates is already wrapped in try/catch — keep those guards when adapting. See `references/shared/IMPLEMENTER.md` § "SSR error guards" for the underlying rule and rationale.
+
+### 1. `src/pages/products/index.astro` — product listing
+
+Use template `templates/products/index.astro`.
+
+Preserves the designer's page structure (class names, layout) and replaces the placeholder products array with a guarded, **cursor-paginated** `productsV3.queryProducts({ fields: ["CURRENCY"] }).limit(24).skipTo(cursor).find()` (cursor read from `?cursor=` on the URL; Prev/Next anchors built from `result.cursors.next` / `.prev`). Mounts the shared `<CategoryRail/>` (written by `pages-categories`) above the grid, passing `activeSlug={null}` and the prev/next hrefs. Emits the `AddProductImpression` analytics event from a client-side script that reads a JSON payload serialized at SSR.
+
+> **Imports written by `pages-categories`.** Both `<CategoryRail/>` and `listStoreCategories` come from files this scope must NOT write — they're owned by the `pages-categories` scope. Import paths: `../../components/CategoryRail.astro` and `../../utils/categories`. If either import fails to resolve, return `status: "partial"` with `errors: [{ code: "MISSING_PAGES_CATEGORIES_OUTPUT", path: "<missing path>" }]` — that means the orchestrator dispatched scopes out of order.
+
+> **Page size 24** — multiple of the 2/3/4-column grid, well under Wix's per-request cap of 100. Do not change without updating `CATEGORY_PAGES.md` to match.
+
+> **No client-side filter.** The previous "ship every product, hide non-matching cards via JS" pattern is gone — it doesn't scale and breaks SEO. Do not reintroduce `data-category-ids` on `<ProductCard>` or any DOM-hide script. Filtering is done by navigating to `/category/<slug>` (a real route), and `<ClientRouter />` from the designer's Layout handles the swap.
+
+> **Why the double-script pattern:** Listing page is server-rendered but `AddProductImpression` must fire in the browser. The server-computed payload is serialized into an inert JSON `<script>` (`is:inline`) and read by a separate processed `<script>` (bundled by Astro — has ES `import`). `define:vars` + inline-script combinations cannot do ES imports.
+
+> **Gift-card mirror filter (do not remove).** The template applies `productList = productList.filter(p => p.ribbon?.name !== "Gift Card")` after building the result list. When the dashboard's Wix Gift Card app is enabled, it auto-creates 5 mirror Stores products (one per denomination, `productType: "DIGITAL"`, ribbon name `"Gift Card"`). Buying a mirror yields a dud DIGITAL line item that does NOT trigger gift-card issuance — the customer-facing surface for gift cards is `/gift-cards` (gift-cards pack), not `/products`. The filter holds whether or not the gift-cards pack is loaded for this site, so a future site that drops gift-cards but still has the dashboard app stays clean.
+
+### 2. `src/components/ProductCard.astro` — reusable card
+
+Use template `templates/ProductCard.astro`.
+
+The template:
+- Accepts a single `{ product }` prop — the full Wix product object from `productsV3`
+- Resolves product images via `resolveWixImageUrl` (imported from the seeded shared util at `../utils/wix-image`)
+- Applies `product-card` contract class
+- Includes delegated click analytics (`ClickProduct` event via data attributes)
+
+Class from contract: `productCard` → `"product-card"`. If the designer already added the class, don't duplicate.
+
+### 3. `src/pages/products/[slug].astro` — product detail
+
+Use template `templates/products/[slug].astro`.
+
+The template:
+- Exports `wixMetadata` with the Stores sub-page appDefId (`1380b703-…`) and `STORES.PRODUCT.SLUG` token for platform expansion
+- Uses `getProductBySlug()` (NOT `queryProducts()` — it omits variant data)
+- Queries `inventoryItemsV3.queryInventoryItems({ filter: { productId } })` and builds a `variantId → { quantity, trackQuantity, preorderEnabled }` map. This is the AUTHORITATIVE OOS signal; `variantsInfo[].inventoryStatus.inStock` is a stale cached flag.
+- Pipes `product.seoData.tags` through Layout's `head` slot via `<SeoTags slot="head" tags={seoTags} />` (rendered only when any tag is visible)
+- Calls `await getBackInStockEnabled()` from `../../utils/back-in-stock` to learn whether the dashboard's "Start Collecting Requests" toggle is on for Wix Stores; passes the boolean and `priceAmount` to `<ProductPurchase>`. The back-in-stock subscribe form renders inside ProductPurchase's three OOS branches when the prop is true. See `BACK_IN_STOCK.md` for the app-id discrepancy and the bare-fields rule.
+- Mounts `<ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} backInStockEnabled={backInStockEnabled} priceAmount={priceAmount} />` with the canonical `{ product }` contract
+- Wraps both SDK awaits in try/catch so an SDK error produces a 404 redirect (product fetch) or an empty inventory map (inventory fetch), never a torn page (the back-in-stock probe is internally wrapped — it returns `false` on any failure, so it doesn't need an outer try/catch)
+
+**Critical details on `wixMetadata`:**
+
+- **Required for Wix platform indexing.** Without it, the product detail route is invisible to Wix's sitemap generator, SEO editor, and deep-link resolver.
+- **`appDefId`: `1380b703-ce81-ff05-f115-39571d94dfcd`** is the Stores page-registration defId — do NOT confuse with the Stores install/catalog defId (`215238eb-...`) used in Phase 1 and `catalogReference.appId`.
+- **`pageIdentifier`: `"wix.stores.sub_pages.product"`** is the canonical Wix identifier — constant.
+- **`identifiers.slug`**: maps the Astro route param to Wix's identifier token. Route is `[slug].astro`, so key is `slug`. Value `"STORES.PRODUCT.SLUG"` tells Wix to expand with each product's slug.
+
+**Layout `head` slot** — the `Layout.astro` written by the Design System phase must accept a `head` slot and a `hasSeoTags` prop. When `hasSeoTags` is true, the Layout omits its default `<title>`/`<meta description>` and instead renders the `head` slot contents into `<head>`. This lets `SeoTags` entirely replace the default metadata. If the Layout signature doesn't match, the Design System brief is missing it — flag this in the return's `errors` array and continue with a fallback (non-merchant-editable) title.
+
+## Live offers (discount-rule indicators)
+
+The promotion ribbon on each product card is **owned by `ProductCard.astro` itself** — the component imports `fetchLiveOffers` + `offersForProduct` from `src/utils/discounts.ts` (shipped by the ecom `components` scope) and renders its own ribbon. Pages that mount `ProductCard` do NOT pass an `offers` prop and do NOT fetch offers themselves. This concentrates the wiring in one place — page-level wiring forced every page that renders ProductCard to remember it, and category pages would silently ship without ribbons.
+
+`fetchLiveOffers` is memoized per request via `auth.elevate`'s caching, so rendering N ProductCards in one page does NOT fan out N discount-rule queries.
+
+**Listing (`products/index.astro`)** — just `<ProductCard product={product} index={idx} />`. No offers wiring required.
+
+**Detail (`products/[slug].astro`)** — the detail page renders a richer offer callout above `<ProductPurchase>`. That callout still belongs to this scope (it's not part of the card). After the product is loaded:
+
+```ts
+import { fetchLiveOffers, offersForProduct } from "../../utils/discounts";
+const offers = await fetchLiveOffers();
+const productOffers = offersForProduct(offers, product._id);
+```
+
+```astro
+{productOffers.length > 0 && (
+  <div class="offer-callout">
+    {productOffers.map((o) => (
+      <div class="offer-callout-item">
+        <span class="offer-callout-badge">Offer</span>
+        <div>
+          <p class="offer-callout-name">{o.name}</p>
+          {o.offer && o.offer !== o.name && (
+            <p class="offer-callout-detail">{o.offer}</p>
+          )}
+        </div>
+      </div>
+    ))}
+    <p class="offer-callout-foot">Applied automatically at checkout.</p>
+  </div>
+)}
+
+<ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} />
+```
+
+The `.offer-callout*` classes are owned by `src/styles/components-stores.css` (written by the stores Phase 3 components agent), NOT by the designer. Use `{o.offer}` for the body text — that's the dashboard-authored offer string (e.g. `"Buy 1 item\nAll products\n\nGet 1 item for free"`) which Wix formats with `\n` line breaks; the CSS includes `white-space: pre-line` so those render as line breaks.
+
+**Do NOT** hit `discountRules.queryDiscountRules` directly from this scope — always go through `fetchLiveOffers()`. The helper wraps the call with `auth.elevate()` (the endpoint requires `ECOM.DISCOUNT_RULES_READ`, visitor clients return nothing silently) and normalizes the scope-id field (`_id` vs `id`) which trips up naive matching.
+
+When the site has no active rules (first deploys, or the user hasn't created any in the dashboard yet), `offers` comes back as `[]`, `offersForProduct(...)` returns `[]`, the ribbon and callout both render nothing — no code path to guard for.
+
+## Analytics fired from this scope
+
+| Event | Fires from | When | Payload |
+|-------|------------|------|---------|
+| `AddProductImpression` | `products/index.astro` | Listing page load | `{ contents: [{id, name, price, currency, position}], origin: "Product Listing" }` |
+| `ClickProduct` | `ProductCard.astro` | Delegated click on any card | `{ id, name, price, currency, origin: "Product Listing" }` |
+| `ViewContent` | `products/[slug].astro` | Detail page load | `{ id, name, price, currency, origin: "Product Page" }` |
+
+`AddToCart` fires from `AddToCartButton.tsx` (written by `components`) — not this scope.
+
+## Return format
+
+```json
+{
+  "status": "complete",
+  "phase": "stores-pages-products",
+  "scope": "product-pages",
+  "summary": "Wired product listing + detail + ProductCard to productsV3; wixMetadata + SeoTags mounted",
+  "data": {
+    "pagesWired": 2,
+    "wixMetadataExported": true,
+    "seoTagsMounted": true,
+    "useGetProductBySlug": true,
+    "analyticsEvents": ["AddProductImpression", "ClickProduct", "ViewContent"]
+  },
+  "files": [
+    "src/pages/products/index.astro",
+    "src/pages/products/[slug].astro",
+    "src/components/ProductCard.astro"
+  ],
+  "errors": []
+}
+```
+
+If any of `wixMetadataExported`, `seoTagsMounted`, `useGetProductBySlug` ends up `false`, set `status: "partial"` and populate `errors` with the specific issue. These three are non-negotiable for a merchant-grade site.
+
+## Anti-patterns
+
+| WRONG | CORRECT |
+|-------|---------|
+| `import { products }` from `@wix/stores` | `productsV3` |
+| Use `queryProducts()` on detail page | `getProductBySlug()` — `queryProducts` omits variant data |
+| `export const prerender = true` + `getStaticPaths()` on `[slug].astro` | SSR only — productsV3 needs request-context auth; prerender short-circuits it |
+| Pass flat props to `<ProductPurchase>` (`productId`, `options`, `variantsInfo`, …) | Pass the whole product: `<ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} />` |
+| Hardcode `<title>` from `product.name` | Pipe `product.seoData.tags` through `SeoTags` slot, fall back to `product.name` only when tags are empty/disabled |
+| Omit `wixMetadata` export | Required — platform indexing breaks silently without it |
+| Add `fields: ["SEO_DATA"]` | `seoData` is returned by default — no such enum value exists |
+| Write `src/utils/wix-image.ts` inline | Import `resolveWixImageUrl` from `../utils/wix-image` — shared util already exposes it |
+| `ls src/` to find designer output | Parent prompt lists every existing `src/` file — read directly |
+| Rename designer class names | Keep them; use contract classes when ADDING new markup |
+| HTML `<!-- comment -->` in `.astro` frontmatter | `//` or `/* */` — frontmatter is TypeScript |
+| Mount React island without `client:load` | Options + cart state needs hydration |
+| Pass `"INVENTORY"` in the `fields` array | No such enum value exists for `productsV3`. Valid values: `URL`, `CURRENCY`, `INFO_SECTION`, `MERCHANT_DATA`, `PLAIN_DESCRIPTION`, `INFO_SECTION_PLAIN_DESCRIPTION`, `SUBSCRIPTION_PRICES_INFO`, `BREADCRUMBS_INFO`, `WEIGHT_MEASUREMENT_UNIT_INFO`, `VARIANT_OPTION_CHOICE_NAMES`, `MEDIA_ITEMS_INFO`, `DESCRIPTION`, `DIRECT_CATEGORIES_INFO`, `ALL_CATEGORIES_INFO`, `INFO_SECTION_DESCRIPTION`, `THUMBNAIL`, `PRODUCT_CHOICES_MEDIA_REFERENCES`. Passing an invalid value makes the query throw. |
+| Trust `variantsInfo[].inventoryStatus.inStock` as the OOS gate | It's a stale cached flag — a variant with real quantity 0 can still report `inStock: true`. Query `inventoryItemsV3.queryInventoryItems({ filter: { productId } })` at SSR and pass a `variantId → { quantity, trackQuantity, preorderEnabled }` map into `ProductPurchase`. The template already does this. |
+| Skip the `backInStockEnabled` prop on `<ProductPurchase>` | Always pass it (template already imports `getBackInStockEnabled`). When the prop is missing, the OOS subscribe form never renders even if the merchant has enabled collecting requests. |
+| Pass the formatted price string (`"$695"`) as `priceAmount` | Pass the numeric `priceAmount` already computed in frontmatter. The Wix back-in-stock service rejects formatted prices with `400 DECIMAL_GTE`. |