@wix/agent-skills 1.7.0 → 1.9.0

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

@@ -2,7 +2,9 @@
 
 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.
 
-At end of run, the skill writes ONE file (`.wix/run.json`) aggregating every return. This is the only observability artifact on the project side.
+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
 
@@ -28,10 +30,10 @@ Every subagent's final message ends with a fenced JSON block (language tag: `jso
 ```json
 {
   "status": "complete" | "partial" | "failed",
-  "phase": "<phase identifier — pack.seed / pack.components / pack.pages[*].name / design-system / image-phase-1-decorative / image-phase-2-entity>",
+  "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 ... },
+  "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>"
@@ -43,28 +45,11 @@ The JSON block MUST be the **last** content in the message. The parent skill par
 
 ### Timing is NOT the agent's responsibility
 
-Prior versions of this contract asked agents to include `started` / `ended` ISO-8601 timestamps. **Remove those fields.** Agents fabricate placeholder timestamps (`T00:00:00Z` / `T00:05:00Z`) roughly 60% of the time, which makes `run.json` useless for perf comparison.
-
-**Authoritative timing source is the runtime `duration_ms`** captured by the parent skill from task-notifications when the subagent completes. The orchestrator MUST prefer `duration_ms` over any agent-reported timing. If an older agent still emits `started`/`ended`, the orchestrator ignores them.
-
-For Bash calls made by the skill itself (scaffold, env-pull, npm-install, app-install), wrap in `date -u` captures:
-
-```bash
-STARTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-# ... run the command ...
-ENDED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-# compute seconds and append to run.json
-```
-
-No LLM-generated timestamps anywhere in the observability pipeline.
+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.
 
-### Observed failure mode — narrative ending instead of fenced JSON
+### No trailing prose after the fenced JSON
 
-Agents sometimes end with prose like:
-
-> *"All three files are correctly written. Let me verify the key requirements… Everything looks good."*
-
-…with no fenced JSON block at the end. The parent skill then has to reconstruct `data.products` etc. from narrative text — fragile, and when Phase 4 relies on pre-seeded data from Phase 1 Seed returns (see `SKILL.md` Step 7), a missing JSON block means Phase 4 agents don't get their pre-seeded data inline and fall back to re-querying the REST API, costing 5–15s each.
+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:**
 
@@ -96,14 +81,6 @@ All files written. Contract classes referenced: productCard, productGrid, option
 All three files are correctly written. Let me verify the key requirements are met before returning.
 ~~~
 
-~~~markdown
-❌ WRONG — no JSON block at all
-
-All three files are correctly written. The ProductPurchase island uses contract classes
-throughout, AddToCartButton wires to @wix/ecom, and CartView handles the two-step
-checkout redirect. Build should pass.
-~~~
-
 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
@@ -114,205 +91,6 @@ The parent skill looks for the **last** fenced JSON block in the message. A trai
 | `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 |
 
