@wix/agent-skills 1.13.0 → 1.15.0

package/skills/wix-headless/references/shared/RETURN_CONTRACT.md

@@ -1,143 +0,0 @@
-# Agent Return Contract
-
-Coordination between agents uses **in-memory structured returns**, not sidecar files (`.wix/logs/*.md`, `.wix/seed-returns/*.json`, `.wix/image-urls.md`). Every agent returns a JSON block at the end of its completion message; the skill parses these returns directly from session context.
-
-The orchestrator consumes each return directly from context; nothing is aggregated to disk. The one end-of-run file is the project-root `AGENTS.md` (see `references/shared/AGENTS_MD.md`) — content about the site, not telemetry.
-
-This document is the **universal envelope** every agent shares: the rules, the JSON skeleton, status semantics, and the generic failure shape. **The phase-specific `data` shape you must emit does NOT live here — it lives in your own role doc** (the one your scope already reads). See the index at the bottom.
-
-## The JSON return is your sole output channel
-
-Subagents MUST NOT write coordination files (`.wix/seed-returns/<pack>.json`, `.wix/image-urls.md`, `.wix/logs/*.md`, etc.). The orchestrator parses your fenced JSON block from the message body and either acts on the data directly or pipes it to a deterministic helper script via stdin (e.g. `emit-design-tokens.mjs`, `patch-decorative-slots.mjs`). Any data the orchestrator needs from you belongs under `data` in the return block — files in `.wix/` that aren't build-consumed (CSS, .d.ts) or external-system-owned (`wix.config.json`) are not part of the contract.
-
-## Why structured returns, not files
-
-Writing markdown files between agents assumes they're independent processes without shared memory. But subagents run as child model calls under the parent skill's context — they can return structured data directly. File-based coordination adds:
-
-- ~10s per sidecar write (file I/O + narration)
-- ~5s per sidecar read from the parent (another tool call)
-- Coordination complexity (timing, status-line parsing, retry logic)
-
-That overhead is pure critical-path cost with no benefit here.
-
-## The contract
-
-Every subagent's final message ends with a fenced JSON block (language tag: `json` or `jsonc`). Format:
-
-~~~markdown
-... agent's human-readable summary ...
-
-```json
-{
-  "status": "complete" | "partial" | "failed",
-  "phase": "<phase identifier — see your role doc's Returns section for the exact value>",
-  "scope": "<scope string from the agent's prompt>",
-  "summary": "<one-line description of what was done>",
-  "data": { ... phase-specific structured data — shape defined in your role doc ... },
-  "files": ["list", "of", "files", "written", "or", "modified"],
-  "errors": [],
-  "notes": "<optional — anything the parent skill should know>"
-}
-```
-~~~
-
-The JSON block MUST be the **last** content in the message. The parent skill parses the last fenced JSON block as the return.
-
-### Timing is NOT the agent's responsibility
-
-Agents don't self-report timing or status — the return is just `data`. Emit no `started`/`ended` timestamps; any wall-clock measurement is the harness's job, taken from the session trace.
-
-### No trailing prose after the fenced JSON
-
-The fenced JSON block must be the **last** content in the message. A trailing sentence — or no block at all — means the parent skill has to reconstruct `data.products` etc. from narrative text. That's fragile, and when a later phase relies on pre-seeded data from earlier returns, a missing block means downstream agents don't get their data inline and fall back to re-querying the REST API, costing 5–15s each.
-
-**Correct pattern — end with the fenced block, no trailing prose:**
-
-~~~markdown
-✅ CORRECT
-
-All files written. Contract classes referenced: productCard, productGrid, optionPill, quantityBtn.
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-components",
-  "scope": "components",
-  "summary": "Wrote React islands + utils; contract classes referenced: 11",
-  "data": { ... },
-  "files": [ ... ],
-  "errors": []
-}
-```
-~~~
-
-~~~markdown
-❌ WRONG — trailing prose after the block
-
-```json
-{ "status": "complete", ... }
-```
-
-All three files are correctly written. Let me verify the key requirements are met before returning.
-~~~
-
-The parent skill looks for the **last** fenced JSON block in the message. A trailing sentence means it's no longer the last content; scanning falls back to heuristics. Just stop writing after the closing ` ``` `.
-
-## Status semantics
-
-| Status | Meaning | Parent action |
-|--------|---------|---------------|
-| `complete` | All work done successfully | Proceed to next phase |
-| `partial` | Some work done, some failed — `errors` explains | Decide per-case: retry, work around, or fail the run |
-| `failed` | Nothing usable produced — `errors` explains | Retry with corrective prompt or fail the run |
-
-## Failure returns
-
-On `failed` or `partial`, `errors` is populated and `data` may still contain partial results:
-
-```json
-{
-  "status": "partial",
-  "phase": "stores-pages-products",
-  "errors": [
-    {
-      "file": "src/pages/products/[slug].astro",
-      "code": "MISSING_SEO_DATA",
-      "message": "product.seoData was null; fell back to product.name for <title>",
-      "severity": "warning"
-    }
-  ],
-  "data": {...}
-}
-```
-
-Severity levels: `warning` (keep running), `error` (parent should retry), `fatal` (parent must stop).
-
-## Where your phase-specific `data` shape lives
-
-The envelope above is universal. The exact `data` shape — plus the known `error.code` values and required `files` — lives in **your role doc**, the one your scope already reads. Do not look for them here; read your own doc. This keeps each shape single-sourced (no drift) and means you never load shapes for phases you don't emit.
-
-| Your agent / scope | `phase` value(s) | Shape lives in |
-|---|---|---|
-| Seed — stores | `stores-seed` | `references/stores/INSTRUCTIONS.md` § Seed return |
-| Seed — CMS | `cms-seed` | `references/cms/INSTRUCTIONS.md` § Seed return |
-| Seed — other verticals | `<pack>-seed` | per-vertical `INSTRUCTIONS.md` (same generic shape as stores) |
-| Components | `<pack>-components` | `references/shared/IMPLEMENTER.md` § Return contract |
-| Pages | `<pack>-pages[-<group>]` | `references/shared/IMPLEMENTER.md` § Return contract |
-| Design System Designer | `design-system` | `references/DESIGN_SYSTEM.md` § What you write and return |
-| Design System Composer (`scripts/compose.mjs`, not a subagent — manifest printed to stdout) | `compose` | `scripts/compose.mjs` header (the manifest shape) |
-| Page Designer | `designer-<scope>` | `references/astro/designer/INSTRUCTIONS.md` (per-scope) |
-| Images | `image-phase-1-decorative`, `image-phase-2-entity` | `references/images/INSTRUCTIONS.md` § Return Contract |
-
-The **orchestrator** is the one audience that needs every shape — it parses each return directly; there is no aggregated file. This table is its index.
-
-## Notes for agent authors
-
-When writing a new agent, put a **Returns** section in its role doc (`INSTRUCTIONS.md` or equivalent) listing:
-
-1. The `phase` identifier this agent emits
-2. The exact `data` shape for successful returns
-3. Known `error.code` values
-4. Required `files` entries
-
-Then add a row to the index table above so the orchestrator can find it. Do **not** copy the shape back into this file — one source per shape. Produce the JSON return block deterministically; don't let creative prose overrun the fenced block. Parent skill parsing assumes the JSON is well-formed and complete and is the **last** content in the message.

