@wix/agent-skills 1.6.0 → 1.8.0

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

@@ -1,6 +1,6 @@
 # Phase 3 Components — Gift Cards
 
-Launched in **Step 4.5** alongside other verticals' `components` scopes (after Phase 2 Design System). Writes the runtime probe utility, the buy-flow React island, and scoped CSS. Finishes before the Phase 4 Pages scopes run in Step 7.
+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
 
@@ -18,7 +18,7 @@ Files this agent MUST NOT touch:
 
 ## Coordination: design tokens
 
-Your parent prompt includes the design tokens inline. Reference token CSS variables (`var(--color-cream)`, `var(--spacing-lg)`, etc.) from `components-gift-cards.css`. Do NOT read `.wix/design-tokens.css` from disk.
+Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave). Reference token CSS variables (`var(--color-cream)`, `var(--spacing-lg)`, etc.) from `components-gift-cards.css`.
 
 ## Critical rules
 
@@ -116,4 +116,4 @@ Use brand `@theme` utilities (`bg-cream`, `text-ink`, etc.) where natural; fall
 | 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 |
+| Write your own `wix-image.ts` / `analytics.ts` | Import from the shared utilities |

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

@@ -1,6 +1,6 @@
 # Phase 4 Pages — Gift Cards
 
-Launched in **Step 7** alongside other verticals' `pages` scopes. Writes the `/gift-cards` route and patches `Navigation.astro` + `index.astro` at their declared markers. The Components scope's outputs (`src/utils/gift-cards.ts`, `src/components/GiftCardPurchase.tsx`, `src/styles/components-gift-cards.css`) must already exist before this scope runs.
+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
 
@@ -126,4 +126,4 @@ If a marker is missing, return `status: "partial"` with `errors: [{ code: "MARKE
 | 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 |
+| 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/{stores → astro/stores}/BACK_IN_STOCK.md

@@ -1,15 +1,17 @@
 # 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>`).
+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/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`
 
+**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)
 
@@ -45,9 +47,9 @@ This scope uses **template files** instead of inline code. For each file below:
 
 Do NOT modify logic, imports, the bare-fields request shape, or the app-id constants.
 
-### 1. `src/utils/back-in-stock.ts`
+### 1. `src/utils/back-in-stock.ts` — pre-copied, not owned by this scope
 
-Use template `templates/back-in-stock.ts`.
+> 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.
@@ -150,7 +152,6 @@ The full components scope return must mention back-in-stock:
   "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
   },
@@ -159,7 +160,6 @@ The full components scope return must mention back-in-stock:
     "src/components/AddToCartButton.tsx",
     "src/components/ProductPurchase.tsx",
     "src/components/BackInStockForm.tsx",
-    "src/utils/back-in-stock.ts",
     "src/styles/components-stores.css"
   ],
   "errors": []
@@ -175,4 +175,4 @@ The full components scope return must mention back-in-stock:
 | 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 |
+| 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 → astro/stores}/CATEGORY_PAGES.md

@@ -1,8 +1,8 @@
 # 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.
+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.
 
-**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.
+**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
 
@@ -10,7 +10,9 @@ 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 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`
@@ -21,7 +23,7 @@ Files this agent MUST NOT touch:
 ## 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).
+- **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)
@@ -31,18 +33,17 @@ Files this agent MUST NOT touch:
 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-…`.
+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 `templates/stores/` and write it verbatim to the corresponding `src/` path, with three small adjustments:
+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/categories.ts` | `src/utils/categories.ts` |
 | `templates/CategoryRail.astro` | `src/components/CategoryRail.astro` |
 | `templates/category/[slug].astro` | `src/pages/category/[slug].astro` |
 
@@ -54,13 +55,12 @@ Adjustments at the call site:
 
 ## Pre-return file-existence assertion
 
-Before returning `status: "complete"`, verify all three files exist:
+Before returning `status: "complete"`, verify the two files you write 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.
+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
 
@@ -69,11 +69,10 @@ If any is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FIL
   "status": "complete",
   "phase": "stores-pages",
   "scope": "pages-categories",
