@wix/agent-skills 1.5.0 → 1.7.0

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

@@ -8,7 +8,7 @@ Read **only** the files your scope needs. The reading set varies by scope:
 
 | Your scope | Mandatory | Conditional |
 |---|---|---|
-| `seed` | this file, `RETURN_CONTRACT.md`, `MCP_PREFIX.md` | — |
+| `seed` | this file, `RETURN_CONTRACT.md`, `DOCS_SEARCH.md` | — |
 | `components`, `components-css`, `pages`, `pages-*` | this file, `RETURN_CONTRACT.md`, `STYLING.md` | — |
 | Image scopes | (read `references/images/INSTRUCTIONS.md` § Self-Loading) | — |
 
@@ -19,50 +19,41 @@ Then read the specific reference(s) for your declared scope (see your vertical's
 Your prompt includes a line `Scope: <name>`. Map to exactly one reference set per your vertical's `INSTRUCTIONS.md` scope table. If the `Scope:` line is missing, stop and ask the parent — do not guess.
 
 Standard scope names (see architecture-proposal §3):
-- `seed` — Seed phase (MCP data setup, no frontend code)
+- `seed` — Seed phase (REST data setup, no frontend code)
 - `components` — Components phase (reusable React/Astro islands, SDK wiring)
 - `pages` — Pages phase (route files with visual design + data queries, single scope per vertical)
 - `pages-<name>` — Pages phase sub-scope (only when a vertical has multiple pages groups, e.g. stores has `pages-products`, `pages-home-and-nav`)
 
-## MCP tool prefix
+## REST auth
 
-Your prompt includes `MCP tool prefix: <prefix>`. Substitute it for `mcp__wix-mcp-remote__` wherever it appears in your reference files. See `references/shared/MCP_PREFIX.md` for discovery rules.
+Scopes that call Wix APIs (`seed`, image phases) receive `siteId` in the prompt. Mint once: `TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")`. Every `curl` uses the headers in `references/shared/AUTHENTICATION.md`. Doc lookups use the public REST endpoints listed in `references/shared/DOCS_SEARCH.md`.
 
-If your scope is `components` or `pages`, you should NOT make MCP calls — those scopes are frontend-only. If you find yourself needing MCP, it's a scope violation — return `status: "partial"` with an error note, do not proceed.
+If your scope is `components` or `pages`, you should NOT make REST calls — those scopes are frontend-only. If you find yourself needing a site API call, it's a scope violation — return `status: "partial"` with an error note, do not proceed.
 
-## Reading `.wix/site.json`
+## Do NOT read `.wix/site.json`
 
-Every agent reads `.wix/site.json` at the start of its run. The file is the single source of truth for per-project data:
+Every input you need is inlined in your prompt. The orchestrator is the sole reader/writer of `.wix/site.json`; the file is a slim metadata snapshot for run.json composition + resume detection, not a coordination channel.
 
-```jsonc
-{
-  "brand":        { "name": "...", "description": "..." },
-  "seeded":       { "stores": { "products": [...] }, "cms": { "collections": {...} }, ... },
-  "designTokens": { "colors": {...}, "fonts": {...}, "radii": {...}, "spacing": {...} },
-  "verticals":    ["stores", "ecom", "cms"]
-}
-```
-
-**Phase-specific reads:**
+**Phase-specific inputs (all inlined in your prompt):**
 
-| Scope | What to read from site.json |
+| Scope | What the prompt inlines |
 |---|---|
-| `seed` | `brand` (for copy generation — product descriptions, FAQ answers). Do NOT read `seeded.<self>` — you're writing it. |
-| `components` | `brand`, `designTokens` (via `var(--color-*)` in CSS). |
-| `pages` / `pages-*` | `brand`, `seeded.<vertical>` (products, posts, collections), `designTokens`. Page data comes from `seeded`, NOT from re-querying MCP. |
+| `seed` | `brand`, `intent.<pack>`, `siteId`, recipe path(s). Do NOT re-derive these. |
+| `components` | `brand`, the full `designTokens` JSON (same shape Designer returned). CSS variables are also on disk at `.wix/design-tokens.css` for the build. |
+| `pages` / `pages-*` | `brand`, the `designTokens` JSON, and the relevant `seeded.<vertical>` slice (products, posts, collections IDs). Page data wiring uses live SDK queries; the `seeded` data in your prompt is for path resolution + demo content authoring. |
 
-If a required key is missing (e.g. `seeded.stores.products` absent when you're dispatched as `pages-products`), fail fast — return `status: "failed"` with `errors: [{ code: "SITE_JSON_INCOMPLETE", missing: "seeded.stores.products" }]`. Do NOT re-query MCP — the data gap means a seeder didn't complete, and re-querying would mask the real bug.
+If a required input is missing from your prompt (e.g. the orchestrator forgot to inline `seeded.stores` when dispatching you as `pages-products`), fail fast — return `status: "failed"` with `errors: [{ code: "PROMPT_INCOMPLETE", missing: "seeded.stores.products" }]`. Do NOT re-fetch from `.wix/site.json` or via curl — the data gap means an upstream phase didn't complete, and re-querying would mask the real bug.
 
-## Seeders write their data for the orchestrator to aggregate
+## Seeders return data; orchestrator aggregates
 
-Agents with `Scope: seed` return their seeded entities in the `data` block of the standard return (see `RETURN_CONTRACT.md`). The parent skill merges your return into `.wix/site.json.seeded.<vertical>` after your run completes. You do NOT write `site.json` yourself — return the data and let the orchestrator aggregate.
+Agents with `Scope: seed` return their seeded entities in the `data` block of the standard return (see `RETURN_CONTRACT.md`). The orchestrator collects every seeder return into its session scratch and inlines the relevant slice into the prompts of Phase 3 Components / Phase 4 Pages / Image Phase 2 subagents. You do NOT write `site.json` yourself and you do NOT write `.wix/seed-returns/<pack>.json` — your JSON return is the contract.
 
 ## Writing page files
 
 Pages-phase agents write route files (`.astro`) with:
 
 1. **Visual design via design tokens and Tailwind.** Reference tokens as `var(--color-primary)` in `<style>` blocks or `bg-[--color-primary]` as Tailwind arbitrary values. Use canonical component templates (`agents/<vertical>/templates/*.astro`) as starting points — adapt, don't invent.
-2. **Data queries against seeded data.** Read the seeded entities from `.wix/site.json.seeded.<vertical>` at build time (Astro frontmatter `import { site } from "../../.wix/site"`) or at request time via the SDK if the page is server-rendered.
+2. **Data queries against seeded data.** The seeded entity IDs / slugs are inlined in your prompt (`seeded.<vertical>`). Pages query the Wix SDK at request time (`await productsV3.queryProducts(...)`) — that's the production-correct pattern. Use the inlined `seeded` data for path generation (e.g. `getStaticPaths` slugs) and for authoring demo content where needed; do NOT `import` `.wix/site.json` from page files.
 3. **Imports from shared components.** Pages import components your Components-phase agent wrote (`src/components/*.tsx`, `.astro`).
 4. **Imports from skill shared utilities.** `from "../utils/wix-image"` and `from "../utils/analytics"` — these are skill-shipped (copied into the project by `seed-utilities.sh` during Setup); do NOT import them from anywhere else.
 
@@ -133,7 +124,7 @@ The full styling contract (tokens-as-utilities default, when global semantic cla
   @reference "./global.css";
   ```
   Without it, the build breaks at release time even though `tsc` and `astro check` pass clean — only the bundler catches it.
-- **Fail loud, never silently.** If data is missing, a required field is absent, or an MCP call returns an unexpected shape, return `status: "failed"` with details. Do not invent placeholders or swallow errors.
+- **Fail loud, never silently.** If data is missing, a required field is absent, or an REST call returns an unexpected shape, return `status: "failed"` with details. Do not invent placeholders or swallow errors.
 
 ## Return contract
 
@@ -144,12 +135,12 @@ Every agent ends its message with a fenced JSON block per `RETURN_CONTRACT.md`.
 | Wrong | Right |
 |---|---|
 | Reading references for scopes other than the declared `Scope:` | Read only your scope's references |
-| Querying MCP from a `components` or `pages` scope | Components/Pages are frontend-only; use `seeded` data from `site.json` |
-| Re-querying when `site.json.seeded.<vertical>` is missing | Fail fast with `SITE_JSON_INCOMPLETE` — the seeder didn't complete |
+| Issuing REST calls from a `components` or `pages` scope | Components/Pages are frontend-only; use `seeded` data inlined in your prompt |
+| Re-querying when `seeded.<vertical>` is missing from your prompt | Fail fast with `PROMPT_INCOMPLETE` — the orchestrator forgot to inline it (upstream bug) |
 | Writing `.wix/site.json` from a seeder | Seeders return data; orchestrator writes site.json |
 | Inventing class names for layout/spacing/typography (`.productCard`, `.heroSection`) | Tailwind utilities derived from `@theme` tokens (`class="flex flex-col gap-md"`, `class="py-4xl"`). For one-off page decoration, co-located `<style>` block. |
 | Removing a marker after inserting at it | Marker stays; other verticals may contribute after you |
 | Trailing narrative prose after the return JSON | JSON block must be the last content |
 | Fabricated timestamps in the return JSON | Do not include timing fields — orchestrator captures them |
 | Inline `style="color: red"` | Use design tokens: `style="color: var(--color-primary)"` |
-| Creating a new cross-cutting class name | Extract a shared primitive component instead |
+| Creating a new cross-cutting class name | Extract a shared primitive component instead |

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

@@ -94,4 +94,4 @@ For production checks, verify the final rendered HTML and edge-controlled files
 - For `llms.txt`: fetch `/llms.txt` after the REST update and account for Wix-injected sections.
 - For custom domains: check both the Wix-hosted URL and custom domain when available, because domain propagation and redirects can differ.
 
-Do not construct URLs by editing the release URL from memory. Use the exact release URL printed by the CLI or the configured custom domain.
+Do not construct URLs by editing the release URL from memory. Use the exact release URL printed by the CLI or the configured custom domain.

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

@@ -1,18 +1,22 @@
 # Agent Return Contract
 
-Replaces the sidecar-file coordination model (`.wix/logs/*.md`) with **in-memory structured returns**. Every agent returns a JSON block at the end of its completion message; the skill parses these returns directly from session context.
+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.
 
-## Why this replaces sidecars
+## The JSON return is your sole output channel
 
-Sidecar files were designed assuming agents are independent processes without shared memory. But subagents run as child model calls under the parent skill's context — they can return structured data directly. Writing/reading markdown files between them adds:
+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)
 
-Prior runs spent **~1–2 minutes total** on sidecar ceremony. Eliminating that buys back meaningful critical-path time.
+That overhead is pure critical-path cost with no benefit here.
 
 ## The contract
 
@@ -60,7 +64,7 @@ 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 MCP, costing 5–15s each.
+…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.
 
 **Correct pattern — end with the fenced block, no trailing prose:**
 
@@ -265,21 +269,26 @@ Phase 4 CMS page agents reference these collection names; the image agent attach
 
 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 Step 3 (no dependencies):**
+**`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; wrote .wix/image-urls.md",
+  "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": [".wix/image-urls.md"],
+  "files": [],
   "errors": []
 }
 ```
@@ -302,7 +311,7 @@ The image agent runs in two scopes dispatched by the parent in different steps.
 }
 ```
 
-(Image agent writes to Wix Media via MCP, not to project files — Image Phase 2 `files` is empty.)
+(Image agent writes to Wix Media via REST, not to project files — Image Phase 2 `files` is empty.)
 
 ## Failure returns
 
@@ -395,20 +404,20 @@ Agents should check their output for these before returning `complete`:
 | 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 |
 
-### MCP
+### REST API
 
 | Failure | How to detect | Fix |
 |---------|---------------|-----|
-| `UNSUPPORTED_FORM_NAMESPACE` after app install | Error on first MCP call post-install | Wait 10s, retry up to 3x (namespace propagation) |
-| `CallWixSiteAPI` with stringified `body` | Tool rejects the call shape | Load the tool schema via your runtime's tool-discovery primitive, then pass `body` as a real object |
-| Tool-not-found on Wix MCP call | Tool name without the session's prefix | Use `<prefix>ToolName`; see `MCP_PREFIX.md` recovery |
+| `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 |
 
 ### Build
 
 | Failure | How to detect | Fix |
 |---------|---------------|-----|
-| `Legacy HTML single-line comments` | `npx @wix/cli 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 env pull` then retry |
+| `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 |
 
 ## Notes for agent authors
@@ -420,4 +429,4 @@ When writing a new agent, include a **Returns** section in its `INSTRUCTIONS.md`
 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.
+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.

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

@@ -1,12 +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; designer `INSTRUCTIONS.md` 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), `COMPOSE.md` (Composer), `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"`.
 
 ## The three categories
 
 | Category | Lives in | Owned by | Use for |
 |---|---|---|---|
-| **Tokens (composed as utilities)** | `@theme` block in `src/styles/global.css`, mirrored to `.wix/site.json.designTokens`, `.wix/design-tokens.css`, `.wix/site.d.ts` | Designer (Phase 2) | 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)** | `@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]"`. |
 | **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. |
 
@@ -14,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. Read `.wix/site.json.designTokens` (or its typed mirror at `.wix/site.d.ts`) at the start of any pages or components scope to know which tokens this run published. If a token you need isn't there, 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 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.
 
 ## Decision tree
 
@@ -24,7 +26,7 @@ When you find yourself reaching for a `class="..."` value, ask:
 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` and propagate to `.wix/site.json.designTokens`).
+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
 
@@ -35,10 +37,45 @@ These are layout/spacing/typography concerns that should always be utilities, ne
 - 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 derived from tokens (`max-w-prose`, `w-full`)
+- Container widths derived from tokens (`max-w-prose`, `w-full`) **only when** the designer declared matching `--container-*` keys in `@theme`
+
+### Prose / reading width (CMS, FAQ, About)
+
+Tailwind v4 resolves `max-w-3xl` to `var(--container-3xl)`, **not** `var(--spacing-3xl)`. If the designer published `--spacing-3xl: 5rem` but no `--container-3xl`, FAQ/About columns collapse to ~80px.
+
+**Page agents (Phase 4):**
+
+- **Do not** use `max-w-2xl`, `max-w-3xl`, etc. unless `global.css` `@theme` documents the matching `--container-*` key (grep `@theme` before choosing).
+- **Prefer** `container-reading` (designer `@utility`), `max-w-6xl` when `--container-6xl` exists, or explicit arbitrary width `max-w-[48rem]`.
+- **Do not** confuse spacing scale with container scale — `py-3xl` uses `--spacing-3xl`; `max-w-3xl` uses `--container-3xl`.
 
 If a designer's `global.css` contains rules like `.featured-section { padding-block: var(--spacing-4xl); }` or `.product-card-body { display: flex; flex-direction: column; gap: var(--spacing-xs); }`, those are misplaced — they belong in markup as utilities. 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.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 |
+| `--spacing-2xs` … `--spacing-4xl` | **required (full scale)** | — | every template uses `gap: var(--spacing-md)` and similar |
+| `--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-sm` 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.
@@ -54,7 +91,7 @@ That's it. The full list of always-required classes for a site lives in designer
 
 ## Component-specific CSS is owned by the component, not the designer
 
-The boundary that previously caused leaks: the designer published 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. Result: the same class 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 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.
 
@@ -75,15 +112,15 @@ Tokens + truly cross-cutting patterns (buttons, decorative slots, site shell) ar
 - 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 designer
+### Pre-return checklist for the Composer
 
-Before returning the design-system scope, the designer agent runs:
+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):
 
 ```
 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/*/
 ```
 
-For every class name listed above that the designer'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.
+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.
 
@@ -114,4 +151,4 @@ No coordination with the designer needed; no entry to forget on the always-requi
 
 ## 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.
+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

@@ -5,20 +5,20 @@ description: "Implements Wix Stores vertical — product catalog, categories, ad
 
 # Stores Implementer
 
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, MCP prefix, site.json read pattern, return contract, style conventions, and common failure modes.
+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.
 
 ## Scope routing
 
 | Scope | Phase | Reference |
 |-------|-------|-----------|
-| `seed` | Seed (MCP catalog setup — products only; categories are merchant-driven, not seeded) | `./PRODUCT_CATALOG_DATA.md` |
-| `components` | Components (React islands + SeoTags + back-in-stock util — TSX/Astro only, **no CSS**) | `./SHARED_WIRING.md` |
-| `components-css` | Components (scoped CSS — `components-stores.css` only; runs concurrently with `components`) | `./COMPONENTS_CSS.md` |
-| `pages-categories` | Pages (`/category/[slug]` listing + shared CategoryRail + `utils/categories.ts`) | `./CATEGORY_PAGES.md` |
-| `pages-products` | Pages (products listing + detail + ProductCard; mounts the rail written by `pages-categories`) | `./PRODUCT_PAGES.md` |
-| `pages-home-and-nav` | Pages (home-page contribution + Shop submenu in Navigation) | `./HOME_AND_NAV.md` |
+| `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. | — |
+| `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 `./COMPONENTS_CSS.md` § "What this scope owns".
+> **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".
 
 ## Files this vertical creates / contributes
 
@@ -32,38 +32,38 @@ If a declared file is missing, return `status: "partial"` with `errors: [{ code:
 
 ## Templates
 
-Canonical templates live at `<SKILL_ROOT>/templates/stores/`. Your `components` and `pages-*` scopes read these and adapt them — don't invent markup or logic.
+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>/templates/stores/AddToCartButton.tsx`
-- `<SKILL_ROOT>/templates/stores/ProductPurchase.tsx`
-- `<SKILL_ROOT>/templates/stores/BackInStockForm.tsx`
-- `<SKILL_ROOT>/templates/stores/SeoTags.astro`
+- `<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 (`components-css` scope — scoped CSS only):
-- `<SKILL_ROOT>/templates/stores/components-stores.css`
+- `<SKILL_ROOT>/references/astro/templates/stores/components-stores.css`
 
 Pages (`pages-products` scope):
-- `<SKILL_ROOT>/templates/stores/ProductCard.astro`
-- `<SKILL_ROOT>/templates/stores/products/index.astro`
-- `<SKILL_ROOT>/templates/stores/products/[slug].astro`
+- `<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>/templates/stores/CategoryRail.astro`
-- `<SKILL_ROOT>/templates/stores/category/[slug].astro`
+- `<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>/templates/stores/back-in-stock.ts` before `components` dispatches.
-- `src/utils/categories.ts` — pre-copied from `<SKILL_ROOT>/templates/stores/categories.ts` before `pages` dispatches.
+- `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` (written by the `components-css` scope — see `./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` (written by the `components-css` scope — see `../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.
@@ -75,8 +75,8 @@ The designer's `global.css` declares only tokens, the `.btn` family, decorative
 
 Back-in-stock is a dashboard-toggleable feature: it ships in every stores build but only lights up when the merchant clicks "Start Collecting Requests" in the Back in Stock dashboard. The implementation is split across the two scopes the same way every other stores feature is:
 
-- **`components` scope** writes the SSR probe (`src/utils/back-in-stock.ts`) and the React form island (`src/components/BackInStockForm.tsx`). See `./BACK_IN_STOCK.md` for the full rules — especially the two app ids (use `1380b703-…` for back-in-stock, NOT the Stores install id `215238eb-…`) and the bare-fields rule (no `itemUrl`, no `image` on the SDK call).
-- **`components-css` scope** appends the back-in-stock form rules to `src/styles/components-stores.css` as part of writing that file. See `./BACK_IN_STOCK.md` § 3 for the CSS append.
+- **`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.
 - **`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.
@@ -93,4 +93,4 @@ If the merchant hasn't enabled "Start Collecting Requests", the probe returns `f
 | 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 |
+| Ship a client-side filter (`data-category-ids` + JS hide) on the product grid | Filter server-side via `/category/[slug]` routes; client-side filtering doesn't scale past ~100 products and breaks SEO. The `<CategoryRail/>` swaps cards via `<ClientRouter />`, not by hiding them |

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

@@ -1,28 +1,28 @@
 # Recipe: Product Catalog Data Setup (Phase 1)
 
-Replace the default sample products Wix Stores installs with on-brand products via MCP. This file covers the `seed-seed` scope — data seeding only. Frontend wiring lives in the Phase 2 scope references (`SHARED_WIRING.md`, `PRODUCT_PAGES.md`, `CART_CHECKOUT.md`, `HOME_AND_NAV.md`) and should not be read by `seed-seed`.
+Replace the default sample products Wix Stores installs with on-brand products via the Stores REST API (`curl` against `wixapis.com/stores/v3/...` with the standard headers from `../shared/AUTHENTICATION.md`). This file covers the `seed-seed` scope — data seeding only. Frontend wiring lives in the astro scope references (`../astro/stores/SHARED_WIRING.md`, `../astro/stores/PRODUCT_PAGES.md`, `../astro/ecom/CART_PAGES.md`, `../astro/stores/HOME_AND_NAV.md`) and should not be read by `seed-seed`.
 
 > **Critical Rules — Read Before Starting**
 > 1. **V3 only** — all endpoints under `/stores/v3/...` for products.
-> 2. **No improvised endpoints** — if an MCP call returns 404, stop and report. Do not guess alternative URLs. Do not loop on `SearchWixRESTDocumentation` more than twice on the same topic.
+> 2. **No improvised endpoints** — if an REST call returns 404, stop and report. Do not guess alternative URLs. Do not loop on `docs-search REST (see DOCS_SEARCH.md)` more than twice on the same topic.
 > 3. **Do not seed categories.** Categories are merchant-driven — created in the Wix dashboard, not by this scope. The storefront's rail, Shop submenu, and `/category/[slug]` route are still wired (Phase 4) and light up automatically once the merchant adds at least one visible category with items (≤ 5 min after creation, the helper's TTL).
 
 > **V3 Catalog:** New Wix sites use Catalog V3. All endpoints below live under `/stores/v3/...`. The V1 product endpoints should not be used — they silently return 0 results on V3 catalogs.
 
 ## Prerequisites
 
-- Wix Stores app must be installed on the site (via MCP after scaffolding, or installed via MCP if missing — see Step 0)
+- Wix Stores app must be installed on the site (installed via the apps-installer REST endpoint after scaffolding — see Step 0)
 
-## Setup: Replace Default Products via MCP
+## Setup: Replace Default Products via REST
 
 > **Conditional:** This section only applies when ALL of these are true:
 > - The Stores app was just installed (default sample products exist)
-> - Wix MCP tools are available (`mcp__wix-mcp-remote__CallWixSiteAPI` exists)
+> - CLI auth works (`npx @wix/cli@latest token --site "$SITE_ID"` returns a token)
 > - Discovery context is available in your prompt (business type, brand name, style)
 >
-> **If MCP tools are not available, skip this entire section.** The 12 default products remain and can be customized later in the Wix dashboard.
+> **If CLI auth is not available, skip this entire section.** The 12 default products remain and can be customized later in the Wix dashboard.
 
-> **API error guard:** If any MCP call in Phase 1 returns a 404 or an unexpected error, do **not** retry the same call with a guessed alternative URL or namespace. Report the failing endpoint, request body, and error verbatim to the user, then stop. Improvised endpoints have caused multi-minute silent stalls in past runs.
+> **API error guard:** If any REST call in Phase 1 returns a 404 or an unexpected error, do **not** retry the same call with a guessed alternative URL or namespace. Report the failing endpoint, request body, and error verbatim to the user, then stop.
 
 > **Stores appDefId** for install and `catalogReference.appId`: `215238eb-22a5-4c36-9e7b-e7c08025e04e`. (A different defId — `1380b703-ce81-ff05-f115-39571d94dfcd` — is used for `wixMetadata.appDefId` in Phase 2. Do not swap them.)
 
@@ -30,16 +30,16 @@ Replace the default sample products Wix Stores installs with on-brand products v
 
 Before querying products, verify the Stores app is installed:
 
-1. **Probe** — `CallWixSiteAPI: POST /stores/v3/products/query` with body `{ "query": { "paging": { "limit": 1 } } }`
+1. **Probe** — `REST: POST https://www.wixapis.com/stores/v3/products/query`
 2. **If the API returns a "REQUIRED_APP_NOT_INSTALLED" error** → install the Wix Stores app:
    ```
-   CallWixSiteAPI: POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install
+   REST: POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install
    body: {
      "tenant": { "tenantType": "SITE", "id": "<siteId>" },
      "appInstance": { "appDefId": "215238eb-22a5-4c36-9e7b-e7c08025e04e", "enabled": true }
    }
    ```
-   > Translate this prose-HTTP form into the full `CallWixSiteAPI` tool-call shape — include `siteId`, `reason`, `sourceDocUrl` wrapper fields and pass `body` as a real object (NOT a stringified JSON). See `../../shared/MCP_PREFIX.md` § "CallWixSiteAPI call conventions".
+   > Translate this prose-HTTP form into the full `curl` tool-call shape — pass `body` as JSON in `-d` (NOT a stringified JSON). See `../shared/AUTHENTICATION.md` for the standard REST headers.
 
    Then retry the probe query to confirm installation succeeded.
 3. **If the probe succeeds** → proceed to Step 1.
@@ -51,7 +51,7 @@ Replace the 12 generic sample products with 3 on-brand products that match the u
 ### Step 1: Query Default Products
 
 ```
-CallWixSiteAPI: POST /stores/v3/products/query
+REST: POST https://www.wixapis.com/stores/v3/products/query
 body: {
   "query": {
     "paging": { "limit": 50 }
@@ -64,7 +64,7 @@ Collect all product IDs from the response.
 ### Step 2: Bulk Delete Defaults
 
 ```
-CallWixSiteAPI: POST /stores/v3/bulk/products/delete
+REST: POST https://www.wixapis.com/stores/v3/bulk/products/delete
 body: {
   "productIds": ["<id1>", "<id2>", ..., "<id12>"]
 }
@@ -98,7 +98,7 @@ Adapt names, descriptions, and pricing to match the brand's tone and style. Use
 **Product with variants** (e.g., skincare with 30ml/50ml sizes):
 
 ```
-CallWixSiteAPI: POST /stores/v3/bulk/products-with-inventory/create
+REST: POST https://www.wixapis.com/stores/v3/bulk/products-with-inventory/create
 body: {
   "products": [
     {
@@ -183,7 +183,7 @@ Include all products in the same `products` array. Do not include `media` — pr
 ### Step 5: Verify
 
 ```
-CallWixSiteAPI: POST /stores/v3/products/query
+REST: POST https://www.wixapis.com/stores/v3/products/query
 body: {
   "query": { "paging": { "limit": 50 } }
 }
@@ -201,11 +201,11 @@ If the merchant later creates visible categories in the Wix dashboard and assign
 - The `Navigation` Shop submenu lists the categories.
 - `/category/<slug>` becomes a reachable, server-side-filtered listing.
 
-This works because the frontend (`src/utils/categories.ts`, written by the `pages-categories` scope in Phase 4) live-queries the Wix API at SSR time with a 5-min cache — no redeploy or regen is needed.
+This works because the frontend (`src/utils/categories.ts`, pre-copied by the orchestrator before Phase 4 and imported by the `pages-*` scopes) live-queries the Wix API at SSR time with a 5-min cache — no redeploy or regen is needed.
 
 ### Step 7: Return Results
 
-Emit a structured JSON block at the end of your completion message per `../../shared/RETURN_CONTRACT.md`. Do NOT write a sidecar file.
+Emit a structured JSON block at the end of your completion message per `../shared/RETURN_CONTRACT.md`. Do NOT write a sidecar file.
 
 ```json
 {
@@ -246,4 +246,4 @@ Phase 1 is complete after Step 7. Do **not** attempt any of the following, even
 - Creating, renaming, or deleting any category — categories are merchant-driven (see Step 6). The auto-managed "All Products" category (handle `online_stores_all_products`) stays in place; the frontend filters it out by handle.
 - Verifying your work via additional `query` calls beyond the Step 5 verification already performed.
 
-Phase 2+ (frontend wiring) is covered in the scope-specific references (`SHARED_WIRING.md`, `PRODUCT_PAGES.md`, `CATEGORY_PAGES.md`, `CART_CHECKOUT.md`, `HOME_AND_NAV.md`) — do not read them during `seed-seed`.
+Phase 2+ (frontend wiring) is covered in the astro scope references (`../astro/stores/SHARED_WIRING.md`, `../astro/stores/PRODUCT_PAGES.md`, `../astro/stores/CATEGORY_PAGES.md`, `../astro/ecom/CART_PAGES.md`, `../astro/stores/HOME_AND_NAV.md`) — do not read them during `seed-seed`.