package/skills/wix-headless/references/shared/STYLING.md

@@ -1,141 +0,0 @@
-# Styling — Three Categories, One Default
-
-Every visual decision in a generated site falls into one of three categories. Each has a single owner and a single home. This file is the canonical reference; `DESIGN_SYSTEM.md` (Designer), `scripts/compose.mjs` (Composer — deterministic script, self-documenting), `astro/designer/INSTRUCTIONS.md` (Phase 4 page designers), and `IMPLEMENTER.md` link here.
-
-> **Design-system ownership (the design-vs-application split).** The **Designer** (`DESIGN_SYSTEM.md`) owns the token *values* and their *completeness* — a coherent, complete brand visual authored as a **DESIGN.md** (`data.design`; format spec in `shared/DESIGN_MD.md`). The **Composer** (`scripts/compose.mjs`; self-documenting) owns the *application* — it writes the `@theme` block in `global.css` from those values (mapping each semantic role to a `--var` name) and guarantees the required-token contract below resolves. Component and page authors still compose those tokens as Tailwind utilities at their call sites. So: Designer picks "paper = `#FAF6EF`"; Composer writes `--color-paper: #FAF6EF` into `@theme`; a page writes `class="bg-paper"`.
-
-## The three categories
-
-| Category | Lives in | Owned by | Use for |
-|---|---|---|---|
-| **Tokens (composed as utilities)** | the canonical `DESIGN.md` + its projections: the `@theme` block in `src/styles/global.css` (written by `scripts/compose.mjs`), plus `.wix/design-tokens.css` and `.wix/site.d.ts` (written by `scripts/emit-design-tokens.mjs`) — all from Designer's `DESIGN.md` | Designer picks values (Phase 2); `compose.mjs` writes `@theme` | All color, typography scale, radii, aspect ratios, shadows, transitions (spacing is Tailwind's built-in numeric scale). Pages compose tokens at call sites as Tailwind utilities — `class="py-24 bg-sand aspect-[16/5]"`. |
-| **Global semantic classes** | `src/styles/global.css` (outside `@theme`) and `src/styles/components-<pack>.css` | Designer + Phase 3 component agents | Compound multi-element patterns, interactive states (`:hover`, `:focus`, `:disabled`), and JS/React DOM query targets. |
-| **Co-located styles** | `<style>` block at the bottom of the same `.astro` file (or component CSS module for islands) | Page or component author | One-off page decoration: hero stamps, custom dividers, ornamental overlays that won't be reused elsewhere. |
-
-## Default direction
-
-**Tokens-as-utilities is the default.** When you're about to write a class for layout, spacing, typography, alignment, simple background/text color, or aspect ratio, write Tailwind utilities derived from `@theme` instead. The site's design tokens give you `bg-paper-warm`, `text-ink`, `font-display`, `aspect-[16/5]` etc.; spacing is Tailwind-numeric (`py-24`, `gap-3`). Compose them in markup; do not invent semantic classes for these concerns.
-
-The token namespace is the contract. The design tokens (the DESIGN.md token vocabulary — `colors`/`typography`/`rounded`/`containers`) live on disk at `.wix/design-tokens.css` (gate-verified present before the build wave) — **read that file at the start of any pages or components scope** to know which tokens this run published. The orchestrator does **not** inline them in your prompt. (`.wix/site.d.ts` is also on disk for the build.) If a token you need isn't in `.wix/design-tokens.css`, that's a designer-side gap — flag it in your return JSON, don't paper over it with a custom class.
-
-## Decision tree
-
-When you find yourself reaching for a `class="..."` value, ask:
-
-1. **Can this be expressed as 2–4 Tailwind utilities derived from `@theme`?** → Use utilities. Don't create a class.
-2. **Is it a compound multi-element pattern** (e.g., a bordered card with header + body + foot rules), an **interactive state** (`:hover`/`:focus`/`:disabled`/`:hover .child`), or a **JS query target** the DOM is inspected for? → Global semantic class in `global.css` (designer-owned) or `components-<pack>.css` (Phase 3 components agent-owned).
-3. **Is it a one-off page decoration** that won't be reused on any other route? → Co-located `<style>` block at the bottom of the same `.astro` file. Reference tokens via `var(--color-foo)` from `:root` (auto-loaded by `design-tokens.css`).
-
-If none fit, you're probably trying to do something the tokens don't support yet — talk to the designer (for new runs, return a `MISSING_TOKEN` error; for existing projects, add the token to `@theme`).
-
-## What does NOT belong as a global semantic class
-
-These are layout/spacing/typography concerns that should always be utilities, never standalone classes:
-
-- Section padding / margins (`py-24`, `mt-16`, `mb-12`)
-- Flex / grid layouts (`flex flex-col gap-4`, `grid grid-cols-3 gap-6`)
-- Aspect ratios (`aspect-[4/5]`, `aspect-square`)
-- Plain typography choices (`text-display-lg font-display`, `text-mute uppercase tracking-wide`)
-- Background / foreground color application without state (`bg-paper`, `text-ink-soft`)
-- Container widths (`max-w-prose`, `max-w-6xl`, `max-w-3xl`, `w-full`) — these resolve to the `--container-*` keys the designer declared.
-
-### Spacing & reading width
-
-**Spacing is Tailwind's built-in numeric scale** — `gap-4`, `py-24`, `px-6`, `mt-16`, etc. There is **no** named `--spacing-<size>` scale (it was removed: its t-shirt names `md`/`3xl`/… collided with the width utilities, so `max-w-3xl` resolved to `--spacing-3xl` ≈ 96px). Common steps: `1`=0.25rem, `2`=0.5, `3`=0.75, `4`=1rem, `6`=1.5, `8`=2, `12`=3, `16`=4, `24`=6rem.
-
-> **Never reintroduce a named `--spacing-*` scale.** In Tailwind v4 the `--spacing-*` namespace also generates the width/sizing families (`max-w-*`, `w-*`, `min-w-*`, …), so any `--spacing-<key>` token shadows the matching `max-w-<key>`. The current fix works because the skill's spacing steps happen to equal Tailwind's numeric defaults — but if a brand ever needs genuinely *custom* spacing **values**, put them under a different namespace (e.g. `--rhythm-*`) or use arbitrary values (`py-[5.5rem]`); do not revive `--spacing-*`.
-
-**Width / reading columns:** `max-w-md`, `max-w-3xl`, `max-w-6xl`, `max-w-prose` now resolve correctly to the `--container-*` keys (no spacing collision), so use them freely; `container-reading` (the designer `@utility`) or an arbitrary `max-w-[48rem]` also work.
-
-If a designer's `global.css` contains rules like `.featured-section { padding-block: 6rem; }` or `.product-card-body { display: flex; flex-direction: column; gap: 0.5rem; }`, those are misplaced — they belong in markup as utilities (`py-24`, `flex flex-col gap-2`). Inventing such classes ships broken layouts: every consumer needs the designer to have pre-declared the class, and Tailwind v4 silently drops the references when the rule is missing.
-
-## Required tokens — the component-CSS template contract
-
-The per-pack `components-<pack>.css` templates at `<SKILL_ROOT>/references/astro/templates/<pack>/components-<pack>.css` reference a fixed set of CSS custom properties via `var(--token)` (never `@apply`). Those templates are copied verbatim into the project by the orchestrator at BUILD-astro.md § Step 4.5, so **the Composer's `@theme` block MUST declare every token below** for the build to pass (the Composer maps the Designer's framework-agnostic spec onto these `--var` names, deriving any required role the Designer omitted). If a token is missing, the rule that references it collapses silently and the corresponding component renders unstyled (or worse, half-styled).
-
-| Token | Required? | Fallback in templates | Used by |
-|---|---|---|---|
-| `--color-paper` | **required** | — | every pack — primary background |
-| `--color-paper-warm` | **required** | `var(--color-paper, var(--color-cream))` | stores summary bg, ecom cart-summary bg, gift-cards |
-| `--color-ink` | **required** | — | every pack — primary text + dark fills |
-| `--color-ink-soft` | optional | `var(--color-mute)` | stores option-label, ecom cart-item-option |
-| `--color-mute` | **required** | — | every pack — muted text + remove buttons |
-| `--color-rule` | **required** | — | every pack — borders + dividers |
-| `--color-accent` | **required** | — | every pack — brand emphasis |
-| `--color-cream` | optional | inner fallback in `var(--color-paper-warm, var(--color-paper, var(--color-cream)))` | stores form bg, gift-cards |
-| `--color-error` | optional | `var(--color-accent)` or hardcode | ecom cart-item-unavailable, stores back-in-stock-error |
-| `--font-display` | **required** | — | every pack — headings + labels |
-| `--font-body` | **required** | — | every pack — body text + UI |
-| `--radius-sm`, `--radius-md` | **required** | — | buttons, inputs, cards |
-| `--radius-lg`, `--radius-xl` | optional | — | stores product-card |
-
-The templates do NOT use `@apply` — every rule is `property: var(--token);` directly. This means missing utilities don't fail at build time (the way `@apply gap-3` would). Missing tokens degrade silently to `var(missing) → unset → initial`. That makes the failure mode "ugly component" not "broken build" — easier to recover from but harder to detect, so verify the full set above is in `@theme` before returning.
-
-**Why this contract exists.** The component templates are authored against a stable, brand-agnostic token vocabulary so they don't need to be regenerated per run. Using `@apply` against brand-specific tokens (e.g. `bark`, `cream`, `parchment`) that designers don't publish fails the build with `Cannot apply unknown utility class`. Direct `var()` against the required-token list above avoids that class of failure entirely.
-
-## What DOES belong in `global.css` (designer-owned)
-
-The designer's `global.css` is small — tokens plus a short list of truly cross-cutting patterns. Anything specific to a single vertical's component (a product card, a cart row, a discount callout) does NOT belong here. Those live with the component, in `components-<pack>.css` (Phase 3 components agent-owned) or in a co-located `<style>` block inside the component's `.astro` file.
-
-The retained set:
-
-- **Button family** — `btn`, `btn-primary`, `btn-secondary`, `btn-ghost`. Compound + `:hover`/`:disabled`. Used on every page across every vertical.
-- **`[data-decorative-slot]`** — cross-cutting decorative pattern; the orchestrator injects images here regardless of vertical.
-- **`editorial-rule`** — cross-cutting decorative pattern (gold-rule / accent dividers used by hero/section dividers across verticals).
-- **Site shell shells** — `.site-nav`, `.site-footer`, `.nav-progress`. Sticky header, footer scaffold, top progress bar — universal site chrome with markers that verticals contribute into via `<!-- nav:links -->` etc.
-
-That's it. The full list of always-required classes for a site lives in designer `INSTRUCTIONS.md`; this file states the principle.
-
-## Component-specific CSS is owned by the component, not the designer
-
-The boundary that causes leaks: if the designer publishes partial rules for `.product-card`, `.product-grid`, `.product-card-media`, `.offer-callout`, `.cart-summary`, etc. — all classes used by exactly one vertical's component — the designer doesn't know how those components should be laid out for a particular brand, so the rules ship as stubs and templates quietly add the missing layout in scoped CSS. The same class then behaves differently on different pages (e.g. `/products` rendering with `.product-grid { transition: opacity }` and no `display: grid`, while `/category/<slug>` defines a separate scoped `.product-grid` with the actual grid).
-
-The fix is structural: move component-specific CSS out of `global.css` entirely.
-
-| What | Where it lives | Owner |
-|---|---|---|
-| `.product-card`, `.product-card-media`, `.product-card-ribbon`, `.product-card-index`, `.product-grid` | `src/styles/components-stores.css` | Stores Phase 3 components agent (or scoped `<style>` in the component's `.astro`) |
-| `.offer-callout` family (`-item`, `-badge`, `-name`, `-detail`, `-foot`) | `src/styles/components-stores.css` | Stores Phase 3 components agent |
-| `.cart-summary`, `.cart-total`, `.cart-empty`, `.checkout-btn` | `src/styles/components-ecom.css` | Ecom Phase 3 components agent |
-| Anything used by exactly one component | Co-located `<style>` block in the component's `.astro` or the matching `components-<pack>.css` | The pack that owns the component |
-
-The Phase 3 components agents already write to `components-<pack>.css` (the file is imported by the designer's `Layout.astro` from the start). This change just makes it the *only* place those classes live — no parallel partial rule in `global.css`.
-
-### Pre-return checklist for the Composer
-
-`compose.mjs` writes `global.css` by substituting the `@theme` palette into a pinned skeleton, so this leak is **structurally prevented** — the skeleton declares no `.product-card`/`.cart-summary`-family rules and the script never adds any. The grep below is a maintainer guard for when the skeleton itself is edited; confirm it declares none of these:
-
-```
-grep -r --include="*.astro" --include="*.tsx" -lE "class(\\Name)?=.*(\\.|\\b)(product-card|product-grid|product-card-media|product-card-ribbon|product-card-index|offer-callout|cart-summary|cart-total|cart-empty|checkout-btn)\\b" $SKILL_ROOT/references/astro/templates/*/
-```
-
-For any listed class the Composer's `global.css` declares: if a template references it, move the rule to the appropriate `components-<pack>.css` template (or a scoped `<style>` block). Do NOT ship a partial rule in `global.css` that the template "completes".
-
-## Co-located styles — the locality default for one-offs
-
-Astro's `<style>` blocks scope automatically to the `.astro` file by default — no class-name collision risk across routes. When a page needs decoration that doesn't fit utilities and isn't reusable, the rule lives next to its only caller:
-
-```astro
-<section class="relative py-24">
-  <div class="hero-stamp">Made in small batches</div>
-</section>
-
-<style>
-  .hero-stamp {
-    position: absolute;
-    bottom: 1.5rem;
-    right: 1.5rem;
-    background: rgba(27, 26, 23, 0.75);
-    color: var(--color-paper);
-    padding: 0.5rem 0.875rem;
-    font-family: var(--font-display);
-    font-style: italic;
-  }
-</style>
-```
-
-No coordination with the designer needed; no entry to forget on the always-required list. If this stamp later becomes a pattern used on three routes, *then* promote it to a global semantic class.
-
-## Why this protocol
-
-The bug class this prevents: markup writers (designer's shells, vertical pages agents, committed templates) and the CSS writer (designer's `global.css`) operate in different phases with no handshake. When the markup writer types a class string the CSS writer didn't pre-declare, Tailwind v4 silently drops it and ships a site with broken styling. Tokens-as-utilities collapses that handshake — there's no class to forget, only utilities derived from a token list everyone reads.

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

@@ -1,126 +0,0 @@
----
-name: stores-implementer
-description: "Implements Wix Stores vertical — product catalog, categories, add-to-cart, product pages. Scopes: seed, components, components-css, pages-products, pages-categories, pages-home-and-nav. Extends references/shared/IMPLEMENTER.md."
----
-
-# Stores Implementer
-
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, prompt-inlined inputs (read only your `.wix/seeded.json` slice), return contract, style conventions, and common failure modes.
-
-## Scope routing
-
-| Scope | Phase | Reference |
-|-------|-------|-----------|
-| `seed` | Seed (REST catalog setup — products only; categories are merchant-driven, not seeded) | `./PRODUCT_CATALOG_DATA.md` |
-| `components` | Components (React islands + SeoTags + back-in-stock util — TSX/Astro only, **no CSS**) | `../astro/stores/SHARED_WIRING.md` |
-| ~~`components-css`~~ | **Do not dispatch.** `src/styles/components-stores.css` is copied from `<SKILL_ROOT>/references/astro/templates/stores/components-stores.css` by the orchestrator's pre-Step-4.5 batch (see BUILD-astro.md § Step 4.5). The template uses direct `var(--token)` CSS, so it works against any designer-published vocabulary without per-run rewrites. `COMPONENTS_CSS.md` documents that CSS for reference — there is no `components-css` subagent to dispatch. | — |
-| `pages-categories` | Pages (`/category/[slug]` listing + shared CategoryRail + `utils/categories.ts`) | `../astro/stores/CATEGORY_PAGES.md` |
-| `pages-products` | Pages (products listing + detail + ProductCard; mounts the rail written by `pages-categories`) | `../astro/stores/PRODUCT_PAGES.md` |
-| `pages-home-and-nav` | Pages (home-page contribution + Shop submenu in Navigation) | `../astro/stores/HOME_AND_NAV.md` |
-
-> **Why `components` is TSX/Astro-only.** The scoped CSS (`src/styles/components-stores.css`) has no runtime coupling to the TSX components — it's referenced only by class name at build time — so it ships pre-copied from the template by the orchestrator (see § "CSS ownership" below) rather than being written by an agent. The `components` agent gets a smaller reading set and a smaller write list. See `../astro/stores/COMPONENTS_CSS.md` § "What this scope owns".
-
-## Files this vertical creates / contributes
-
-See the § "Templates" list below for the canonical files each scope reads and adapts.
-
-## Seed return
-
-The `seed` scope emits this `data` shape in its return JSON (envelope rules in `../shared/RETURN_CONTRACT.md`). Phase 4 page agents consume `data.products[*].slug` and `data.products[*].variantId` to wire live SDK queries.
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-seed",
-  "scope": "seed",
-  "summary": "Deleted 12 default products; created 3 on-brand products with variants",
-  "data": {
-    "products": [
-      {
-        "id": "2d1bce83-...",
-        "name": "Tero Dining Table",
-        "slug": "tero-dining-table",
-        "variantId": "ffc1caa2-...",
-        "price": 2890,
-        "inventory": 12,
-        "sku": "TAB-TERO-OAK"
-      }
-    ],
-    "deletedCount": 12,
-    "createdCount": 3
-  },
-  "files": [],
-  "errors": []
-}
-```
-
-## Pre-return file-existence assertion (all page scopes)
-
-Before returning `status: "complete"` from any `pages-*` scope, verify every file your scope produces (per the § "Templates" list below) exists on disk. Silently dropping a file (e.g. `[slug].astro` from `pages-products`) reports `complete` to the orchestrator, but every product link 404s at runtime.
-
-If a declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]` rather than claiming success. The orchestrator's Step 8.0.5 manifest check will also catch this, but an agent-side assertion gives a faster and more precise failure.
-
-## Templates
-
-Canonical templates live at `<SKILL_ROOT>/references/astro/templates/stores/`. Your `components` and `pages-*` scopes read these and adapt them — don't invent markup or logic.
-
-Components (`components` scope — TSX/Astro only):
-- `<SKILL_ROOT>/references/astro/templates/stores/AddToCartButton.tsx`
-- `<SKILL_ROOT>/references/astro/templates/stores/ProductPurchase.tsx`
-- `<SKILL_ROOT>/references/astro/templates/stores/BackInStockForm.tsx`
-- `<SKILL_ROOT>/references/astro/templates/stores/SeoTags.astro`
-
-Components CSS (pre-copied by the orchestrator — no agent writes it):
-- `<SKILL_ROOT>/references/astro/templates/stores/components-stores.css`
-
-Pages (`pages-products` scope):
-- `<SKILL_ROOT>/references/astro/templates/stores/ProductCard.astro`
-- `<SKILL_ROOT>/references/astro/templates/stores/products/index.astro`
-- `<SKILL_ROOT>/references/astro/templates/stores/products/[slug].astro`
-
-Pages (`pages-categories` scope):
-- `<SKILL_ROOT>/references/astro/templates/stores/CategoryRail.astro`
-- `<SKILL_ROOT>/references/astro/templates/stores/category/[slug].astro`
-
-### Pre-copied by the orchestrator (do NOT write these yourself)
-
-The following utility files are deterministically copied by the orchestrator BEFORE your phase dispatches (`components` for the first, `pages` for the second). They are mechanical SDK wrappers with no brand-specific content; reading or rewriting them as part of your scope wastes tokens and risks drift. Just import the helpers at the listed paths:
-
-- `src/utils/back-in-stock.ts` — pre-copied from `<SKILL_ROOT>/references/astro/templates/stores/back-in-stock.ts` before `components` dispatches.
-- `src/utils/categories.ts` — pre-copied from `<SKILL_ROOT>/references/astro/templates/stores/categories.ts` before `pages` dispatches.
-
-If you find one of these missing at runtime, that's an orchestrator-side bug — return `status: "partial"` with `errors: [{code: "UTILITY_TEMPLATE_NOT_PRECOPIED", path: "<missing>"}]` and continue. Do NOT write your own version; the post-phase manifest check will recover by template-copy and the right helper lands on disk.
-
-## CSS ownership — stores pack
-
-Stores-specific component CSS lives in `src/styles/components-stores.css` (pre-copied from the template by the orchestrator before Step 4.5 — see the `components` scope-routing note above and `../astro/stores/COMPONENTS_CSS.md`), NOT in the designer's `global.css`. The classes the pack owns:
-
-- `.product-card`, `.product-card-media`, `.product-card-ribbon`, `.product-card-index` — the product card itself, including the `overflow: hidden` + `border-radius` clipping context. Whoever writes the `border-radius` here also writes any inner padding required to keep child content inside the rounded edges. Without inner padding, a price `<p>` sits flush against the rounded bottom corner and descenders get clipped. Add `padding-bottom: 1rem` on the card plus horizontal padding on each text block when you set the radius. See `references/shared/STYLING.md` § "Component-specific CSS is owned by the component, not the designer".
-- `.product-grid` — the layout that lists product cards. Both `/products` (pages-products scope) and `/category/[slug]` (pages-categories scope) consume it from one place. Include `display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 2rem;` plus the View-Transitions opacity fade for in-flight navigations.
-- `.offer-callout` family (`.offer-callout`, `-item`, `-badge`, `-name`, `-detail`, `-foot`) — discount panel rendered above `<ProductPurchase>` on `/products/[slug]`.
-
-The designer's `global.css` declares only tokens, the `.btn` family, decorative slots, the editorial-rule, and the site-shell shells. If `global.css` ships with a partial rule for any class above, that's a designer bug — flag it in your return JSON's `errors` array (`{code: "GLOBAL_CSS_LEAK", class: "<name>"}`) and override with the complete rule in `components-stores.css`.
-
-## Back-in-stock subscribe — components + pages wiring split
-
-Back-in-stock is a dashboard-toggleable feature: it ships in every stores build but only lights up when the merchant clicks "Start Collecting Requests" in the Back in Stock dashboard. The implementation is split across the `components` and `pages-products` scopes the same way every other stores feature is, with its CSS riding along in the pre-copied stylesheet:
-
-- **`components` scope** writes the SSR probe (`src/utils/back-in-stock.ts`) and the React form island (`src/components/BackInStockForm.tsx`). See `../astro/stores/BACK_IN_STOCK.md` for the full rules — especially the two app ids (use `1380b703-…` for back-in-stock, NOT the Stores install id `215238eb-…`) and the bare-fields rule (no `itemUrl`, no `image` on the SDK call).
-- **Back-in-stock form CSS** ships in the pre-copied `src/styles/components-stores.css` template — no agent writes it. See `../astro/stores/BACK_IN_STOCK.md` § 3 for the rules it carries.
-- **`pages-products` scope** imports `getBackInStockEnabled` in `[slug].astro`, awaits the probe, and passes `backInStockEnabled` + `priceAmount` to `<ProductPurchase>`. ProductPurchase renders the form in its three OOS branches when the prop is true.
-
-If the merchant hasn't enabled "Start Collecting Requests", the probe returns `false`, the prop stays `false`, and the form never mounts — no rebuild needed when the merchant flips the toggle in the dashboard.
-
-## Stores-specific failure modes
-
-| Wrong | Right |
-|---|---|
-| `import { products }` | `import { productsV3 }` — V1 silently returns 0 on V3 catalogs |
-| Skip `variantId` on cart add | Always include — single-variant products have one |
-| Omit `wixMetadata` on `/products/[slug]` | Required for Wix sitemap/SEO/deep-link routing |
-| Mount CartBadge on a page component | Mount via ecom's `contributes:` marker in `Navigation.astro` so it appears on all pages |
-| Hit `/stores/v3/categories/...` for category endpoints | Categories live under `/categories/v1/` — `POST /categories/v1/categories`, `POST /categories/v1/bulk/categories/{id}/add-items`, `POST /categories/v1/categories/query` |
-| Use the back-in-stock app id `1380b703-…` when adding items to a category | Use the **Stores install id** `215238eb-22a5-4c36-9e7b-e7c08025e04e` for `appId` on `bulkAddItemsToCategory` items — it's the same id Wix Stores writes to its products |
-| Call `categories.queryCategories(...).limit(N).find()` with no filter | The SDK builder rejects empty filter expressions with `INVALID_FILTER`. Always chain at least `.eq("visible", true)` before `.find()` |
-| Call `categories.listCategoriesForItems(items, ...)` from the SDK | The SDK function ships items via GET querystring and breaks on arrays. Use `POST /categories/v1/categories/list-categories-for-items` directly, or fan out per-category via `listItemsInCategory` |
-| Ship a client-side filter (`data-category-ids` + JS hide) on the product grid | Filter server-side via `/category/[slug]` routes; client-side filtering doesn't scale past ~100 products and breaks SEO. The `<CategoryRail/>` swaps cards via `<ClientRouter />`, not by hiding them |