-  "summary": "Wrote shared CategoryRail + categories helper; /category/[slug] route renders M categories.",
+  "summary": "Wrote shared CategoryRail + /category/[slug] route (imports the pre-copied categories helper); route renders M categories.",
   "data": {
     "categoriesRendered": 0,
     "filesWritten": [
-      "src/utils/categories.ts",
       "src/components/CategoryRail.astro",
       "src/pages/category/[slug].astro"
     ]
@@ -83,4 +82,4 @@ If any is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FIL
 }
 ```
 
-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.
+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 → astro/stores}/COMPONENTS_CSS.md

@@ -1,6 +1,6 @@
 # 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.
+**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
 
@@ -19,11 +19,11 @@ Exactly one file:
 
 You only need:
 
-1. **`<SKILL_ROOT>/templates/stores/components-stores.css`** — the canonical template. Read it once.
+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 (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.
+5. **Design tokens (on disk)** — read the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`spacing`/`rounded`/`containers`) 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.
 
@@ -32,7 +32,7 @@ You do NOT need to read `INSTRUCTIONS.md`, `SHARED_WIRING.md`, `BACK_IN_STOCK.md
 ### 1. Read the template
 
 ```
-<SKILL_ROOT>/templates/stores/components-stores.css
+<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`, `--spacing-md`, `--font-display`, etc.). **Do not rename the class names or state modifiers** — they must match the contract keys the TSX components reference.
@@ -68,7 +68,7 @@ The boundary: **rules referenced by exactly one pack's TSX live in that pack's s
 
 ### 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):
+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.
@@ -86,7 +86,7 @@ Write the adapted CSS to `src/styles/components-stores.css`. The first line must
 
 ## 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.
+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
 
@@ -126,4 +126,4 @@ If a leak was found and overridden, include `errors: [{code: "GLOBAL_CSS_LEAK",
 | 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 |
+| 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 → astro/stores}/HOME_AND_NAV.md

@@ -1,6 +1,8 @@
 # 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: `pages-home-and-nav` — dispatched as its **own serialized shell-patcher agent** in the build wave (NOT merged into the stores private-files agent, because it patches the shared shells). Imports the orchestrator-pre-copied `categories.ts` helper and the `CategoryRail`/`ProductCard` the stores private agent writes — **resolved at build time, so no write-ordering against that agent.** Patches the home page's stores-related placeholder data with live `productsV3` queries AND inserts the Shop submenu (categories list) into the persisted Navigation at the `<!-- nav:links -->` marker. (The `CartBadge` mount at `<!-- nav:actions -->` is ecom's; you own only `<!-- nav:links -->`.) Read your seeded slice from `.wix/seeded.json` (`seeded.stores`).
+
+> **You patch the shared `Navigation.astro` + `index.astro` shells**, which other packs (ecom at `nav:actions`, gift-cards, blog) also patch at their own markers. **Touch only your markers and preserve every other scope's siblings — never rewrite either file.** (Flow is the conductor's job: it serializes the shell-patching agents so concurrent marker edits don't collide — BUILD-astro.md § "Step 4.5", the serialized shell chain.)
 
 ## Scope
 
@@ -12,14 +14,14 @@ Files this agent PATCHES (does NOT rewrite):
 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`
+- `src/utils/categories.ts` — pre-copied by the orchestrator; this scope only **imports** `listStoreCategories` from it. `src/components/CategoryRail.astro`, `src/pages/category/[slug].astro` — owned by `pages-categories`
 - 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.
+- **Design tokens** — read the design tokens (the DESIGN.md vocabulary) from `.wix/design-tokens.css` (on disk) 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.
 
@@ -28,7 +30,7 @@ Files this agent MUST NOT touch:
 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.
+4. **Never improvise category endpoint URLs.** Use `categoriesV3` SDK. If the SDK isn't available, fall back to `curl` with `POST /categories/v1/categories/query` body `{"query":{}}`. Improvised `/stores/v3/categories/...` URLs cause a multi-minute stall.
 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.
 