-## Phase-specific `data` shapes
-
-The skill uses `data` to carry information forward to later phases. Each phase has a known shape.
-
-### Phase 1: stores seed
-
-```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": []
-}
-```
-
-Phase 4 agents consume `data.products[*].slug` and `data.products[*].variantId` to wire live SDK queries.
-
-### Phase 1: CMS seed
-
-```json
-{
-  "status": "complete",
-  "phase": "cms-seed",
-  "scope": "seed",
-  "data": {
-    "collections": [
-      {
-        "name": "about-content",
-        "itemIds": ["665f3363-..."],
-        "fields": ["heading", "body", "image"]
-      },
-      {
-        "name": "faq",
-        "itemIds": ["abc", "def", "ghi", "jkl", "mno", "pqr"],
-        "fields": ["question", "answer", "sortOrder"]
-      }
-    ]
-  }
-}
-```
-
-Phase 4 CMS page agents reference these collection names; the image agent attaches entity images to CMS items by ID.
-
-### Phase 2: shared wiring
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-components",
-  "scope": "components",
-  "summary": "Wrote React islands + utils; wired analytics; contract classes referenced: 7",
-  "data": {
-    "islands": ["ProductPurchase.tsx", "CartView.tsx", "AddToCartButton.tsx", "CartBadge.tsx"],
-    "utils": ["wix-image.ts", "analytics.ts"],
-    "astroComponents": ["SeoTags.astro"]
-  },
-  "files": [
-    "src/utils/wix-image.ts",
-    "src/utils/analytics.ts",
-    "src/components/SeoTags.astro",
-    "src/components/AddToCartButton.tsx",
-    "src/components/CartBadge.tsx",
-    "src/components/ProductPurchase.tsx",
-    "src/components/CartView.tsx"
-  ]
-}
-```
-
-### Phase 2: page rewrites
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-pages-products",
-  "scope": "pages-products",
-  "data": {
-    "pagesWired": 2,
-    "wixMetadataExported": true,
-    "seoTagsMounted": true,
-    "analyticsEvents": ["AddProductImpression", "ClickProduct", "ViewContent"]
-  },
-  "files": [
-    "src/pages/products/index.astro",
-    "src/pages/products/[slug].astro",
-    "src/components/ProductCard.astro"
-  ]
-}
-```
-
-### Designer foundation
-
-```json
-{
-  "status": "complete",
-  "phase": "design-system",
-  "data": {
-    "contractKeys": 19,
-    "cssLines": 247,
-    "fonts": ["Cormorant Garamond", "DM Sans"],
-    "palette": {"cream": "#FFF8F0", "charcoal": "#1A1A1A", "roseGold": "#B76E79"}
-  },
-  "files": [
-    "src/styles/global.css",
-    "src/layouts/Layout.astro",
-    "src/components/Navigation.astro",
-    "src/components/Footer.astro",
-    ".wix/design-tokens.css"
-  ]
-}
-```
-
-### Designer page groups
-
-```json
-{
-  "status": "complete",
-  "phase": "designer-store-pages",
-  "data": {
-    "pagesDesigned": ["/products", "/products/[slug]", "/cart", "/thank-you"],
-    "placeholderDataUsed": true,
-    "contractClassesHonored": 11
-  },
-  "files": [
-    "src/pages/products/index.astro",
-    "src/pages/products/[slug].astro",
-    "src/pages/cart.astro",
-    "src/pages/thank-you.astro",
-    "src/components/ProductCard.astro",
-    "src/components/ProductPurchase.astro",
-    "src/components/CartView.astro"
-  ]
-}
-```
-
-### Images (split into two image phases, dispatched separately)
-
-The image agent runs in two scopes dispatched by the parent in different steps. Each emits its own return block.
-
-**`image-phase-1-decorative` — dispatched in `SEED.md` Step 2 Wave 3 batch (no dependencies):**
-
-```json
-{
-  "status": "complete",
-  "phase": "image-phase-1-decorative",
-  "scope": "image-phase-1-decorative",
-  "summary": "Generated 3 decorative images; uploaded to Wix Media; returned slot→URL map",
-  "data": {
-    "decorativeCount": 3,
-    "purposes": ["hero", "about", "background"],
-    "slots": {
-      "hero":  "https://static.wixstatic.com/media/...",
-      "about": "https://static.wixstatic.com/media/...",
-      "background": "https://static.wixstatic.com/media/..."
-    },
-    "model": "google:4@2",
-    "totalCredits": 0.297
-  },
-  "files": [],
-  "errors": []
-}
-```
-
-**`image-phase-2-entity` — dispatched in Step 7 (Phase 1 Seed return data inline in prompt):**
-
-```json
-{
-  "status": "complete",
-  "phase": "image-phase-2-entity",
-  "scope": "image-phase-2-entity",
-  "summary": "Generated + attached images for 6 products and 1 CMS item",
-  "data": {
-    "entityCount": { "products": 6, "cmsAboutContent": 1, "blogPosts": 0 },
-    "model": "google:4@2",
-    "totalCredits": 0.693
-  },
-  "files": [],
-  "errors": []
-}
-```
-
-(Image agent writes to Wix Media via REST, not to project files — Image Phase 2 `files` is empty.)
-
 ## Failure returns
 
 On `failed` or `partial`, `errors` is populated and `data` may still contain partial results:
