@wix/agent-skills 1.0.0

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

@@ -0,0 +1,178 @@
+# Phase 3 Components — Back in Stock (Stores)
+
+Split across the stores `components` scope (TSX/util files) and the `components-css` sibling (CSS rules). The matching Phase 4 wiring lives in `PRODUCT_PAGES.md` (SSR probe import + new props on `<ProductPurchase>`).
+
+## Scope
+
+Files written for back-in-stock, by scope:
+
+**`components` scope** (see `./SHARED_WIRING.md`):
+- `src/utils/back-in-stock.ts` — SSR-elevated probe of the Wix back-in-stock service, plus the canonical Stores app id constant
+- `src/components/BackInStockForm.tsx` — React island that posts via `@wix/ecom`'s `backInStockNotifications.createBackInStockNotificationRequest`
+
+**`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`
+
+Use template `templates/back-in-stock.ts`.
+
+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-md mt-md p-lg border border-rule rounded;
+  background-color: var(--color-cream);
+}
+.back-in-stock-headline {
+  @apply flex flex-col gap-sm;
+}
+.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-sm;
+}
+.back-in-stock-input {
+  @apply flex-1 px-md py-sm 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-lg py-sm 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-md p-lg 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-sm 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"],
+    "utils": ["back-in-stock.ts"],
+    "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/utils/back-in-stock.ts",
+    "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/stores/CATEGORY_PAGES.md

@@ -0,0 +1,86 @@
+# Phase 4 Category Pages — Stores
+
+Scope: `pages-categories`. Launched in **Step 7** alongside `pages-products` and `pages-home-and-nav`. This scope writes the dedicated category landing route and the shared `<CategoryRail/>` + `categories.ts` helper that `pages-products` and `pages-home-and-nav` also import.
+
+**Dispatch:** all three stores Phase-4 scopes are dispatched in parallel — Astro resolves the cross-file imports at build time (Step 8). The orchestrator does not need to serialize. 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
+- `src/utils/categories.ts` — TTL-cached helpers: `listStoreCategories`, `getCategoryBySlug`, `listProductsInCategory`
+
+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** — `.wix/site.json.designTokens` for the published vocabulary. 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. **Use the Stores app id `215238eb-22a5-4c36-9e7b-e7c08025e04e`** as `STORES_APP_ID` in `categories.ts`. Same id used for cart ops and Phase 1 product seed. NOT the back-in-stock id `1380b703-…`.
+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 `templates/stores/` and write it verbatim to the corresponding `src/` path, with three small adjustments:
+
+| Template path | Site path |
+|---|---|
+| `templates/categories.ts` | `src/utils/categories.ts` |
+| `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 all three files exist:
+
+- `src/utils/categories.ts`
+- `src/components/CategoryRail.astro`
+- `src/pages/category/[slug].astro`
+
+If any 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.
+
+## Return contract
+
+```json
+{
+  "status": "complete",
+  "phase": "stores-pages",
+  "scope": "pages-categories",
+  "summary": "Wrote shared CategoryRail + categories helper; /category/[slug] route renders M categories.",
+  "data": {
+    "categoriesRendered": 0,
+    "filesWritten": [
+      "src/utils/categories.ts",
+      "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/stores/COMPONENTS_CSS.md

@@ -0,0 +1,129 @@
+# Phase 3 Components-CSS — Stores
+
+Sibling of the `components` scope. Launched in **Step 4.5** in the same concurrent batch — runs in parallel with the TSX/Astro work, ecom and gift-cards components, and Image Phase 2.
+
+## 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>/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 (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`, `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>/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`, `--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. 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: var(--spacing-md)` 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: 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]`.
+- **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 (observed across runs):
+
+- `.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
+
+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": "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 |

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

@@ -0,0 +1,227 @@
+# Phase 4 Home Page + Nav — Stores
+
+Scope: `pages-home-and-nav`. Launched in **Step 7** after `pages-categories` has written the shared rail and `categories.ts` helper. Patches the home page's stores-related placeholder data with live `productsV3` queries AND inserts the Shop submenu (categories list) into the persisted Navigation.
+
+## Scope
+
+Files this agent PATCHES (does NOT rewrite):
+
+- `src/pages/index.astro` — only the stores-related sections (featured products grid, category cards)
+- `src/components/Navigation.astro` — only at the `<!-- nav:links -->` marker; insert the Shop link + categories submenu
+
+Files this agent MUST NOT touch:
+- Any other part of `index.astro` — hero, copy, newsletter, decorative ornaments are designer-owned
+- Any part of `Navigation.astro` outside the `<!-- nav:links -->` marker — designer/ecom-owned (the marker model lets multiple verticals contribute siblings without conflict)
+- `src/utils/categories.ts`, `src/components/CategoryRail.astro`, `src/pages/category/[slug].astro` — owned by `pages-categories`; this scope only **imports** `listStoreCategories` from `categories.ts`
+- Any other component, page, or CSS
+- `global.css`
+
+## Inputs (from parent prompt)
+
+- **Phase 1 stores return** — `products: [{id, name, slug, ...}]`. Needed for live query on home page; also useful for deciding how many to feature.
+- **Design tokens** — read `.wix/site.json.designTokens` for the published color/spacing/typography vocabulary; compose Tailwind utilities derived from those tokens at the call site rather than inventing semantic classes. See `references/shared/STYLING.md` for the three styling categories.
+- **Designer output summary** — path of `src/pages/index.astro` and `src/components/Navigation.astro`, with notes on what placeholder data exists.
+- **Categories (lookup)** — if the designer used category links with hardcoded slugs, call `categoriesV3` SDK to discover real category slugs and rewrite `href`s.
+
+## Critical rules
+
+1. **Surgical edits only.** Use `Edit` tool, not `Write`. Preserve everything the designer wrote — hero, copy, decorative elements, section structure, class names.
+2. **Do NOT restructure layout.** If the designer didn't include featured products, don't add it.
+3. **Do NOT mutate categories in the catalog.** Read-only. Match designer's category slugs against real ones; rewrite `href` if matched; fall back to `/products` if not.
+4. **Never improvise category endpoint URLs.** Use `categoriesV3` SDK. If the SDK isn't available, fall back to `<prefix>CallWixSiteAPI` with `POST /categories/v1/categories/query` body `{"query":{}}`. Improvised `/stores/v3/categories/...` URLs caused a multi-minute stall historically.
+5. **If another agent already wired the home page** (e.g., a previous run), leave it alone and note this in the return.
+6. **ProductCard is a template** — always accepts `{ product }`. Pass raw SDK product objects, never flat-map. See § 1a.
+
+## When to run the home-page patch
+
+Skip the home-page patch entirely if the home page has NO stores-consuming components:
+
+- No `ProductGrid` / `ProductCard` with placeholder products array
+- No category cards with hardcoded category slugs (e.g., `/products?category=...`)
+
+If the home page is purely editorial (hero + copy + newsletter), return with `featuredProductsWired: false` — there's nothing to patch.
+
+## Implementation
+
+### 1. Home page: featured products
+
+Find the placeholder products array in `src/pages/index.astro`. Replace with a server-side `productsV3` query; pass the raw product objects to `ProductCard`.
+
+> **WRONG:** `featured = products.map(p => ({name: p.name, price: ...}))` then `<ProductCard name={p.name} .../>`
+> **RIGHT:** `featured = featuredProducts ?? []` as `any[]`, then `<ProductCard product={p} />`
+>
+> Flat-mapping strips fields that ProductCard needs (`media`, `actualPriceRange`, etc.) and crashes the home page (`product` is `undefined`).
+
+```astro
+---
+// src/pages/index.astro (frontmatter additions only — keep existing imports)
+import { productsV3 } from "@wix/stores";
+
+// Wrap every SSR await in try/catch — see references/shared/IMPLEMENTER.md
+// § "SSR error guards" for the full rule.
+let featured: any[] = [];
+try {
+  const { items: featuredProducts } = await productsV3
+    .queryProducts({ fields: ["CURRENCY"] })
+    .limit(4)
+    .find();
+  featured = featuredProducts ?? [];
+} catch (err) {
+  console.error("[home] featured products query failed:", err);
+}
+---
+```
+
+Then pass each raw product to `ProductCard`. The ribbon is fetched inside ProductCard itself — pages no longer wire offers:
+```astro
+{featured.map((p) => <ProductCard product={p} />)}
+```
+
+> **Gift-card mirror filter.** After `featured = featuredProducts ?? []`, apply the same filter the listing template uses:
+> ```ts
+> featured = featured.filter((p) => p.ribbon?.name !== "Gift Card");
+> ```
+> The Wix Gift Card app, when enabled in the dashboard, auto-creates 5 DIGITAL Stores products tagged with the "Gift Card" ribbon. They must not appear in the home featured grid for the same reason they're filtered from `/products`: buying a mirror produces a dud line item that doesn't trigger gift-card issuance, and the home teaser block (gift-cards pack) is the right surface for gift cards on the home page.
+
+Do **NOT** flat-map products into `{name, price, slug, image}` — pass the raw SDK objects. ProductCard handles its own field extraction, image resolution, and ribbon (offer) rendering internally.
+
+Preserve every other prop the designer set on the grid. If `featured` is empty (query failed, or stock cleared), the grid renders with zero cards — the rest of the page stays up.
+
+### 1a. ProductCard interface (template — deterministic)
+
+ProductCard is a **template file** (`templates/ProductCard.astro`). The `product-pages` scope copies it deterministically. The interface is:
+
+```astro
+interface Props {
+  product: { _id?: string; name?: string; slug?: string; media?: ...; actualPriceRange?: ... };
+  index?: number;
+}
+const { product, index } = Astro.props;
+```
+
+The card fetches its own discount-rule offers internally via `fetchLiveOffers()` (memoized per-request), so pages don't pass an `offers` prop. Just `<ProductCard product={p} />`.
+
+**Do NOT flat-map.** ProductCard handles image resolution, price formatting, and ribbon rendering internally.
+
+**Verification:** After writing your Edit, grep `ProductCard.astro` for `Astro.props` and confirm the prop name in your `<ProductCard .../>` JSX matches `product`.
+
+### 2. Home page: category cards (slug matching)
+
+The designer may hardcode category links like `href="/products?category=rubber"`. These rely on Stores-app categories matching those slugs. Phase 1 does NOT create categories — they're merchant-driven, so on a fresh build the only category in the catalog is the auto-managed "All Products" (which the helper filters out). Expect zero real categories on first load; the matching logic below should degrade gracefully to `/products` and re-evaluate on each request as the merchant adds categories in the dashboard.
+
+Handle this:
+
+1. **Query real categories** via `@wix/stores` `categoriesV3`:
+   ```typescript
+   import { categoriesV3 } from "@wix/stores";
+   const { items: categories } = await categoriesV3.queryCategories().find();
+   ```
+   Fall back to `CallWixSiteAPI` with `POST /categories/v1/categories/query` body `{"query":{}}` if the SDK module is unavailable.
+2. **Match by name or slug** — case-insensitive substring match is fine (e.g., designer's "rubber" card matches a real category "Rubber Ducks").
+3. **If a match exists** → rewrite the `href` to use the real category slug (and optionally real category name).
+4. **If no match exists** → render the card with `/products` (no filter) rather than a dead filter URL. Keep the visual card intact.
+5. **If fewer real categories exist than cards the designer rendered** → render only matching cards. Do NOT invent categories.
+
+> Never call `/stores/v3/categories/*` — category endpoints live under `/categories/v1/`. Improvising URLs caused a documented multi-minute stall in past runs.
+
+### 3. Navigation: Shop submenu
+
+The designer scaffolds `Navigation.astro` with a `<!-- nav:links -->` marker that vertical packs replace with their primary nav contributions. Stores contributes the Shop link (always) and a hover/focus submenu listing the merchant's visible categories (when any exist — empty by default, since Phase 1 does not seed them).
+
+Read `src/utils/categories.ts` (already on disk — written by `pages-categories`) and import `listStoreCategories`. At the marker, insert:
+
+```astro
+---
+// (frontmatter additions to Navigation.astro — keep existing imports)
+import { listStoreCategories } from "../utils/categories";
+
+const navCategories = await listStoreCategories();
+---
+```
+
+Then replace the `<!-- nav:links -->` marker with:
+
+```astro
+<li class={`site-nav-item${navCategories.length > 0 ? ' has-submenu' : ''}`}>
+  <a
+    href="/products"
+    class="site-nav-link"
+    data-astro-prefetch="hover"
+    aria-current={isActive('/products') || isActive('/category') ? 'page' : undefined}
+    aria-haspopup={navCategories.length > 0 ? 'true' : undefined}
+  >Shop</a>
+  {navCategories.length > 0 && (
+    <ul class="site-nav-submenu" aria-label="Shop categories">
+      <li>
+        <a href="/products" class="site-nav-sublink" data-astro-prefetch="hover">All</a>
+      </li>
+      {navCategories.map((cat) => (
+        <li>
+          <a
+            href={`/category/${cat.slug}`}
+            class="site-nav-sublink"
+            data-astro-prefetch="hover"
+            aria-current={Astro.url.pathname === `/category/${cat.slug}` ? 'page' : undefined}
+          >{cat.name}</a>
+        </li>
+      ))}
+    </ul>
+  )}
+</li>
+<!-- nav:links -->
+```
+
+Keep the marker comment immediately after the inserted `<li>` so other vertical packs (gift-cards, etc.) can still contribute siblings.
+
+> **Empty-categories fallback.** `navCategories` is `[]` by default — Phase 1 does not seed categories, and `listStoreCategories()` only returns visible, non-empty, merchant-created categories. When empty, the submenu renders nothing and the link is just `Shop` with no dropdown. The aria-haspopup attribute is conditionally added so screen readers don't promise a menu that isn't there. As soon as the merchant creates a visible category with items in the dashboard, the submenu lights up automatically (≤ 5 min, the helper's TTL).
+
+> **`isActive` is already defined** in the designer-scaffolded Navigation.astro frontmatter (it returns whether a path matches the current URL). Reuse it; do not redefine.
+
+> **`data-astro-prefetch="hover"` is required** on every category link so hovering warms the prefetch cache before the click. Designer's Layout includes `<ClientRouter />` — without prefetch, each click waits a full network round-trip.
+
+> **CSS for submenu** comes from designer's `global.css` (`.site-nav-item`, `.site-nav-submenu`, `.site-nav-sublink`, hover/focus reveals). If those classes don't exist, return `status: "partial"` with `errors: [{ code: "DESIGNER_MISSING_NAV_SUBMENU_CSS", path: "src/styles/global.css" }]`.
+
+## Return format
+
+```json
+{
+  "status": "complete",
+  "phase": "stores-pages-home-and-nav",
+  "scope": "pages-home-and-nav",
+  "summary": "Wired home page featured products; inserted Shop submenu with N categories into Navigation",
+  "data": {
+    "homePageHadPlaceholders": true,
+    "featuredProductsWired": true,
+    "featuredProductsCount": 4,
+    "categoryCardsFound": 3,
+    "categoryCardsMatched": 2,
+    "categoryCardsFallbackToProducts": 1,
+    "navSubmenuCategoryCount": 0
+  },
+  "files": [
+    "src/pages/index.astro",
+    "src/components/Navigation.astro"
+  ],
+  "errors": []
+}
+```
+
+## Scope boundaries (reinforced)
+
+- **Do NOT edit** home page layout, copy, hero text, newsletter section, or decorative SVGs.
+- **Do NOT add** new sections the designer didn't include.
+- **Do NOT mutate** categories in the catalog — read-only.
+- **Do NOT touch** `Navigation.astro` outside the `<!-- nav:links -->` marker. Other vertical packs use the same marker model and write siblings.
+- **Do NOT touch** `CartBadge.tsx` or `CartView.tsx` — owned by ecom.
+- **Do NOT rewrite** `src/utils/categories.ts` or `src/components/CategoryRail.astro` — owned by `pages-categories`.
+- If home page already has a live query (another agent wired it), leave alone and note in return.
+
+## Anti-patterns
+
+| WRONG | CORRECT |
+|-------|---------|
+| Replace entire `index.astro` contents | Use `Edit` to patch only the stores-related sections |
+| Call `/stores/v3/categories/query` | Use `categoriesV3` SDK, or fall back to `/categories/v1/categories/query` |
+| Invent category slugs that don't exist | Match real categories; fall back to `/products` for unmatched |
+| Pass flat props (`name={p.name}`) when ProductCard expects `product={...}` object | ProductCard is a template — always `<ProductCard product={p} />` with the raw SDK object |
+| `featured = products.map(p => ({name: p.name, ...}))` — flat-mapping SDK results | Store raw products: `featured = featuredProducts ?? []` as `any[]` |