@@ -72,7 +74,7 @@ try {
 ---
 ```
 
-Then pass each raw product to `ProductCard`. The ribbon is fetched inside ProductCard itself — pages no longer wire offers:
+Then pass each raw product to `ProductCard`. The ribbon is fetched inside ProductCard itself — pages don't wire offers:
 ```astro
 {featured.map((p) => <ProductCard product={p} />)}
 ```
@@ -116,7 +118,7 @@ Handle this:
    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.
+   Fall back to `curl` with `POST https://www.wixapis.com/categories/v1/categories/query` body `{"query":{}}` if the SDK module is unavailable (headers per `AUTHENTICATION.md`).
 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.
@@ -128,7 +130,7 @@ Handle this:
 
 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:
+Import `listStoreCategories` from `src/utils/categories.ts` (already on disk — pre-copied by the orchestrator). At the marker, insert:
 
 ```astro
 ---
@@ -213,7 +215,7 @@ Keep the marker comment immediately after the inserted `<li>` so other vertical
 - **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`.
+- **Do NOT rewrite** `src/utils/categories.ts` (pre-copied by the orchestrator — import only) 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
@@ -224,4 +226,4 @@ Keep the marker comment immediately after the inserted `<li>` so other vertical
 | 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[]` |
+| `featured = products.map(p => ({name: p.name, ...}))` — flat-mapping SDK results | Store raw products: `featured = featuredProducts ?? []` as `any[]` |

package/skills/wix-headless/references/{stores → astro/stores}/PRODUCT_PAGES.md

@@ -1,10 +1,10 @@
 # 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: `product-pages` (the `pages-products` scope) — written by the stores **merged build agent** (the build wave) *after* its `components` and `pages-categories` scopes. This scope writes the product listing, product detail, and ProductCard component **once** — applying the designer's visual spec (`references/astro/designer/INSTRUCTIONS.md` → `store-pages`) together with live `productsV3` queries in a single pass. Read your seeded slice from `.wix/seeded.json` (`seeded.stores`).
 
 ## Scope
 
-Files this agent OWNS (rewrites from designer output):
+Files this agent OWNS (each written once, visual structure + live queries together):
 
 - `src/pages/products/index.astro` — product listing
 - `src/pages/products/[slug].astro` — product detail with `wixMetadata` + SEO tags
@@ -12,15 +12,17 @@ Files this agent OWNS (rewrites from designer output):
 
 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/cart.astro`, `src/pages/thank-you.astro` — owned by `cart-checkout`
 - `src/pages/index.astro`, `src/components/Navigation.astro` — owned by `pages-home-and-nav`
+- `src/components/CategoryRail.astro` — owned by the `pages-categories` scope, which your merged agent writes **before** this one. **Import** from `../../components/CategoryRail.astro`; never `Write` it here. By the time you mount it, the `pages-categories` step has already put it on disk. If it's somehow absent, you wrote your scopes out of order — return `status: "partial"` with `errors: [{ code: "MISSING_PAGES_CATEGORIES_OUTPUT", path: "src/components/CategoryRail.astro" }]` (write `pages-categories` before `pages-products`; never defensively `Write` it from this scope).
+- `src/utils/categories.ts` — pre-copied by the orchestrator in the build-wave pre-batch (BUILD-astro.md § "Step 4.5"). **Import** `listStoreCategories`/etc. from `../../utils/categories`; never `Write` it.
 - `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.
+- **Design tokens** — read the design tokens (the DESIGN.md vocabulary) from `.wix/design-tokens.css` (on disk) 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 visual spec** — the layout, contract classes, and decorative-slot conventions for `products/index.astro`, `products/[slug].astro`, `ProductCard.astro` (from `references/astro/designer/INSTRUCTIONS.md` → `store-pages`), applied in the same pass as the live queries.
 
 ## Critical rules (all must be honored)
 
@@ -66,13 +68,13 @@ Do NOT modify logic, imports, SDK calls, `wixMetadata` export, or prop-passing.
 
 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.
+Applies the designer's page structure (class names, layout) and binds 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.
+> **Imports you must NOT write.** `<CategoryRail/>` (`../../components/CategoryRail.astro`) is written by the `pages-categories` scope your merged agent runs *before* this one; `listStoreCategories` (`../../utils/categories`) is pre-copied by the orchestrator. Both are on disk by the time you mount them. If either fails to resolve, return `status: "partial"` with `errors: [{ code: "MISSING_PAGES_CATEGORIES_OUTPUT", path: "<missing path>" }]` — that means your agent wrote `pages-products` before `pages-categories`, or the pre-copy was skipped.
 
 > **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.
+> **No client-side filter.** Do not ship every product and hide non-matching cards via JS — it doesn't scale and breaks SEO. Do not add `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.
 
@@ -210,4 +212,4 @@ If any of `wixMetadataExported`, `seoTagsMounted`, `useGetProductBySlug` ends up
 | 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`. |
+| 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`. |

package/skills/wix-headless/references/{stores → astro/stores}/SHARED_WIRING.md

@@ -1,8 +1,8 @@
 # Phase 3 Components — Stores (TSX/Astro)
 
-Launched in **Step 4.5** (after Phase 2 Design System completes, parallel to any running designer page scopes). Writes code that depends on the **design tokens** but NOT on Phase 4 page markup. Finishes before the Phase 4 Pages scopes run in Step 7.
+This is the **components** portion of the stores **merged build agent** (the build wave — `BUILD-astro.md` § "Step 4.5"). Your agent writes these islands **first**, then the stores pages (`pages-categories`, `pages-products`) that mount them — so the islands are on disk before the page code references them. The code here depends on the **design tokens** (read from `.wix/design-tokens.css` on disk) but NOT on page markup.
 
-> **CSS lives in a sibling scope.** `src/styles/components-stores.css` is owned by the `components-css` scope (see `./COMPONENTS_CSS.md`), which runs concurrently with this one in the same Step 4.5 batch. This scope does NOT write the CSS file. Reference contract class names from the design tokens here; the CSS sibling defines the rules.
+> **CSS is pre-copied, not authored.** `src/styles/components-stores.css` ships from the skill template, copied by the orchestrator in the build-wave pre-batch (see `./COMPONENTS_CSS.md`). This scope does NOT write the CSS file. Reference its contract class names from the design tokens here; the pre-copied stylesheet defines the rules.
 
 ## Scope
 
@@ -17,14 +17,15 @@ Files this agent MUST NOT touch:
 - `src/styles/components-stores.css` — owned by the **`components-css`** sibling scope (see `./COMPONENTS_CSS.md`). Reference its class names; do not write the file.
 - `src/utils/wix-image.ts` — **shared utility shipped by the build skill.** Import `resolveWixImageUrl` from `../utils/wix-image`; do NOT write your own copy (would shadow the shared util and drop other verticals' callers). The canonical source lives at `<SKILL_ROOT>/shared-utilities/wix-image.ts`; it's copied into projects by `seed-utilities.sh` during Setup.
 - `src/components/CartView.tsx`, `src/components/CartBadge.tsx`, `src/utils/analytics.ts`, `src/styles/components-ecom.css` — owned by ecom
-- Any `.astro` page — those are designed and later rewritten by other scopes
+- `src/utils/back-in-stock.ts` — **pre-copied by the orchestrator** in the build-wave pre-batch (BUILD-astro.md § "Step 4.5"), same as `categories.ts`. Import `getBackInStockEnabled`/the app-id constants from `../utils/back-in-stock`; never `Write` it (see `./BACK_IN_STOCK.md`).
+- Any `.astro` page — written by your agent's `pages-*` scopes (after the islands) or by another vertical
 - `src/styles/global.css` — owned by designer foundation
 - `src/layouts/Layout.astro` — owned by designer foundation (including the `components-stores.css` import line)
 - Any designed component (`ProductCard.astro`, `Navigation.astro`, etc.) — owned by designers
 
 ## Coordination: design tokens
 
-Your parent prompt includes the design tokens inline. Use it directly — do **not** read `.wix/design-tokens.css` + `.wix/site.d.ts` from disk and do not poll for it. The parent skill serializes your launch behind designer foundation specifically so the contract is already available in your prompt when you start.
+Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave). The parent skill serializes your launch behind the designer foundation specifically so this file is already written when you start.
 
 Reference the ACTUAL class names from the contract in React components (e.g. `className="add-to-cart-btn"`, not `className="addToCartButton"` or an invented name). See `references/shared/IMPLEMENTER.md` § "Contract class-name adaptation" for the full rule.
 
@@ -94,7 +95,7 @@ Handles variant selection, quantity selector, stock awareness, and wraps `AddToC
 <ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} />
 ```
 
-**Prop contract — single `product` object.** The template accepts the full productsV3 product and destructures internally. This mirrors `ProductCard.astro`'s `{ product }` contract so both stores components take the same shape (prevents the regression observed in an earlier run where a fallback-written `[slug].astro` passed `product` as a whole when the component expected flat props).
+**Prop contract — single `product` object.** The template accepts the full productsV3 product and destructures internally. This mirrors `ProductCard.astro`'s `{ product }` contract so both stores components take the same shape (prevents a shape mismatch where a fallback-written `[slug].astro` passes `product` as a whole while the component expects flat props).
 
 Key behaviors:
 - `hasMeaningfulOptions` — a product has meaningful options only when at least one option has >1 choice. Dummy single-choice options (e.g., "Type: Standard") are treated as no options.
@@ -159,6 +160,6 @@ Classes from contract (stores pack):
 | Default Tailwind color utilities on React islands (`bg-green-50`, `bg-blue-500`) | Brand `@theme` utilities (`bg-bark`, `text-cream`) or contract class names |
 | `<!--` HTML comments in `.astro` frontmatter | `//` or `/* */` — frontmatter is TypeScript |
 | Omit `WIX_STORES_APP_ID` constant | Hardcoded `215238eb-22a5-4c36-9e7b-e7c08025e04e` in AddToCartButton for `catalogReference.appId` |
-| Introspect `node_modules/@wix/*` | All symbols are documented here; if missing, call `<prefix>SearchWixSDKDocumentation` |
+| Introspect `node_modules/@wix/*` | All symbols are documented here; if missing, use docs-search REST (see `DOCS_SEARCH.md`) |
 | Write `CartView.tsx`, `CartBadge.tsx`, or `analytics.ts` | Not owned by this scope — do not write |
-| Pass flat props to `ProductPurchase` (`productId`, `options`, `variantsInfo`, …) | Pass the whole product: `<ProductPurchase product={product} inventoryByVariant={inventoryByVariant} />` |
+| Pass flat props to `ProductPurchase` (`productId`, `options`, `variantsInfo`, …) | Pass the whole product: `<ProductPurchase product={product} inventoryByVariant={inventoryByVariant} />` |

package/skills/wix-headless/references/astro/templates/Footer.astro

@@ -0,0 +1,27 @@
+---
+// ── Composer skeleton: src/components/Footer.astro ────────────────────────────
+// Substitutions (see compose.mjs):
+//   {{brand.name}} — brand name for the wordmark + copyright.
+//   {{shell.footerTagline}} — short brand-voice tagline from data.shell.
+//   {{nav.links}} — same inlined Navigation links array (mirror/subset);
+//        one <a href={href}>{label}</a> per entry, labels VERBATIM. No cart,
+//        login, or account links.
+// Fixed bulk (keep literal): transition:persist, the year expression.
+const year = new Date().getFullYear();
+---
+<footer class="site-footer" transition:persist="site-footer">
+  <div class="max-w-6xl mx-auto px-lg py-3xl flex flex-col md:flex-row md:items-start md:justify-between gap-xl">
+    <div class="flex flex-col gap-sm max-w-prose">
+      <span class="font-display text-lg text-ink">{{brand.name}}</span>
+      <p class="text-sm">{{shell.footerTagline}}</p>
+    </div>
+    <nav>
+      <ul class="flex flex-col gap-sm text-sm">
+        {{nav.links}}
+      </ul>
+    </nav>
+  </div>
+  <div class="max-w-6xl mx-auto px-lg pb-xl text-xs">
+    <p>© {year} {{brand.name}}. All rights reserved.</p>
+  </div>
+</footer>

package/skills/wix-headless/references/astro/templates/Layout.astro

@@ -0,0 +1,132 @@
+---
+// ── Composer skeleton: src/layouts/Layout.astro ──────────────────────────────
+// Fully replaces the scaffold's bare stub. The <script> below and the View
+// Transitions wiring are LITERAL fixed bulk — do not re-author. Composer's only
+// substitutions (see compose.mjs):
+//   {{components-css-imports}} — one `import '../styles/components-<pack>.css';`
+//        per pack in "Packs with components" (omit entirely when none).
+//   {{fonts.googleHref}} — the Google Fonts <link> href built from designTokens
+//        .fonts (display + body families). Omit the <link> if fonts are system.
+//   {{brand.name}} — default <title>.
+import '../styles/global.css';
+{{components-css-imports}}
+import { ClientRouter } from 'astro:transitions';
+import Navigation from '../components/Navigation.astro';
+import Footer from '../components/Footer.astro';
+
+interface Props {
+  title?: string;
+  description?: string;
+  hasSeoTags?: boolean;
+}
+const { title, description, hasSeoTags = false } = Astro.props;
+---
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'/%3E" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link rel="stylesheet" href="{{fonts.googleHref}}" />
+    {!hasSeoTags && (
+      <>
+        <title>{title ? `${title} · {{brand.name}}` : "{{brand.name}}"}</title>
+        {description && <meta name="description" content={description} />}
+      </>
+    )}
+    <slot name="head" />
+    <ClientRouter />
+  </head>
+  <body>
+    <div class="nav-progress" data-nav-progress aria-hidden="true"></div>
+    <Navigation />
+    <main><slot /></main>
+    <Footer />
+    <script>
+      // Persisted rail aria-current sync + top loading bar + rail-anchored
+      // scroll across listing-to-listing navigation. Stores pack relies on
+      // all three; do not split into separate scripts.
+      function syncCategoryRail() {
+        const path = window.location.pathname;
+        const activeSlug = path.startsWith("/category/")
+          ? path.slice("/category/".length).replace(/\/$/, "")
+          : path === "/products" || path === "/products/"
+            ? ""
+            : null;
+        if (activeSlug === null) return;
+        const pills = document.querySelectorAll<HTMLAnchorElement>(
+          "[data-category-rail] .category-pill",
+        );
+        for (const pill of pills) {
+          const slug = pill.dataset.categorySlug ?? "";
+          if (slug === activeSlug) pill.setAttribute("aria-current", "page");
+          else pill.removeAttribute("aria-current");
+        }
+      }
+      // Eager click feedback — flip aria-current before the network call.
+      document.addEventListener("click", (event) => {
+        const target = event.target as HTMLElement | null;
+        const pill = target?.closest<HTMLAnchorElement>(
+          "[data-category-rail] .category-pill",
+        );
+        if (!pill) return;
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+        const pills = document.querySelectorAll<HTMLAnchorElement>(
+          "[data-category-rail] .category-pill",
+        );
+        for (const p of pills) p.removeAttribute("aria-current");
+        pill.setAttribute("aria-current", "page");
+      }, true);
+      const progress = document.querySelector<HTMLElement>("[data-nav-progress]");
+      function startProgress() {
+        if (!progress) return;
+        progress.dataset.state = "loading";
+        document.body.dataset.navigating = "true";
+      }
+      function endProgress() {
+        if (!progress) return;
+        progress.dataset.state = "done";
+        delete document.body.dataset.navigating;
+        window.setTimeout(() => {
+          if (progress.dataset.state === "done") delete progress.dataset.state;
+        }, 320);
+      }
+      // Anchor the persisted rail across listing-to-listing navigation. The
+      // page-header above the rail differs between /products and /category/[slug]
+      // (breadcrumbs, lede, optional image), so naive scroll preservation reads
+      // as a jump. Capture rail.getBoundingClientRect().top before the swap and
+      // re-equalize after.
+      const isListing = (p: string) =>
+        p === "/products" || p === "/products/" || p.startsWith("/category/");
+      let railAnchorTop: number | null = null;
+      document.addEventListener("astro:before-preparation", (event: any) => {
+        const from = window.location.pathname;
+        const to = event?.to?.pathname ?? from;
+        const rail = document.querySelector<HTMLElement>("[data-category-rail]");
+        railAnchorTop =
+          rail && isListing(from) && isListing(to)
+            ? rail.getBoundingClientRect().top
+            : null;
+        startProgress();
+      });
+      document.addEventListener("astro:after-swap", () => {
+        syncCategoryRail();
+        if (railAnchorTop !== null) {
+          const rail = document.querySelector<HTMLElement>("[data-category-rail]");
+          if (rail) {
+            const delta = rail.getBoundingClientRect().top - railAnchorTop;
+            if (Math.abs(delta) > 0.5) {
+              window.scrollBy({ top: delta, left: 0, behavior: "instant" as ScrollBehavior });
+            }
+          }
+        }
+        railAnchorTop = null;
+        endProgress();
+      });
+      document.addEventListener("astro:page-load", endProgress);
+      syncCategoryRail();
+    </script>
+  </body>
+</html>