@@ -335,98 +113,31 @@ On `failed` or `partial`, `errors` is populated and `data` may still contain par
 
 Severity levels: `warning` (keep running), `error` (parent should retry), `fatal` (parent must stop).
 
-## Final `.wix/run.json` (written once by the skill at end of run)
-
-The skill aggregates every agent return into one file.
-
-**Timing is required** — the `run` object MUST include `started`, `ended`, and `totalSeconds`, and every entry in `phases` MUST include `seconds`. All timing values are captured by the parent skill (from runtime `duration_ms` for subagents, from `date -u` wraps for its own Bash calls) — agents do not self-report. If timing is missing for any phase, record `seconds: null` + `errors: [{code: "MISSING_TIMING"}]` and investigate what broke capture. See `skills/wix-headless/SKILL.md` § "Timing — required in run.json" for the capture protocol.
-
-Example:
-
-```json
-{
-  "version": "1.0",
-  "run": {
-    "started": "2026-01-15T09:16:14Z",
-    "ended": "2026-01-15T09:28:03Z",
-    "totalSeconds": 709,
-    "brand": "Acme Coffee",
-    "prompt": "I want to sell tables online",
-    "verticals": ["stores", "cms"],
-    "packs": ["stores", "cms"]
-  },
-  "outcome": {
-    "build": "success",
-    "previewUrl": "https://goj5lj-tabula-...-alexp775.wix-host.com",
-    "dashboardUrl": "https://manage.wix.com/dashboard/<siteId>"
-  },
-  "phases": [
-    { "phase": "scaffold", "status": "complete", "seconds": 45 },
-    { "phase": "app-install-stores", "status": "complete", "seconds": 6 },
-    { "phase": "env-pull", "status": "complete", "seconds": 4 },
-    { "phase": "npm-install", "status": "complete", "seconds": 42, "packageCount": 725 },
-    { "phase": "stores-seed", "status": "complete", "seconds": 112, "data": { ... } },
-    { "phase": "cms-seed", "status": "complete", "seconds": 98, "data": { ... } },
-    { "phase": "stores-components", "status": "complete", "seconds": 134, "data": { ... } },
-    { "phase": "design-system", "status": "complete", "seconds": 165, "data": { ... } },
-    { "phase": "designer-home", "status": "complete", "seconds": 287, "data": { ... } },
-    { "phase": "designer-static", "status": "complete", "seconds": 265, "data": { ... } },
-    { "phase": "designer-store-pages", "status": "complete", "seconds": 298, "data": { ... } },
-    { "phase": "stores-pages-products", "status": "complete", "seconds": 89, "data": { ... } },
-    { "phase": "stores-pages-cart-checkout", "status": "complete", "seconds": 67, "data": { ... } },
-    { "phase": "stores-pages-home-and-nav", "status": "complete", "seconds": 54, "data": { ... } },
-    { "phase": "pages", "status": "complete", "seconds": 78, "data": { ... } },
-    { "phase": "image-phase-1-decorative", "status": "complete", "seconds": 112, "data": { "decorativeCount": 3, ... } },
-    { "phase": "image-phase-2-entity", "status": "complete", "seconds": 287, "data": { "entityCount": { "products": 6, "cmsAboutContent": 1 }, ... } },
-    { "phase": "build", "status": "complete", "seconds": 9 },
-    { "phase": "preview", "status": "complete", "seconds": 21 }
-  ],
-  "notes": []
-}
-```
-
-Observations post-run (including this doc's example):
-- Total serial wall time ≈ max parallel paths, not sum of seconds
-- `data` blocks preserve what each agent returned — recoverable without re-reading agent transcripts
-- `files` lists omitted from aggregate; query individual phase `data` if needed
-
-## Common failure modes
-
-Agents should check their output for these before returning `complete`:
-
-### Astro/React
-
-| Failure | How to detect | Fix |
-|---------|---------------|-----|
-| HTML-style comments in `.astro` frontmatter | `grep '<!--' *.astro frontmatter` | Use `//` or `/* */` — frontmatter is TypeScript |
-| Missing `wixMetadata` on `/products/[slug]` | Check exports | Add the metadata export — required for Wix platform indexing |
-| `import { products }` instead of `productsV3` | `grep 'from "@wix/stores"' -- import line` | V1 silently returns 0 on V3 catalogs |
-| Missing `variantId` in cart operations | Check `catalogReference.options` | Always include — single-variant products have one |
-| React island using default Tailwind color class | `grep 'bg-blue-\|bg-green-\|text-red-\|bg-gray-' *.tsx` | Use brand `@theme` utilities (`bg-bark`, `text-cream`) or contract class names |
-
-### REST API
+## Where your phase-specific `data` shape lives
 
-| Failure | How to detect | Fix |
-|---------|---------------|-----|
-| `UNSUPPORTED_FORM_NAMESPACE` after app install | Error on first REST call post-install | Wait 10s, retry up to 3x (namespace propagation) |
-| `curl` with stringified `body` | Endpoint rejects the call shape | Pass `body` as a real JSON object via `-d` (not a stringified blob). See `AUTHENTICATION.md` for the standard REST headers. |
-| 401/403 on Wix REST call | Expired or wrong token | Re-mint per `AUTHENTICATION.md` recovery ladder; one retry then surface body |
+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.
 
-### Build
+| 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 |
 
-| Failure | How to detect | Fix |
-|---------|---------------|-----|
-| `Legacy HTML single-line comments` | `npx @wix/cli@latest build` stderr | See Astro/React row 1 above — Phase 2 agent emitted HTML comments |
-| `Missing environment variable WIX_CLIENT_ID` | Build stderr | Run `npx @wix/cli@latest env pull --json` then retry |
-| `Cannot find module '@wix/…'` | Build stderr | npm install didn't include that package; check pack's `packages` list |
+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, include a **Returns** section in its `INSTRUCTIONS.md` that lists:
+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
 
-Agents should 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.
+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,14 +1,14 @@
 # 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), `COMPOSE.md` (Composer), `astro/designer/INSTRUCTIONS.md` (Phase 4 page designers), and `IMPLEMENTER.md` link here.
+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 returned as a framework-agnostic JSON spec (`data.designTokens`). The **Composer** (`COMPOSE.md`) 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"`.
+> **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)** | `@theme` block in `src/styles/global.css`, mirrored to `.wix/design-tokens.css` + `.wix/site.d.ts` (emitted by `scripts/emit-design-tokens.mjs` from Designer's `data.designTokens`) | Designer picks values (Phase 2); Composer writes `@theme` | All color, spacing, typography scale, radii, aspect ratios, shadows, transitions. Pages compose tokens at call sites as Tailwind utilities — `class="py-4xl bg-sand aspect-[16/5]"`. |
+| **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, spacing, typography scale, radii, aspect ratios, shadows, transitions. Pages compose tokens at call sites as Tailwind utilities — `class="py-4xl 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. |
 
@@ -16,7 +16,7 @@ Every visual decision in a generated site falls into one of three categories. Ea
 
 **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 `py-4xl`, `gap-sm`, `bg-paper-warm`, `text-ink`, `font-display`, `aspect-[16/5]` etc. Compose them in markup; do not invent semantic classes for these concerns.
 
-The token namespace is the contract. The orchestrator inlines the full `designTokens` JSON in your prompt (same shape Designer returned) — at start of any pages or components scope, read from your prompt to know which tokens this run published. `.wix/design-tokens.css` and `.wix/site.d.ts` are on disk for the build to consume, but you do NOT need to read them. If a token you need isn't in the inlined contract, that's a designer-side gap — flag it in your return JSON, don't paper over it with a custom class.
+The token namespace is the contract. The design tokens (the DESIGN.md token vocabulary — `colors`/`typography`/`spacing`/`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
 
@@ -53,7 +53,7 @@ If a designer's `global.css` contains rules like `.featured-section { padding-bl
 
 ## 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.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).
+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 |
 |---|---|---|---|
@@ -104,25 +104,15 @@ The fix is structural: move component-specific CSS out of `global.css` entirely.
 
 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`.
 
-### Why this is structural
-
-Tokens + truly cross-cutting patterns (buttons, decorative slots, site shell) are stable across verticals and brands — fine for the designer to own. Component-specific layout and spacing evolves with the component. Putting it next to the component means:
-
-- One author per class. No drift.
-- Verticals can ship new component variants without round-tripping the designer.
-- `overflow: hidden` + `border-radius` traps are caught by the same person who set the radius — no second author who has to *know* the radius value.
-
 ### Pre-return checklist for the Composer
 
-The Composer writes `global.css` by substituting the `@theme` palette into a pinned skeleton, so the component-class leak below is **structurally prevented** — the skeleton declares no `.product-card`/`.cart-summary`-family rules at all. The check remains as a guard: before returning, confirm the Composer-written `global.css` declares none of these (it shouldn't, unless the skeleton was edited):
+`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/templates/*/
+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 every class name listed above that the Composer's `global.css` declares: if any template references it, the class is component-specific and must NOT be in `global.css`. Move the rule to the appropriate `components-<pack>.css` template (or to a scoped `<style>` block in the component template). Do NOT ship a partial rule in `global.css` that the template "completes" — that's the leak this file is preventing.
-
-The check is mechanical and bounded — it scans templates, not the live project.
+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
 

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

@@ -5,7 +5,7 @@ description: "Implements Wix Stores vertical — product catalog, categories, ad
 
 # Stores Implementer
 
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, prompt-inlined inputs (no site.json reads), return contract, style conventions, and common failure modes.
+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
 
@@ -13,20 +13,50 @@ Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routi
 |-------|-------|-----------|
 | `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.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. | — |
+| ~~`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 split.** A single agent writing five .tsx/.astro files plus the scoped CSS dominated Phase 3 wall time (228 s on a 3-product run, 320 s on an 8-product run). The CSS file has no runtime coupling to the TSX components — it's referenced only by class name at build time — so it splits cleanly into a sibling agent that runs in the same dispatch batch. Each scope gets a smaller reading set and a smaller write list. See `../astro/stores/COMPONENTS_CSS.md` § "What this scope owns".
+> **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 `<SKILL_ROOT>/references/verticals/stores.md` frontmatter (`creates:` and `contributes:` blocks).
+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 listed in your scope's `files:` block (see verticals/stores.md) exists on disk. Silently dropping a file (e.g. `[slug].astro` from `pages-products`) reports `complete` to the orchestrator, but every product link 404s at runtime.
+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.
 
@@ -40,7 +70,7 @@ Components (`components` scope — TSX/Astro only):
 - `<SKILL_ROOT>/references/astro/templates/stores/BackInStockForm.tsx`
 - `<SKILL_ROOT>/references/astro/templates/stores/SeoTags.astro`
 
-Components CSS (`components-css` scope — scoped CSS only):
+Components CSS (pre-copied by the orchestrator — no agent writes it):
 - `<SKILL_ROOT>/references/astro/templates/stores/components-stores.css`
 
 Pages (`pages-products` scope):
@@ -63,7 +93,7 @@ If you find one of these missing at runtime, that's an orchestrator-side bug —
 
 ## CSS ownership — stores pack
 
-Stores-specific component CSS lives in `src/styles/components-stores.css` (written by the `components-css` scope — see `../astro/stores/COMPONENTS_CSS.md`), NOT in the designer's `global.css`. The classes the pack owns:
+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: var(--spacing-md)` on the card plus horizontal padding on each text block when you set the radius. See `references/shared/STYLING.md` § "Component-specific CSS is owned by the component, not the designer".
 - `.product-grid` — the layout that lists product cards. Both `/products` (pages-products scope) and `/category/[slug]` (pages-categories scope) consume it from one place. Include `display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: var(--spacing-xl);` plus the View-Transitions opacity fade for in-flight navigations.
@@ -73,10 +103,10 @@ The designer's `global.css` declares only tokens, the `.btn` family, decorative
 
 ## Back-in-stock subscribe — components + pages wiring split
 
-Back-in-stock is a dashboard-toggleable feature: it ships in every stores build but only lights up when the merchant clicks "Start Collecting Requests" in the Back in Stock dashboard. The implementation is split across the two scopes the same way every other stores feature is:
+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).
-- **`components-css` scope** appends the back-in-stock form rules to `src/styles/components-stores.css` as part of writing that file. See `../astro/stores/BACK_IN_STOCK.md` § 3 for the CSS append.
+- **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.