@wix/agent-skills 1.7.0 → 1.9.0

package/skills/wix-headless/references/custom/ecom/WIRING.md

@@ -0,0 +1,67 @@
+---
+name: custom-ecom-wiring
+description: "Integration-mode wiring subagent for the ecom capability. Wires add-to-cart + checkout into a brought-in static site — @wix/ecom currentCart + a redirect to Wix-hosted checkout, client-side via @wix/sdk from CDN. No SSR cart-persistence (deferred); cart lives in the visitor session + a checkout redirect."
+---
+
+# Ecom wiring (integration mode)
+
+You wire the **ecom capability** (add-to-cart + checkout) into a brought-in static site (`frontend = "custom"`). Pairs with the **stores** guide (which renders products). Client-side vanilla JS, `@wix/sdk` from CDN, no build. Read `INSTRUCTIONS.md` § "The technical spine" + § "Wiring discipline" first.
+
+> **Scope.** Beta does **add-to-cart + redirect-to-Wix-hosted-checkout** via the visitor session. A persistent on-page cart UI across reloads needs the server runtime (`@wix/astro`) — **deferred**. Checkout itself happens on Wix's hosted page, so payment/fulfillment need no client work.
+
+## Inputs
+
+- **`appId`** — `OAuthStrategy` `clientId`.
+- Binding-map / design controls: the "Add to cart" / "Buy" buttons (with the product/variant id available, e.g. from the stores wiring's `data-product-id`).
+
+## Add to cart + checkout
+
+```html
+<script type="module">
+  import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1";
+  import { currentCart } from "https://esm.sh/@wix/ecom@1";
+  import { redirects } from "https://esm.sh/@wix/redirects@1";
+
+  const wix = createClient({ modules: { currentCart, redirects }, auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }) });
+
+  // Add to cart — buttons carry data-product-id (set by the stores wiring)
+  document.querySelectorAll("[data-add-to-cart]").forEach((btn) => {
+    btn.addEventListener("click", async () => {
+      btn.disabled = true;
+      try {
+        await wix.currentCart.addToCurrentCart({
+          lineItems: [{
+            catalogReference: {
+              appId: "215238eb-22a5-4c36-9e7b-e7c08025e04e", // Wix Stores catalog appId (constant)
+              catalogItemId: btn.dataset.productId,
+            },
+            quantity: 1,
+          }],
+        });
+        document.querySelector("[data-cart-badge]")?.replaceChildren(document.createTextNode("•"));
+      } catch (err) { console.error("[wix-ecom] add-to-cart failed:", err); }
+      finally { btn.disabled = false; }
+    });
+  });
+
+  // Checkout — create a checkout from the current cart, then redirect to Wix-hosted checkout
+  document.querySelector("[data-checkout]")?.addEventListener("click", async () => {
+    try {
+      const { checkoutId } = await wix.currentCart.createCheckoutFromCurrentCart({ channelType: "WEB" });
+      const { redirectSession } = await wix.redirects.createRedirectSession({
+        ecomCheckout: { checkoutId },
+        callbacks: { postFlowUrl: location.href },
+      });
+      if (redirectSession?.fullUrl) location.assign(redirectSession.fullUrl);
+    } catch (err) { console.error("[wix-ecom] checkout failed:", err); }
+  });
+</script>
+```
+
+- **`currentCart`** APIs only — never the `cart` namespace that needs a cart ID.
+- The Wix Stores catalog `appId` (`215238eb-…`) is a platform constant (the catalog provider), distinct from the site's OAuth `appId`/`clientId`.
+- Cart badge is a minimal indicator; a full cart-contents page is out of Beta scope (no SSR persistence).
+
+## Discipline & return
+
+Additive; inline the site `appId`; guard calls. Return per `shared/RETURN_CONTRACT.md`: files edited, controls wired (add-to-cart count, checkout button), and note that persistent cart UI is deferred.

package/skills/wix-headless/references/custom/forms/WIRING.md

@@ -0,0 +1,101 @@
+---
+name: custom-forms-wiring
+description: "Integration-mode wiring subagent for the forms capability. Connects a brought-in static site to Wix Forms — wires an existing <form> to submit via @wix/forms, OR injects a new connected form (RSVP / lead / contact) styled from the design's CSS tokens. Client-side @wix/sdk + OAuthStrategy visitor session, loaded from CDN. The universal connection floor for integration mode."
+---
+
+# Forms wiring (integration mode)
+
+You wire the **forms capability** into a brought-in static site for `wix-headless` integration mode (`frontend = "custom"`). Forms is the **universal connection floor** — when a design has no dynamic content, a domain-appropriate form (RSVP, lead, contact) is the connection that makes it live.
+
+You write **client-side, vanilla JS** — no React, no build step. `@wix/sdk` + `@wix/forms` load from a CDN; the HTML *is* the deployable. Read `INSTRUCTIONS.md` § "The technical spine" and § "Wiring discipline" before starting.
+
+## Inputs (inlined by the orchestrator)
+
+- **`appId`** — from `wix.config.json`; the `OAuthStrategy` `clientId`.
+- **`formId`** — the Wix Form created at Seed time (Seed creates the form definition from the augmentation spec's `fields`, with `postSubmissionTriggers.upsertContact` so submissions create CRM contacts). Never hardcode or invent a form ID — if it's missing, fail loudly.
+- **`fields`** — each `{ name, label, type, required, options?, target }`. The **`target`** is the Wix field key the submission map uses (from the created form's schema). If only `name` is known, the orchestrator resolves `target` from the seeded form schema before dispatch.
+- **The augmentation spec** (`injectAt`, `styleFrom`) and/or a binding-map entry (an existing `<form>` to wire).
+- **`tokens`** — the design's resolved CSS custom properties for styling.
+
+## Two cases
+
+### A. Augment — inject a new connected form (the static-design path)
+
+The design has no form (e.g. a wedding invitation). Inject one at `augmentation.injectAt`.
+
+1. **Build the `<form>` markup** from `fields`, styled with the design's tokens. Use the site's existing CSS custom properties (`var(--…)`) and font/spacing variables verbatim so the form reads as designed-in. Reuse the page's section/heading rhythm (match an existing `section`'s padding, an existing heading's font). Each input's `name` attribute = the field's `target`.
+2. **Insert** at `injectAt` (e.g. `position: "before"` the `section.closing`). Additive only — do not alter surrounding markup or the global `<style>`. Put the form's own CSS in a single scoped `<style>` block that references the design tokens.
+3. **Wire submission** with the script below.
+
+### B. Wire — connect an existing `<form>` (the form-shaped-design path)
+
+The design already has a `<form>` (binding-map entry, `entity: "forms.submit"`). Map its inputs' `name`/`id` to the form's field `target`s, intercept submit, and post via the SDK. Keep the existing markup and styling; only add the submit handler script.
+
+## The submission script (both cases)
+
+Append one `<script type="module">` (before `</body>`). Inline the literal `appId` and `formId`.
+
+```html
+<script type="module">
+  import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1";
+  import { submissions } from "https://esm.sh/@wix/forms@1";
+
+  const wix = createClient({
+    modules: { submissions },
+    auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }), // appId from wix.config.json
+  });
+
+  const FORM_ID = "REPLACE_WITH_FORM_ID";
+  const form = document.querySelector("#wix-rsvp-form"); // the injected/targeted form
+
+  form?.addEventListener("submit", async (e) => {
+    e.preventDefault();
+    const btn = form.querySelector("[type=submit]");
+    if (btn) btn.disabled = true;
+
+    // keys MUST be the Wix field `target`s (input name="<target>")
+    const data = Object.fromEntries(new FormData(form).entries());
+
+    try {
+      const result = await wix.submissions.createSubmission({
+        formId: FORM_ID,
+        submissions: data,
+      });
+      if (result.status === "PENDING" || result.status === "CONFIRMED") {
+        form.querySelector("[data-wix-success]")?.removeAttribute("hidden");
+        form.reset();
+      } else {
+        throw new Error("unexpected submission status: " + result.status);
+      }
+    } catch (err) {
+      console.error("[wix-forms] submission failed:", err);
+      form.querySelector("[data-wix-error]")?.removeAttribute("hidden");
+      // surface field-level violations if present
+      const violations = err?.details?.validationError?.fieldViolations ?? [];
+      for (const v of violations) {
+        for (const fe of (v?.data?.errors ?? [])) {
+          const el = form.querySelector(`[name="${fe.errorPath}"]`);
+          if (el) el.setAttribute("aria-invalid", "true");
+        }
+      }
+    } finally {
+      if (btn) btn.disabled = false;
+    }
+  });
+</script>
+```
+
+- Include a hidden success node (`<p data-wix-success hidden>…</p>`) and error node (`<p data-wix-error hidden>…</p>`) in the form markup, styled with the tokens.
+- The submission `data` keys are the field **`target`s** — set each input's `name` to its `target`.
+- Pin the CDN versions (`@1`) in the import URLs; do not float `@latest` in shipped HTML.
+
+## Discipline (from `INSTRUCTIONS.md`)
+
+- **Additive only** — never restructure the design or edit the global stylesheet; the injected form is self-contained.
+- **Style from tokens** — use `var(--…)` from the site's `:root`; never introduce a foreign palette/font.
+- **Guard the call** — try/catch; on failure show the error node, keep the form usable.
+- **Inline `appId` + `formId` literally** — no env vars, no build-time substitution.
+
+## Return
+
+Per `shared/RETURN_CONTRACT.md`: report the file(s) edited, the inject anchor used, the `formId` wired, and the form's `target`→input mapping. If `formId` was missing, return `status: "failed"` with `errors: [{ code: "FORM_NOT_SEEDED" }]` — do not invent one.

package/skills/wix-headless/references/custom/stores/WIRING.md

@@ -0,0 +1,80 @@
+---
+name: custom-stores-wiring
+description: "Integration-mode wiring subagent for the stores capability. Connects a brought-in static site's product markup to Wix Stores — replaces hard-coded product cards with live productsV3 queries rendered into the existing DOM template, client-side via @wix/sdk + @wix/stores from CDN. Cart-add + checkout via the ecom guide."
+---
+
+# Stores wiring (integration mode)
+
+You wire the **stores capability** into a brought-in static site (`frontend = "custom"`). The design already shows products as **hard-coded sample cards**; you replace the sample data with live `@wix/stores` queries, rendering into the **existing card markup** the design provides. Client-side vanilla JS, `@wix/sdk` from CDN, no build. Read `INSTRUCTIONS.md` § "The technical spine" + § "Wiring discipline" first.
+
+## Inputs (inlined by the orchestrator)
+
+- **`appId`** — `OAuthStrategy` `clientId` (from `wix.config.json`).
+- **Binding-map entries** for `stores.products` regions: `{ file, anchor, shape, template, bindings, sampleCount }`.
+- **Seeded `productIds` / slugs** (from Seed) — so the wired query shows the seeded catalog.
+- **`tokens`** — design CSS custom properties (only needed if you add an empty-state node).
+
+## The read-and-render pattern (this is the core; blog/cms reuse it)
+
+For each binding-map list region:
+
+1. **Keep the first sample child as the template.** The region (`anchor`) holds `sampleCount` near-identical children matching `template` (e.g. `article.product-card`). Clone that node per result; remove the remaining static samples. Do **not** restyle — the existing classes carry the design.
+2. **Query live data** and **bind fields** by the binding-map `bindings` map (DOM selector relative to template → entity field path).
+3. **Render on load**, guard with try/catch; on error leave the original samples visible.
+
+```html
+<script type="module">
+  import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1";
+  import { productsV3 } from "https://esm.sh/@wix/stores@1";   // V3 — never the V1 `products`
+
+  const wix = createClient({
+    modules: { productsV3 },
+    auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }),
+  });
+
+  const grid = document.querySelector("section.product-grid");      // binding-map anchor
+  const tpl  = grid?.querySelector("article.product-card");          // binding-map template
+  if (grid && tpl) {
+    try {
+      const { items } = await wix.productsV3
+        .queryProducts({ fields: ["CURRENCY"] })
+        .limit(12)
+        .find();
+
+      const proto = tpl.cloneNode(true);
+      grid.replaceChildren(...items.map((p) => {
+        const card = proto.cloneNode(true);
+        // bindings: selector@attr → field path   (e.g. "img.thumb@src" → media.mainMedia.image.url)
+        const img = card.querySelector("img.thumb"); if (img) img.src = p.media?.mainMedia?.image?.url ?? "";
+        const name = card.querySelector("h3.name");  if (name) name.textContent = p.name ?? "";
+        const price = card.querySelector("span.price"); if (price) price.textContent = p.priceData?.formatted?.price ?? "";
+        // description is RICH TEXT — bind plainDescription, never the HTML `description` (see note below)
+        const desc = card.querySelector(".description"); if (desc) desc.textContent = p.plainDescription ?? (p.description ?? "").replace(/<[^>]*>/g, "");
+        // link to a detail page if the design has one (see "Detail" below)
+        const link = card.querySelector("a"); if (link && p.slug) link.href = `/product/${p.slug}`;
+        return card;
+      }));
+    } catch (err) {
+      console.error("[wix-stores] product query failed:", err);   // leave samples visible
+    }
+  }
+</script>
+```
+
+- **Use `productsV3`**, never V1 `products` (V1 silently returns 0 on V3 catalogs).
+- **Description is rich text — bind `p.plainDescription`, never `p.description`.** `description` is HTML/ricos; binding it into `textContent` (or a framework `{…}` expression) renders literal `<p>…</p>` tags. Use `plainDescription` (a plain string), falling back to `description.replace(/<[^>]*>/g, "")` if absent.
+- **(create × own only — N/A for brought-in static sites.)** When you *own* the markup (the SPA is generated, not brought in), size every image: Wix media URLs are full-resolution, so an `<img>` with no sizing overflows its card onto the text. Put each image in a fixed `aspect-ratio`/`height` slot with `width:100%; height:100%; object-fit:cover`. A brought-in static site is already sized by its own design — skip this.
+- Apply the binding-map's actual selectors/field paths — the snippet's `img.thumb`/`h3.name`/`span.price`/`.description` are illustrative.
+- **Categories:** if a region is `categoriesV3`, query `wix.categoriesV3.queryCategories().eq("visible", true).find()` (the builder rejects empty filters — always chain at least one predicate).
+
+## Detail (`shape: "detail"`)
+
+If the design has a product-detail page keyed by slug, read the slug from the URL (`location.pathname`), `queryProducts().eq("slug", slug).find()`, and bind the single result into the detail markup. If there is no detail page, link cards to the catalog or omit links.
+
+## Buy / cart
+
+Add-to-cart and checkout are the **ecom** capability — see `references/custom/ecom/WIRING.md`. If a card has a "Buy"/"Add" control and ecom is in the capability set, the ecom guide wires it; otherwise leave it inert or link to the product.
+
+## Discipline & return
+
+Additive only; render into the existing template; inline `appId`; guard every call (samples are the error fallback). Return per `shared/RETURN_CONTRACT.md`: files edited, anchors wired, query used, seeded IDs surfaced. Missing seeded catalog → note it; the empty query still wires (Seed should have populated it).

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

@@ -5,17 +5,17 @@ description: "Implements vertical-agnostic ecommerce — cart page, checkout red
 
 # Ecom 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
 
 | Scope | Phase | Reference |
 |-------|-------|-----------|
 | `components` | Components (CartView, CartBadge — TSX only, **no CSS**) — `src/utils/discounts.ts` is pre-copied by the orchestrator | `../astro/ecom/CART_WIRING.md` |
-| ~~`components-css`~~ | **Do not dispatch.** `src/styles/components-ecom.css` is copied from `<SKILL_ROOT>/references/astro/templates/ecom/components-ecom.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-ecom.css` is copied from `<SKILL_ROOT>/references/astro/templates/ecom/components-ecom.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` | Pages (cart.astro, thank-you.astro, Navigation CartBadge mount) | `../astro/ecom/CART_PAGES.md` |
 
-> **Why `components` is split.** A single agent writing the .tsx islands plus the scoped CSS was Phase 3's critical path on the most recent run (204 s for ecom alone). 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. Mirrors the stores split. See `../astro/ecom/COMPONENTS_CSS.md` § "What this scope owns".
+> **Why `components` is TSX-only.** The scoped CSS (`src/styles/components-ecom.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 the `components-css` scope-routing row above) rather than being written by an agent. Mirrors the stores split. See `../astro/ecom/COMPONENTS_CSS.md` § "What this scope owns".
 
 Note: `ecom` is never triggered independently — it's co-loaded by verticals that require it (`stores` today; `bookings`, `events` in the future). No `seed` scope — ecom has no data of its own; it works off line items from whichever catalog app is installed.
 
@@ -29,7 +29,7 @@ Components (`components` scope — TSX only):
 - `<SKILL_ROOT>/references/astro/templates/ecom/CartView.tsx`
 - `<SKILL_ROOT>/references/astro/templates/ecom/CartBadge.tsx`
 
-Components CSS (`components-css` scope — scoped CSS only):
+Components CSS (pre-copied by the orchestrator — no agent writes it):
 - `<SKILL_ROOT>/references/astro/templates/ecom/components-ecom.css`
 
 ### Pre-copied by the orchestrator (do NOT write this yourself)
@@ -40,7 +40,7 @@ Components CSS (`components-css` scope — scoped CSS only):
 
 ## CSS ownership — ecom pack
 
-Ecom-specific component CSS lives in `src/styles/components-ecom.css` (written by your `components` scope), NOT in the designer's `global.css`. The classes you own:
+Ecom-specific component CSS lives in `src/styles/components-ecom.css` (pre-copied from the template by the orchestrator before Step 4.5 — see the `components-css` scope-routing row above; your `components` scope imports it, never writes it), NOT in the designer's `global.css`. The classes the pack owns:
 
 - `.cart-summary` — the bordered/sticky summary panel on `/cart`. Compound bordered card; sticky on desktop.
 - `.cart-total` — the row inside the summary that anchors the total amount with a top rule and display-serif typography.

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

@@ -5,7 +5,7 @@ description: "Implements contact, lead, and signup forms via @wix/forms. Scopes:
 
 # Forms 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
 
@@ -17,7 +17,7 @@ Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routi
 
 ## Files this vertical creates / contributes
 
-See `<SKILL_ROOT>/references/verticals/forms.md` frontmatter.
+Each scope's files are enumerated in `../astro/forms/CONTACT_FORM.md` (§ Form Setup, § React island, § Page wiring).
 
 ## Form purpose variants
 

package/skills/wix-headless/references/gift-cards/INSTRUCTIONS.md

@@ -5,7 +5,7 @@ description: "Implements the passive Wix Gift Cards vertical — runtime probe u
 
 # Gift Cards 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
 
@@ -18,11 +18,11 @@ This pack has **no `seed` scope** — the dashboard's eGift Card template is the
 
 ## Files this vertical creates / contributes
 
-See `<SKILL_ROOT>/references/verticals/gift-cards.md` frontmatter (`creates:` and `contributes:` blocks).
+See the § "Templates" list below for the files each scope produces (and the nav/home contributions it patches).
 
 ## Pre-return file-existence assertion (pages scope)
 
-Before returning `status: "complete"` from the `pages` scope, verify every file in `creates:` (phase: pages) plus the patched files in `contributes:` exists on disk. If a declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]` rather than claiming success.
+Before returning `status: "complete"` from the `pages` scope, verify every file the scope produces (the page templates in § "Templates" below, plus the patched `Navigation.astro` / `index.astro`) exists on disk. If a declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]` rather than claiming success.
 
 ## Templates
 

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

@@ -36,11 +36,15 @@ If your prompt is missing a `Scope:` line, stop and ask the parent — do not gu
    - **400** `unsupportedDimensions` → see § "Error Handling"
    - **400** `invalidTaskUUID` → `taskUUID` must be valid UUIDv4 → see § "Quick Reference"
 
-## Quick Reference: Generation Call Shape
+## Preferred: generate + import via `generate-images.mjs`
 
-Before the first REST call, ensure the `curl` tool schema is loaded (the orchestrator's session auth covers this for the whole session per `<SKILL_ROOT>/references/commands/AUTHENTICATION.md` — only re-load if you hit a tool-not-found error). Use your runtime's AUTHENTICATION.md recovery ladder to look up the suffix.
+**Run the phase's generation + Wix Media import through `<SKILL_ROOT>/scripts/generate-images.mjs`** (see `../shared/IMAGE_GENERATION.md` § "Preferred: run the whole phase through `generate-images.mjs`"). Build the image list — one entry per slot (Phase 1) or per entity (Phase 2), each with `{key, positivePrompt, width, height}` — and pipe it in with the run's cached `WIX_TOKEN`. The script fires all generations concurrently in-process and returns a `key → {url, fileId}` map plus a `slots` (key→url) convenience map. This is the deterministic form of the "one concurrent batch" rule — it cannot serialize and cannot hit the `google:4@2` N≥3 504. Then attach: Phase 1 → `write-decorative-json.mjs`; Phase 2 → the per-entity PATCH/PUT/publish recipe in this file. **You still own prompt construction** (brand-contextual, per the guidelines) and **entity attachment**; the script owns the parallel network round-trips only.
 
-**All generation tool calls for an image phase MUST be in one concurrent batch.** The exact shape depends on the model — see `../shared/IMAGE_GENERATION.md` § "Required: minimize round-trips" for the rule. In short:
+## Quick Reference: Generation Call Shape (manual fallback)
+
+The shapes below are the **reference bodies** the script builds, and the **fallback** if you hand-drive generation. Before the first REST call, ensure the `curl` tool schema is loaded (the orchestrator's session auth covers this for the whole session per `<SKILL_ROOT>/references/shared/AUTHENTICATION.md` — only re-load if you hit a tool-not-found error). Use your runtime's AUTHENTICATION.md recovery ladder to look up the suffix.
+
+**If you do hand-drive it, all generation tool calls for an image phase MUST be in one concurrent batch.** The exact shape depends on the model — see `../shared/IMAGE_GENERATION.md` § "Required (manual fallback): minimize round-trips" for the rule. In short:
 
 - **`google:4@2` (the default):** N concurrent 1-task `curl` calls as siblings in one batch. (Batched N≥3 times out at 504 on this model.)
 - **`bfl:5@1`, `runware:400@1`:** one batched `curl` call with N tasks in the body array.
@@ -108,12 +112,12 @@ Generate site-wide decorative images that don't depend on any entity. Used by th
 **Process (must follow this order):**
 
 1. **Craft all image prompts up front** using brand context — see `IMAGE_GENERATION.md` § "Prompt guidelines".
-2. **Dispatch all generation tool calls in one concurrent batch** — siblings for `google:4@2` (1 task each, N blocks in parallel), or one batched call for other models (N tasks in `body`). Required, not optional — see `IMAGE_GENERATION.md` § "Required: minimize round-trips per image phase". Sequential 1-task calls across multiple turns is an anti-pattern; never do it.
+2. **Generate + import via `generate-images.mjs`** (preferred — § "Preferred: generate + import" above): build the `images` list (`key` = slot name, e.g. `hero`/`about`) and run the script with the cached `WIX_TOKEN`; it fires all generations concurrently and returns the `slots` map. **Manual fallback only:** follow § "Mandatory pre-call procedure" above (construct ALL tasks first, dispatch in one concurrent batch).
 3. **Import each to Wix Media** via `REST: POST https://www.wixapis.com/site-media/v1/files/import`.
 4. **Collect the resolved URLs keyed by slot purpose** (e.g., `{"hero": "https://static.wixstatic.com/...", "about": "https://static.wixstatic.com/..."}`). This map goes into your return JSON under `data.slots` — see § Return below. Do NOT write `.wix/image-urls.md` or any other file; the orchestrator pipes your `data.slots` directly into `patch-decorative-slots.mjs` via stdin.
 5. Return the structured JSON block per `../shared/RETURN_CONTRACT.md` (see § Return below). The JSON return is your sole output channel.
 
-The orchestrator runs `patch-decorative-slots.mjs` with your `data.slots` map piped in on stdin. The patch script injects `<img>` tags into the designer's `data-decorative-slot="<key>"` placeholders. If your return is missing or has no slots, the patch is a no-op and the placeholders fall back to the designer's solid-color rendering — nothing blocks.
+The orchestrator consumes your `data.slots` map via one of two deterministic scripts, depending on the frontend — **your output contract is identical either way** (a slot→URL map; you never touch frontend source): on **astro** it pipes the map into `patch-decorative-slots.mjs`, which injects `<img>` tags into the designer's `data-decorative-slot="<key>"` placeholders in `.astro` pages; on a **framework-SPA (`own`)** it pipes the map into `write-decorative-json.mjs`, which writes `src/decorative-images.json` for the generated app to import. Either way, if your return is missing or has no slots, the consumer is a no-op and the placeholders fall back to the designer's solid-color (themed-block) rendering — nothing blocks.
 
 ## Scope: `image-phase-2-entity` (Phase 1 Seed data inline)
 
@@ -131,14 +135,11 @@ Generate images for products, blog posts, and CMS items. Attach via REST PATCH c
 **Process per entity type (must follow):**
 
 1. **Craft all image prompts** for this entity type up front, using each entity's own context (name, description, title, etc.).
-2. **Dispatch all generation tool calls in one concurrent batch** — same dispatch shape as Phase 1 Decorative:
-   - For `google:4@2` (default): N parallel sibling `curl` tool calls, one task each.
-   - For `bfl:5@1` / `runware:400@1` / others: ONE batched call with all N tasks in `body`.
-   See `IMAGE_GENERATION.md` § "Required: minimize round-trips per image phase". Sequential 1-task calls across multiple turns is an anti-pattern.
+2. **Generate + import via `generate-images.mjs`** (preferred — § "Preferred: generate + import" above): build the `images` list with `key` = each entity's ID, run the script with the cached `WIX_TOKEN`, and read the returned `map[entityId].url` / `.fileId` for the attach step. The script generates all entity images concurrently and isolates per-image failures (`status: "partial"`) — including the `google:4@2` 504 retry below, handled in-script. **Manual fallback only:** follow § "Mandatory pre-call procedure" above (construct ALL tasks first, dispatch in one concurrent batch).
 
-   **`google:4@2` 504 retry.** Even with N concurrent siblings, individual tasks intermittently 504. When the response array contains an entry with `errorMessage: "Request timed out"` or HTTP 504, retry **only the failing task(s)** in a follow-up batch — do NOT re-dispatch the whole batch. Cap at 1 retry per task; if it 504s twice, fall back to `bfl:5@1` for that task or skip it (entity gets no image; user can upload from dashboard).
+   **`google:4@2` 504 retry** (manual fallback; the script does this for you). Even with N concurrent siblings, individual tasks intermittently 504. When the response array contains an entry with `errorMessage: "Request timed out"` or HTTP 504, retry **only the failing task(s)** in a follow-up batch — do NOT re-dispatch the whole batch. Cap at 1 retry per task; if it 504s twice, fall back to `bfl:5@1` for that task or skip it (entity gets no image; user can upload from dashboard).
 
-   **N≥6 entities — stagger.** When you have 6 or more entities of one type, split into pairs of 3 parallel siblings rather than 6+ in one shot. Runware throttles google:4@2 above ~4 concurrent tasks per request burst, and the timeout ladder gets steeper. Two messages with 3 siblings each is reliably faster than one message with 6 + multiple retries. (Heuristic — refine after more runs collect data.)
+   **N≥6 entities — stagger.** When you have 6 or more entities of one type, split into pairs of 3 parallel siblings rather than 6+ in one shot. Runware throttles google:4@2 above ~4 concurrent tasks per request burst, and the timeout ladder gets steeper. Two messages with 3 siblings each is reliably faster than one message with 6 + multiple retries.
 3. **Import each to Wix Media**. Imports can parallelize.
 4. **PATCH each entity** with its image URL / file ID. PATCH calls can also parallelize (sibling `curl` tool calls in one message).
 
@@ -192,7 +193,7 @@ Generate images for products, blog posts, and CMS items. Attach via REST PATCH c
    2. Retry the PATCH once with the new revision.
    3. If the retry also fails with 409, surface the error — something else is mutating the entity faster than we can react. Don't loop.
 
-   Successful PATCHes from the original parallel batch keep their state; only the 409'd entity needs the recovery. Cap at one retry per failed entity. Append to `run.json.recoveries[]`: `{ "code": "INVALID_REVISION_RETRY", "entityId": "<id>", "originalRevision": "<x>", "actualRevision": "<y>" }`.
+   Successful PATCHes from the original parallel batch keep their state; only the 409'd entity needs the recovery. Cap at one retry per failed entity.
 
 ### Blog Posts (if `blogPosts` is in your prompt)
 
@@ -280,11 +281,11 @@ At the end, emit a structured JSON block per `../shared/RETURN_CONTRACT.md`. Do
   "summary": "Generated N decorative images; uploaded to Wix Media; returned slot→URL map",
   "data": {
     "decorativeCount": 3,
-    "purposes": ["hero", "about", "background"],
+    "purposes": ["hero", "about", "productsHeader"],
     "slots": {
       "hero":  "https://static.wixstatic.com/media/...",
       "about": "https://static.wixstatic.com/media/...",
-      "background": "https://static.wixstatic.com/media/..."
+      "productsHeader": "https://static.wixstatic.com/media/..."
     },
     "model": "google:4@2",
     "totalCredits": 0.297
@@ -336,7 +337,7 @@ The JSON block MUST be the **last** content in your message (see `../shared/RETU
 
 | WRONG | CORRECT |
 |-------|---------|
-| N sequential 1-task `curl` generation calls across multiple turns | All generation tool calls in one concurrent batch — parallel siblings for `google:4@2`, or one batched call for other models. See IMAGE_GENERATION.md § "Required: minimize round-trips per image phase" |
+| N sequential 1-task `curl` generation calls across multiple turns | Run `generate-images.mjs` (it parallelizes in-process); or, hand-driving, all generation tool calls in one concurrent batch — parallel siblings for `google:4@2`, or one batched call for other models. See IMAGE_GENERATION.md § "Required (manual fallback): minimize round-trips" |
 | Poll `.wix/logs/<feature>-data.md` sidecars to learn Phase 1 Seed is done | Phase 1 Seed data is inline in your prompt — if missing, return `failed` |
 | `sleep 60` loop to wait for Phase 1 Seed | No waiting, no polling — prompt has the data or the agent fails |
 | Write `.wix/logs/images.md` or `.wix/image-urls.md` sidecar | Return structured JSON per `RETURN_CONTRACT.md` instead (decorative URLs go in `data.slots`) |

package/skills/wix-headless/references/seed-recipes.md

@@ -8,8 +8,8 @@ Per-vertical recipe lookup for the seed dispatch in `SEED.md`. Recipe paths are
 | cms | `references/cms/cms-schema-management.md` (collection create) + `references/cms/cms-data-items-crud.md` (item create per collection) + `references/cms/cms-references-and-relationships.md` (only when a collection's `intent.cms.collections[N]` declares cross-references) | `collectionIds{}`, `itemIds{<collection>: []}` |
 | blog | `references/blog/how-to-create-blog-posts.md` | `postIds[]`, `categoryIds[]` |
 | forms | `references/forms/create-form.md` | `formIds[]` |
-| gift-cards | — (no seed surface; activation lives in Phase 2 app-install) | `{status: "skipped"}` |
-| ecom | — (cart/checkout vertical; no seed surface) | `{status: "skipped"}` |
+| gift-cards | — *(no recipe by design — no seed surface; activation lives in Phase 2 app-install)* | `{status: "skipped"}` |
+| ecom | — *(no recipe by design — cart/checkout vertical; no seed surface)* | `{status: "skipped"}` |
 
 The orchestrator dispatches one subagent per pack with a recipe. `gift-cards` and `ecom` get a phase entry of `{phase: "seed-<pack>", status: "skipped"}` recorded directly by the orchestrator without dispatching a subagent.
 

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

@@ -0,0 +1,47 @@
+# AGENTS.md — the end-of-run site doc
+
+The orchestrator writes one file at the end of a successful run: a project-root `AGENTS.md` describing **what the site has**. It is the one end-of-run artifact — *content about the site*, not telemetry. A fresh session (or a coding agent) opening the project reads it to learn what's there.
+
+## Author, location, timing
+
+- **Author:** the orchestrator, in the final turn. Composed **from session scratch** (brand, frontend, verticals, the page/route list it built) **+ `.wix/seeded.json`** (entity counts). **Re-read nothing** to compose it.
+- **Location:** project-root `AGENTS.md` — the conventional path agents auto-read. Root, not `.wix/`. It sits outside the astro/Vite bundler root, so it never ships to `dist/`.
+- **Timing:** the **last tool call of the final message**. Summary prose (the live URL) first; `Write AGENTS.md` last — same ordering discipline `BUILD.md` § "Final Message" defines.
+
+## Content — fill this template, slotted values only
+
+Deterministic projection of scratch + seeded counts → same inputs produce a byte-identical file. Emit exactly these sections; no free prose beyond the slots.
+
+```markdown
+# <brand>
+
+A Wix headless site built with the `wix-headless` skill. <one-line brand description>.
+
+## Live site
+- **Site:** <published URL>
+- **Dashboard:** https://manage.wix.com/dashboard/<siteId>
+
+## Frontend
+<astro (Wix-hosted) | custom>. Run: `<wix dev | npm run dev>`. Build + publish: `<wix release | npm run build then wix release>`.
+
+## Features
+- <one bullet per loaded, non-disabled vertical, in plain language>
+  Stores → a product catalog · CMS → content collections (About, FAQ, …) · Blog → posts · Forms → a contact form · Gift cards → activate from the dashboard
+
+## Pages
+<one line per route that exists: `/`, `/products`, `/products/[slug]`, `/cart`, …>
+
+## Seeded content
+<counts only: "3 products across 2 categories · 6 blog posts · About + FAQ collections.">
+
+## Extending
+Built with the `wix-headless` skill; re-run it to add features or restyle.
+```
+
+## Excluded — never in AGENTS.md
+
+No per-phase timings, statuses, `started`/`ended`/`seconds`, `x-wix-request-id`s, error codes, subagent handles, recoveries, or rate-limit notes. If a field would only matter to someone debugging the *run*, it does not belong here. (Entity IDs stay in `.wix/seeded.json`, not here — counts only.)
+
+## Not a state file
+
+`AGENTS.md` is reading material. Project **detection** ("is this a wix-headless project / which frontend") keys off `wix.config.json` + the `@wix/astro` dep in `package.json` — never `AGENTS.md` presence.

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

@@ -19,7 +19,7 @@ The "stop and tell the user" path is a **last-resort fallback** for when the bac
 {"event":"awaiting_user","expiresInSeconds":600,"userCode":"TPV5HUG5","verificationUri":"https://users.wix.com/login/device-login?color=developer&studio=true"}
 ```
 
-(Earlier revisions of this doc claimed the CLI wrote human-readable prose to stderr with no JSON events — that was wrong. The events are JSON on stdout. There may be incidental Node warnings interleaved; line-by-line JSON parsing with a `try` around each line handles that cleanly.)
+The events are JSON on stdout. There may be incidental Node warnings interleaved; line-by-line JSON parsing with a `try` around each line handles that cleanly.
 
 ### How to invoke — exact shape
 
@@ -79,7 +79,7 @@ The body is the recipe's documented JSON payload, with `siteId` inlined where th
 
 ## Recovery ladder
 
-**Do not re-mint the token as a recovery step** (see token-minting note above — a re-minted token is byte-identical). Retry the *same* call with the *same* cached token.
+**Re-mint is never a recovery step — see Token minting.** Retry the *same* call with the *same* cached token.
 
 | Symptom | First response | If it still fails |
 |---|---|---|
@@ -105,6 +105,4 @@ SITE_TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")
 
 **Do not share tokens across scopes.** Site-operating calls (`wixapis.com/stores/v3/...`, `/blog/v3/...`, `/wix-data/v2/...`) need the **site** token + `wix-site-id` header; using the account token returns `403 SITE_TOKEN_REQUIRED`. Account-level calls (`manage.wix.com/credit-transactions/...`, `/subscriptions/...`) need the **account** token alone — no `wix-site-id` header; using the site token returns `403 ACCOUNT_TOKEN_REQUIRED`.
 
-Today the only account-scoped call in the skill is the Discovery Q3 balance lookup (`DISCOVERY.md` § 2.5.2). If a future phase needs another, mint a fresh account token at the call site (do not cache across the run alongside the site token — keep them in separate scratch slots so misuse is hard).
-
-**Historical note.** Earlier revisions of this file said the CLI did not expose an account-scoped primitive and concluded the balance lookup was unrecoverable. That was a misreading of `wix token --help` — the help output reads `Get a site-scoped access token` against `--site`, implying (correctly) that omitting `--site` returns the default, account-scoped token. The balance lookup was disabled for no good reason for several runs.
+Today the only account-scoped call in the skill is the Discovery Q3 balance lookup (`DISCOVERY-create.md` § 2.5.2). If a future phase needs another, mint a fresh account token at the call site (do not cache across the run alongside the site token — keep them in separate scratch slots so misuse is hard).

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

@@ -0,0 +1,85 @@
+# DESIGN.md — the design-token format (vendored spec)
+
+`DESIGN.md` is the **single design artifact** of the wix-headless design-system phase. The Designer authors it; `emit-design-tokens.mjs` writes it + projects `.wix/design-tokens.css` and `.wix/site.d.ts` from it; `compose.mjs` reads its **frontmatter** to write the astro design-system files. It is the standalone, framework-agnostic spec a non-astro frontend, a human, or another tool can read.
+
+This file is the **canonical spec inside the skill** — the public DESIGN.md frontmatter format (the `design.md` spec, captured here) plus the small, documented extensions this skill uses. Do not depend on the external `design.md` project at runtime.
+
+## Frontmatter structure
+
+A `DESIGN.md` file is YAML frontmatter delimited by `---`, optionally followed by a free-form markdown body:
+
+```yaml
+---
+version: alpha          # optional
+name: <string>          # the brand / design-system name
+colors:
+  <token-name>: <Color>
+typography:
+  <token-name>:
+    fontFamily: <string>
+    fontSize: <Dimension>        # optional (unused by this skill)
+    fontWeight: <number>         # optional
+    lineHeight: <Dimension|number>  # optional
+    letterSpacing: <Dimension>   # optional
+spacing:
+  <scale-level>: <Dimension|number>
+rounded:                # corner radii (DESIGN.md's name for radius tokens)
+  <scale-level>: <Dimension>
+containers:             # EXTENSION (this skill): content/reading widths
+  <scale-level>: <Dimension>
+googleFontsHref: <string>   # EXTENSION (this skill): the ready Google Fonts <link> href
+---
+
+# free-form body — documentation only, NEVER parsed
+```
+
+### Value types
+
+- **Color** — any valid CSS color string (hex `#RRGGBB`, `rgb()`, `hsl()`, named). **Quote hex values** — an unquoted `#hex` after `: ` is a YAML comment.
+- **Dimension** — a string with a unit suffix: `px`, `em`, `rem` (e.g. `"1rem"`, `16px`).
+- **Token reference** — `{path.to.value}` (curly-brace object path into the YAML tree).
+
+## How this skill uses it
+
+### Frontmatter only is canonical
+
+`compose.mjs` and `emit-design-tokens.mjs` read the **frontmatter only**. The markdown body is documentation and is **never parsed** — so a generated `DESIGN.md` can carry a minimal or empty body without affecting the build, and run-to-run body variance never reaches the output.
+
+### Token vocabulary (the groups this skill consumes)
+
+| DESIGN.md group | wix CSS projection | Notes |
+|---|---|---|
+| `colors` | `--color-<key>` | semantic role keys (see color roles below) |
+| `typography.<level>.fontFamily` | `--font-<level>` | `display` + `body` required; `mono` optional |
+| `spacing` | `--spacing-<key>` | full `2xs…4xl` rhythm scale |
+| `rounded` | `--radius-<key>` | `sm` + `md` required |
+| `containers` | `--container-<key>` | **extension** — content widths, a separate axis from spacing (`prose, md, 3xl, 6xl`) |
+| `googleFontsHref` | the Layout `<link>` href | **extension** — the ready stylesheet URL for the chosen families |
+
+### Color roles — wix-native keys are the contract
+
+The skill's component-CSS templates reference a fixed set of `--color-*` names (`STYLING.md` § "Required tokens"). So the **canonical color token keys in our DESIGN.md are the wix editorial roles** — and these are valid DESIGN.md color token names (the format leaves token names free-form):
+
+`paper` (primary background), `paper-warm` (secondary surface), `ink` (primary text / dark fills), `ink-soft`, `mute` (muted text), `rule` (borders / dividers), `accent` (brand emphasis), `cream`, `error`.
+
+`paper`, `paper-warm`, `ink`, `mute`, `rule`, `accent` are **required**; `ink-soft`, `cream`, `error` recommended (derived as a fail-safe if absent).
+
+### Standard-role compatibility (reading an externally-authored DESIGN.md)
+
+A DESIGN.md authored elsewhere may use the DESIGN.md spec's *common* semantic roles instead of the wix-native keys. `compose.mjs` carries a **role-translation table** so such a file is still consumable; wix-native keys are not in the table and pass through unchanged (winning on conflict):
+
+| standard role | → wix `--color-*` | | standard role | → wix `--color-*` |
+|---|---|---|---|---|
+| `primary` | `accent` | | `surface` / `background` | `paper` |
+| `secondary` | `paper-warm` | | `on-surface` / `on-background` | `ink` |
+| `tertiary` | `ink-soft` | | `outline` | `rule` |
+| `neutral` | `mute` | | `error` | `error` |
+
+This translation is a **compatibility layer**, not the authoring path: the Designer in this skill emits the wix-native keys directly (lossless — no role round-trip), so `STYLING.md` and every `components-<pack>.css` template stay untouched.
+
+## Producers & consumers in the run
+
+- **Designer** (`DESIGN_SYSTEM.md`) — **authors `DESIGN.md` directly** (its frontmatter is the spec); returns only the brand-voice strings + the `DESIGN.md` path.
+- **`emit-design-tokens.mjs`** — reads the Designer's `DESIGN.md` and projects `.wix/design-tokens.css` + `.wix/site.d.ts` from its frontmatter. It does **not** write `DESIGN.md` (the Designer does).
+- **`compose.mjs`** — reads `DESIGN.md` frontmatter → writes the 6 astro design-system files (astro only).
+- **Non-astro (`own`) frontends** — import `.wix/design-tokens.css` for the same values; component composition stays framework-native (no `compose.mjs`).