@wix/agent-skills 1.16.1 → 1.16.3

package/skills/wix-manage/references/stores/create-product-catalog-v3.md

@@ -0,0 +1,273 @@
+---
+name: "Create Product (Catalog V3)"
+description: Mandatory first recipe for every Wix Stores Catalog V3 create-product request. Before any mutation, require an explicit name and price for every product; an absent price is never 0. If no product is identified, offer both image-upload and text-description paths and stop. If name or price is missing, ask or offer a suggestion and stop. When both are present, create from the supplied details without requiring optional enrichment. Covers single/bulk creation, inventory, physical/digital products, images, options, variants, SKUs, and validation.
+---
+
+# Create Product (Catalog V3)
+
+Use this recipe for one or multiple Catalog V3 products. Catalog V1 remains supported through [Create Product (Catalog V1)](create-product-catalog-v1.md).
+
+> [!IMPORTANT]
+> **Apply the no-product gate first.** A vague request such as “I’d like to add a new product” does not identify a product. Respond only:
+>
+> **“What product would you like to create? You can upload up to 3 images and I’ll generate the product information from them, or describe the product in text.”**
+>
+> Then end the turn. Do not ask for name, price, product type, options, SEO, inventory, or any other structured field yet. Do not replace the image-or-text choice with a checklist, form, or questionnaire. Reading this recipe must be the final tool call in that turn.
+
+Canonical example:
+
+- User: “For my Wix store, I’d like to add a new product.”
+- Assistant: “What product would you like to create? You can upload up to 3 images and I’ll generate the product information from them, or describe the product in text.”
+- Result: **Stop. Do not request structured product fields yet.**
+
+## Preflight: respond and return before mutation
+
+Name and price are mandatory **workflow inputs for every product**, even when the API schema accepts an omitted price or initializes it to zero. Evaluate the cases below in order. When a case says **RETURN**, end the turn immediately: do not call a create endpoint, do not continue to examples, and do not create first and ask afterward.
+
+1. **No product identified:** Respond only: “What product would you like to create? You can upload up to 3 images and I’ll generate the product information from them, or describe the product in text.” **RETURN.** Do not replace the two paths with a form, checklist, questionnaire, text-only prompt, or requests for name, price, type, options, SEO, or inventory.
+2. **Any product lacks an explicit name or price:** Ask for all missing mandatory values in one question and offer to suggest them. When only price is missing, respond only: “What price should I set for [product name]? I can suggest one if you’d like.” **RETURN.**
+3. **Every name and price is known:** Creation may continue. Options, variations, description, SEO, info sections, type, SKU, inventory, and images are optional. Use them when supplied or requested; do not ask the user to resolve them before creation.
+
+“Create it,” “create it now,” “for my store, create,” or similar mutation language does not satisfy a missing price. A usable price must be either explicitly supplied by the user or a suggestion the user accepted. Treat `0` as supplied only when the user explicitly requests a free or zero-priced product.
+
+Before every create call, assert both conditions:
+
+- Every product has a non-empty name from the user or an accepted suggestion.
+- Every variant has a price from the user or an accepted suggestion; no price came from an API default, placeholder, example, or assumption.
+
+If any product is missing a price, **do not call the API**. Ask for the missing price, using the product's supplied name when available, and offer to suggest one. Never put `"amount": "0"` in the request unless the user explicitly chose a zero price.
+
+## Core flow
+
+1. Apply the preflight. When it says **RETURN**, make no API call in that turn.
+2. Send site-scoped calls with `Authorization`, `wix-site-id`, and `Content-Type: application/json`.
+3. If the catalog version is unknown, run:
+
+   ```bash
+   curl --request GET \
+     --url 'https://www.wixapis.com/stores/v3/provision/version' \
+     --header 'Authorization: <AUTH>' \
+     --header 'wix-site-id: <SITE_ID>' \
+     --header 'Content-Type: application/json'
+   ```
+
+   Continue here only for `V3_CATALOG`; use the V1 recipe for `V1_CATALOG`.
+4. Resolve each product's supplied type, variants, SKUs, inventory intent, and images after its mandatory name and variant price are known. Do not invent optional attributes the user did not supply or request.
+5. Choose the endpoint, build the products, upload any images, create, and validate every result. Continue until all requested products succeed or report the exact failed items.
+
+## Choose the endpoint
+
+| Request | No inventory | Quantity or in-stock state |
+|---|---|---|
+| One product | `POST /stores/v3/products` | `POST /stores/v3/products-with-inventory` |
+| Multiple products | `POST /stores/v3/bulk/products/create` | `POST /stores/v3/bulk/products-with-inventory/create` |
+
+- Bulk endpoints accept 1–100 products, so a compatible bulk endpoint is also valid for one product.
+- For multiple products requested as one batch, send one bulk call. Use the with-inventory endpoint when any product needs inventory; include `inventoryItem` only on tracked variants.
+- Never send `inventoryItem` to a no-inventory endpoint. Do not invent inventory.
+- Digital products normally use a no-inventory endpoint.
+- Per bulk request, allow at most 100 products, 100 total options, 100 modifiers, 100 info sections, and 1000 variants. Split larger input into compliant batches.
+
+## Build each product
+
+| Concern | Rule |
+|---|---|
+| Type | `PHYSICAL` uses product- and variant-level `physicalProperties`; `DIGITAL` omits physical properties and inventory. |
+| Variants | Include at least one. Price, SKU, barcode, inventory, and digital file are variant-level fields. |
+| Price | Use a string in `price.actualPrice.amount`; add `compareAtPrice` only when supplied. |
+| SKU | Preserve supplied strings exactly, including `#`, punctuation, and leading zeroes. Keep variant SKUs unique unless explicitly requested otherwise. |
+| Options | Define non-empty choices and create every requested Cartesian combination. Each variant references one choice from every option through `optionChoiceNames`. |
+| Text | Prefer `plainDescription` for unformatted copy. Use `description` only for a valid Ricos document. |
+| Media | Up to 3 images are supported per product. Preserve their supplied order in `media.itemsInfo.items`; `media.main` is read-only. |
+
+This inventory-aware physical product is the reusable shape. Remove `inventoryItem` when using a no-inventory endpoint; remove `media` when no image was supplied.
+
+```json
+{
+  "name": "Canvas Tee",
+  "productType": "PHYSICAL",
+  "physicalProperties": {},
+  "media": {"itemsInfo": {"items": [{
+    "url": "https://static.wixstatic.com/media/example.jpg",
+    "altText": "Canvas Tee"
+  }]}},
+  "options": [{
+    "name": "Size",
+    "optionRenderType": "TEXT_CHOICES",
+    "choicesSettings": {"choices": [
+      {"choiceType": "CHOICE_TEXT", "name": "Small"},
+      {"choiceType": "CHOICE_TEXT", "name": "Large"}
+    ]}
+  }],
+  "variantsInfo": {"variants": [
+    {
+      "choices": [{"optionChoiceNames": {
+        "optionName": "Size", "choiceName": "Small", "renderType": "TEXT_CHOICES"
+      }}],
+      "sku": "TEE-001-S",
+      "price": {
+        "actualPrice": {"amount": "18.50"},
+        "compareAtPrice": {"amount": "22.00"}
+      },
+      "inventoryItem": {"quantity": 13},
+      "physicalProperties": {},
+      "visible": true
+    },
+    {
+      "choices": [{"optionChoiceNames": {
+        "optionName": "Size", "choiceName": "Large", "renderType": "TEXT_CHOICES"
+      }}],
+      "sku": "TEE-001-L",
+      "price": {"actualPrice": {"amount": "18.50"}},
+      "inventoryItem": {"inStock": true},
+      "physicalProperties": {},
+      "visible": true
+    }
+  ]}
+}
+```
+
+For a color option, use `SWATCH_CHOICES`; each choice uses `choiceType: ONE_COLOR` and `colorCode`, and the variant reference uses `renderType: SWATCH_CHOICES`.
+
+A digital product uses the smaller shape below. Add the supplied variant-level digital file only when one was provided.
+
+```json
+{
+  "name": "Focus Planner PDF",
+  "productType": "DIGITAL",
+  "variantsInfo": {"variants": [{
+    "sku": "PDF-FOCUS-01",
+    "price": {"actualPrice": {"amount": "9.99"}},
+    "visible": true
+  }]}
+}
+```
+
+### Generated descriptions and SEO
+
+- When copy is generated from an image, every factual claim must be user-supplied or directly visible. Preserve user-supplied facts such as a stated material; do not reject them merely because the image alone cannot prove them. Color, shape, and visible decoration may come from the image. Dimensions, capacity, care instructions, durability, compatibility, performance, and any material the user did not identify must be omitted. For example, never write “dishwasher safe” or “microwave safe” unless the user supplied that fact. Omit uncertain claims instead of turning them into marketing language.
+- Use `plainDescription` unless formatting is required. SEO tags use `seoData.tags`.
+- For formatted bullets, the Ricos node is `BULLETED_LIST`, not `BULLET_LIST`, and its data field is `bulletedListData`:
+
+```json
+{
+  "description": {"nodes": [{
+    "type": "BULLETED_LIST",
+    "nodes": [{"type": "LIST_ITEM", "nodes": [{
+      "type": "PARAGRAPH",
+      "nodes": [{"type": "TEXT", "textData": {"text": "Visible blue glaze"}}],
+      "paragraphData": {}
+    }]}],
+    "bulletedListData": {}
+  }]}
+}
+```
+
+## Add images
+
+Skip this step when no image was supplied. Prefer the available dedicated Wix image-upload capability and upload all attachments and public image URLs together. Do not reconstruct that capability inside a general API-execution call. When no dedicated uploader is available, use `POST /site-media/v1/files/import` with the external URL in the body field named exactly `url`—not `importUrl`:
+
+```json
+{"url":"https://example.com/product.jpg","mimeType":"image/jpeg","displayName":"Product.jpg","mediaType":"IMAGE"}
+```
+
+A successful upload that returns the matching `wixstatic.com` URL may be used in product media while asynchronous processing is `PENDING`; do not treat `PENDING` alone as a failure. Stop if the upload reports `FAILED`. Poll `GET /site-media/v1/files/get-file-by-id?fileId=<FILE_ID>` until `file.operationStatus` is `READY` only when the workflow needs guaranteed processing, image metadata, transformations, or independent proof that the asset is ready. A pending URL proves submission, not completed processing, so do not describe it as ready or fully verified unless a later response proves that. Do not use a thumbnail URL or reuse the original external URL after upload.
+
+Track every upload as its own product-to-file record. A poll or timeout fallback may return only that file's URL—never another product's URL. If an upload fails, retry the same asset through another supported transfer method when possible; never silently replace it with a different image. If the exact asset cannot be preserved, create only products whose requested images uploaded successfully and report every blocked product and failed source exactly; for a single required-image product, make no product-create call.
+
+## Wrap the request
+
+Use the chosen product object directly in either envelope:
+
+```json
+{"product": PRODUCT}
+```
+
+```json
+{"products": [PRODUCT_1, PRODUCT_2], "returnEntity": true}
+```
+
+The first is for single endpoints; the second is for bulk endpoints. If the user supplies only a SKU pattern for variants, generate a stable unique SKU per combination and preserve the mapping in the result.
+
+For one product when the user supplied no quantity, stock state, or inventory-tracking request, the complete direct path is `POST /stores/v3/products` with `{"product": PRODUCT}`. Do not infer `inStock: true`, add `inventoryItem`, or choose `/products-with-inventory`; physical product type does not imply inventory. If it has ready images, add `"fields": ["MEDIA_ITEMS_INFO"]` to the same no-inventory request.
+
+For one physical product with inventory, the complete direct path is one `POST /stores/v3/products-with-inventory` call with `{"product": PRODUCT}`. Put `inventoryItem` on its priced variant. If it has ready images, add `"fields": ["MEDIA_ITEMS_INFO"]` to that same request. The product shape, envelope, endpoint, and validation paths are complete here: do not search another recipe or schema, probe an alternate endpoint, or make a post-create read unless the projected create response does not prove requested media.
+
+### Request projected media when validating images
+
+`media.itemsInfo.items` is a projected response field. Creating a product with media does not guarantee that the create response—or an ordinary Get Product call—returns the gallery. To receive it, pass `"MEDIA_ITEMS_INFO"` in the request-level `fields` array.
+
+For a single create with images:
+
+```json
+{"product": PRODUCT_WITH_MEDIA, "fields": ["MEDIA_ITEMS_INFO"]}
+```
+
+For a bulk create with images:
+
+```json
+{
+  "products": [PRODUCT_1, PRODUCT_2],
+  "returnEntity": true,
+  "fields": ["MEDIA_ITEMS_INFO"]
+}
+```
+
+If the create result still does not prove the stored gallery, make at most one read-only verification call:
+
+```http
+GET /stores/v3/products/<PRODUCT_ID>?fields=MEDIA_ITEMS_INFO
+```
+
+Inspect `product.media.itemsInfo.items` from that projected response. Do not interpret an omitted `itemsInfo` as lost media, search the Update Product schema, or PATCH the same media merely to retrieve it. A PATCH is appropriate only when a projected response proves the stored media is actually wrong.
+
+## Validate before reporting success
+
+| Endpoint result | Required checks |
+|---|---|
+| Single, no inventory | Require `product.id`; report only response-backed fields as verified. For images, request `MEDIA_ITEMS_INFO` on create or use one projected Get Product verification call. |
+| Single, with inventory | Require `product.id`; inspect `inventoryResults.results`, item metadata, and top-level error. |
+| Bulk, no inventory | Inspect every `results[].itemMetadata`; with `returnEntity: true`, the created entity is `results[].item`, not `results[].product`. Reconcile `bulkActionMetadata.totalSuccesses` and `totalFailures` with the requested count. |
+| Bulk, with inventory | Use the exact two-sibling response paths below. Inspect every product and inventory result, both bulk metadata objects, item metadata, and the inventory error before reporting success. |
+
+`POST /stores/v3/bulk/products-with-inventory/create` does **not** return the same flat envelope as `/stores/v3/bulk/products/create`. Its response has two top-level sibling objects:
+
+```json
+{
+  "productResults": {
+    "results": [{"itemMetadata": {}, "item": {}}],
+    "bulkActionMetadata": {}
+  },
+  "inventoryResults": {
+    "results": [{"itemMetadata": {}, "item": {}}],
+    "bulkActionMetadata": {},
+    "error": null
+  }
+}
+```
+
+Before claiming that an inventory-aware bulk create succeeded:
+
+1. Inspect every `productResults.results[]` entry and require `itemMetadata.success`; with `returnEntity: true`, read the product from `item`.
+2. Reconcile `productResults.bulkActionMetadata.totalSuccesses`, `totalFailures`, and `undetailedFailures` with the requested product count.
+3. Separately inspect every top-level `inventoryResults.results[]` entry and require `itemMetadata.success`; with `returnEntity: true`, read the inventory entity from `item`.
+4. Reconcile `inventoryResults.bulkActionMetadata.totalSuccesses`, `totalFailures`, and `undetailedFailures` with the expected inventory-item count, and inspect `inventoryResults.error`.
+
+The inventory error check is mandatory even when every item and metadata count succeeded. Explicitly read the sibling field—for example, normalize `inventoryResults.error ?? null`—and report success only when it is absent or null. Do not infer that value from HTTP 200, item metadata, or bulk metadata.
+
+For `POST /stores/v3/products-with-inventory`, inspect the returned `product.id`, every `inventoryResults.results[].itemMetadata`, and top-level `inventoryResults.error` directly from the create response. Do not issue inventory queries, product searches, Get Product calls, or PATCH calls merely to reconfirm values already proven by that response. If item success proves the inventory write but the response omits the requested quantity, report the quantity as submitted; if the user needs it independently verified, make one targeted inventory read using the returned product ID without first fetching the product again. The only other allowed extra read is the single projected media verification described above when requested images are not present in the projected create result. GET and HEAD requests must not include a request body.
+
+Never read `productResults.inventoryResults`: that path does not exist. A successful product result or HTTP 200 does not prove inventory creation succeeded.
+
+Retry only failed transient items, not successful products. If a requested field is absent from the response, call it submitted rather than API-verified; never echo the request as proof that it was stored.
+
+`product.visible: true` proves catalog visibility, not that an unpublished site is live. Say “created” or “visible in the catalog”; say “live” only when site publication is independently confirmed.
+
+## Failure guide
+
+- Inventory missing: use the with-inventory endpoint and include `inventoryItem` on each tracked variant.
+- Multiple requested products sent separately: use one compatible bulk call unless they cannot form a compliant batch or specific failed items are being retried.
+- `variantsInfo must not be empty`: include at least one priced variant per product.
+- Option/variant mismatch: create every requested combination and reference every option once per variant.
+- Media not visible: use the uploaded `wixstatic.com` URL in `media.itemsInfo.items`; do not set `media.main`.
+- Digital product rejected: omit physical properties and inventory; keep price, SKU, and any supplied digital file on the variant.

package/skills/wix-vibe-headless/install/deploy.cjs

@@ -144,8 +144,7 @@ const finalClientId = onDisk.clientId || clientId;
 const finalMetaSiteId = onDisk.metaSiteId || metaSiteId;
 
 if (!finalClientId || !finalMetaSiteId) {
-  deployed.wixConfig = 'missing_ids — src/rest/wix-config.js is not configured; re-run with '
-    + '--client-id and --metasite-id rather than editing the file by hand';
+  deployed.wixConfig = 'skipped — no ids provided';
 } else if (finalClientId === onDisk.clientId && finalMetaSiteId === onDisk.metaSiteId) {
   deployed.wixConfig = 'already_set';
 } else {

package/skills/wix-vibe-headless/platforms/base44-ecom-light-seed.md

@@ -0,0 +1,104 @@
+# Wix Managed Headless — Base44 storefront client + seed
+
+You are building a **Wix Managed** headless storefront inside Base44 — the business is described in your
+initial prompt, and the Wix connector is already configured.
+
+Your Wix client id is in your prompt — a public, buyer-facing credential (anonymous visitor tokens
+only), safe in the frontend; use it directly for the Wix client setup.
+
+> **`wix-vibe-headless` and `wix-docs` are the complete build and seed path for this app.** **Do NOT use the Base44 commerce kit (or any Base44 solution kit).**
+
+Follow STEPs 1–4 below exactly (run STEP 3 in parallel with STEP 2).
+
+## STEP 1 — Install the Wix skills and deploy the storefront vertical to the app
+
+Install two skills — they land under `.agents/skills/`:
+- **`wix-vibe-headless`** — the storefront build + seed guide (STEPs 2–3): your main source of truth.
+- **`wix-docs`** — a **fallback**: search + read the Wix API docs for anything `wix-vibe-headless`
+  doesn't cover.
+
+Run this through exec_tool, exactly as written — installs both skills, deploys the `storefront` REST scaffolds + UI into `src/`, and pins the AGENTS.md note.
+
+```js
+const { execSync } = require('child_process');
+const { existsSync, readdirSync } = require('fs');
+const results = {};
+for (const skill of ['wix-vibe-headless', 'wix-docs']) {
+  if (existsSync(`/app/.agents/skills/${skill}/SKILL.md`)) { results[skill] = 'already_installed'; continue; }
+  try {
+    const out = execSync(`CI=1 npx -y skills add wix/skills/skills/${skill} --yes 2>&1`,
+      { cwd: '/app', timeout: 60000, shell: '/bin/bash' }).toString().replace(/\x1b\[[0-9;]*m/g, '');
+    results[skill] = /installed 1 skill|found 1 skill/i.test(out) ? 'success'
+      : out.includes('No valid skills') ? 'not_found' : 'unknown';
+  } catch (e) { results[skill] = 'error: ' + e.message; }
+}
+const deploy = execSync(`node /app/.agents/skills/wix-vibe-headless/install/deploy.cjs storefront`, { cwd: '/app' }).toString();
+const agentsMd = execSync(`node /app/.agents/skills/wix-vibe-headless/install/pin-agents-md.cjs`, { cwd: '/app' }).toString();
+return { results, installed: readdirSync('/app/.agents/skills'), deploy: JSON.parse(deploy), agentsMd: JSON.parse(agentsMd) };
+```
+
+Read skills with **`read_file`** using workspace-relative paths (e.g. `.agents/skills/wix-vibe-headless/SKILL.md`) — absolute `/app/...` fails. Always read from `.agents/skills/` exactly on every turn; ignore stray copies like `agent/skills/`.
+
+## STEP 2 — Build the client
+
+Read `.agents/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md` and follow it **EXACTLY** — the single source of truth for how the storefront client is built.
+
+**REST scaffolds are already in `src/rest/`** (STEP 1 deployed them). The storefront also ships a ready UI client in `src/` — theme + wire it per `INSTRUCTIONS.md`, don't rebuild. **Don't `read_file` deployed files** — every field shape is in `INSTRUCTIONS.md`; read one only on a real error or gap.
+
+**`src/App.jsx`: edit surgically, never rewrite.** It carries required platform auth scaffolding
+(`AuthProvider`/`useAuth` from `@/lib/AuthContext`); a full rewrite drops them → the validator
+rejects the write. Wire routes/imports in with `find_replace`, leave the rest as-is.
+
+## STEP 3 — Seed the storefront
+
+**Never delete or clean up anything on the user's site — seeding is additive only.** It's a live
+user-owned business, so never delete or overwrite existing content, even apparent sample data. If a
+cleanup truly seems needed, ask the user first.
+
+Seed by calling the storefront's ready-made seed module — read
+`.agents/skills/wix-vibe-headless/references/storefront/seed/SEED.md` and load its `seed-*.js` via
+its loader snippet (build-time exec_tool); call its functions with your data. Gaps or an unexpected
+shape → the **`wix-docs`** skill.
+
+**Auth for these admin calls is the already-configured Wix headless connector — nothing else.** Get its
+access token and send it as a bearer token:
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+// then: fetch(url, { headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" }, ... })
+```
+
+Inline via exec_tool, `base44` is already declared — use it directly; do **not** import
+`@base44/sdk`, re-declare it, or call `createClient()` (that's for standalone `.js` files only;
+inline it throws *"Identifier 'base44' has already been declared."*).
+
+**Product images.** Generate with **Base44's built-in image generation**, then attach via the
+storefront seed module's image-attach step — `wix-docs` if the module doesn't cover it.
+
+**Seed images with the FINAL url, in one call.** Use the real `https://media.base44.com/...` url
+from the **completed** `generate_image` result and pass it straight into your single `setupStore`
+call (images included). A still-generating `/__generating__/<id>.png` placeholder is not a real url
+— Wix can't fetch it. `generate_image` runs in the background while you build the client, so the
+urls are ready by the time you seed.
+
+## STEP 4 — Wrap up
+
+**Do NOT add the `<WixManageBanner/>` component** and do not send the user Wix dashboard links — this flow does not include the manage banner or back-office handoff.
+
+**Preview briefly, don't chase images.** Broken images are expected — `generate_image` returns a `/__generating__/…` placeholder that the platform swaps for the final url automatically at turn end (failures get a stock fallback). **Do NOT edit or debug image urls.** Leave them and finish.
+
+## Later admin requests
+
+When the user asks for follow-up changes (next iterations), use the already-connected Wix headless connector — get an access token and call the Wix API directly:
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+const res = await fetch("https://www.wixapis.com/<api-path>", {
+  method: "POST",
+  headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ /* request body */ }),
+});
+return await res.json();
+```
+
+`base44` is already declared inline in exec_tool — use it directly; do **not** import `@base44/sdk` or call `createClient()`. For what to call, check the storefront seed module (`.agents/skills/wix-vibe-headless/references/storefront/seed/SEED.md`) or look up the endpoint via `wix-docs`.

package/skills/wix-vibe-headless/platforms/base44-ecom-light.md

@@ -0,0 +1,74 @@
+# Wix Managed Headless — Base44 storefront client
+
+You are building a **Wix Managed** headless storefront inside Base44 — the business is described in your
+initial prompt, and the Wix connector is already configured.
+
+Your Wix client id is in your prompt — a public, buyer-facing credential (anonymous visitor tokens
+only), safe in the frontend; use it directly for the Wix client setup.
+
+> **`wix-vibe-headless` and `wix-docs` are the complete build path for this app.** **Do NOT use the Base44 commerce kit (or any Base44 solution kit).** **This flow builds the client only — there is no seeding step.**
+
+Follow STEPs 1–3 below exactly.
+
+## STEP 1 — Install the Wix skills and deploy the storefront vertical to the app
+
+Install two skills — they land under `.agents/skills/`:
+- **`wix-vibe-headless`** — the storefront build guide (STEP 2): your main source of truth.
+- **`wix-docs`** — a **fallback**: search + read the Wix API docs for anything `wix-vibe-headless`
+  doesn't cover.
+
+Run this through exec_tool, exactly as written — installs both skills, deploys the `storefront` REST scaffolds + UI into `src/`, and pins the AGENTS.md note.
+
+```js
+const { execSync } = require('child_process');
+const { existsSync, readdirSync } = require('fs');
+const results = {};
+for (const skill of ['wix-vibe-headless', 'wix-docs']) {
+  if (existsSync(`/app/.agents/skills/${skill}/SKILL.md`)) { results[skill] = 'already_installed'; continue; }
+  try {
+    const out = execSync(`CI=1 npx -y skills add wix/skills/skills/${skill} --yes 2>&1`,
+      { cwd: '/app', timeout: 60000, shell: '/bin/bash' }).toString().replace(/\x1b\[[0-9;]*m/g, '');
+    results[skill] = /installed 1 skill|found 1 skill/i.test(out) ? 'success'
+      : out.includes('No valid skills') ? 'not_found' : 'unknown';
+  } catch (e) { results[skill] = 'error: ' + e.message; }
+}
+const deploy = execSync(`node /app/.agents/skills/wix-vibe-headless/install/deploy.cjs storefront`, { cwd: '/app' }).toString();
+const agentsMd = execSync(`node /app/.agents/skills/wix-vibe-headless/install/pin-agents-md.cjs`, { cwd: '/app' }).toString();
+return { results, installed: readdirSync('/app/.agents/skills'), deploy: JSON.parse(deploy), agentsMd: JSON.parse(agentsMd) };
+```
+
+Read skills with **`read_file`** using workspace-relative paths (e.g. `.agents/skills/wix-vibe-headless/SKILL.md`) — absolute `/app/...` fails. Always read from `.agents/skills/` exactly on every turn; ignore stray copies like `agent/skills/`.
+
+## STEP 2 — Build the client
+
+Read `.agents/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md` and follow it **EXACTLY** — the single source of truth for how the storefront client is built.
+
+**REST scaffolds are already in `src/rest/`** (STEP 1 deployed them). The storefront also ships a ready UI client in `src/` — theme + wire it per `INSTRUCTIONS.md`, don't rebuild. **Don't `read_file` deployed files** — every field shape is in `INSTRUCTIONS.md`; read one only on a real error or gap.
+
+**`src/App.jsx`: edit surgically, never rewrite.** It carries required platform auth scaffolding
+(`AuthProvider`/`useAuth` from `@/lib/AuthContext`); a full rewrite drops them → the validator
+rejects the write. Wire routes/imports in with `find_replace`, leave the rest as-is.
+
+## STEP 3 — Wrap up
+
+**No seeding in this flow** — the client is the only deliverable. Do not seed, populate, or write data to Wix.
+
+**Do NOT add the `<WixManageBanner/>` component** and do not send the user Wix dashboard links — this flow does not include the manage banner or back-office handoff.
+
+**Preview briefly, don't chase images.** Broken images are expected — `generate_image` returns a `/__generating__/…` placeholder that the platform swaps for the final url automatically at turn end (failures get a stock fallback). **Do NOT edit or debug image urls.** Leave them and finish.
+
+## Later admin requests
+
+When the user asks for follow-up changes (next iterations), use the already-connected Wix headless connector — get an access token and call the Wix API directly:
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+const res = await fetch("https://www.wixapis.com/<api-path>", {
+  method: "POST",
+  headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ /* request body */ }),
+});
+return await res.json();
+```
+
+`base44` is already declared inline in exec_tool — use it directly; do **not** import `@base44/sdk` or call `createClient()`. For what to call, check the storefront seed module (`.agents/skills/wix-vibe-headless/references/storefront/seed/SEED.md`) or look up the endpoint via `wix-docs`.

package/skills/wix-vibe-headless/platforms/base44.md

@@ -106,9 +106,7 @@ its loader snippet (build-time exec_tool); call its functions with your data. Ga
 shape → the **`wix-docs`** skill.
 
 **Auth for these admin calls is the already-configured Wix connector — nothing else.** Get its
-access token and send it as a bearer token; do **not** hand-roll a token getter (e.g.
-`getAdminToken()`), install/run the Wix CLI (`@wix/cli`), or device-login (no managed-project auth
-flow applies to Base44):
+access token and send it as a bearer token:
 
 ```js
 const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
@@ -150,3 +148,5 @@ Once the site is built and seeded:
 
 For any later admin/management request, work as in STEP 4: your vertical's seed module first, else
 `wix-docs` — all over the connector.
+
+version: v1338

package/skills/wix-vibe-headless/references/blog/seed/SEED.md

@@ -14,7 +14,7 @@ for you (Blog binds the cover by the Wix Media file id, not a url).
 
 ```js
 // build-time exec_tool
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const fs = require("fs");
 // exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
 const seed = (() => { const m = { exports: {} };

package/skills/wix-vibe-headless/references/bookings/seed/SEED.md

@@ -8,7 +8,7 @@ Bookings seed operation. Load it and call **`setupBookings` — the one-call pat
 
 ```js
 // build-time exec_tool
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const fs = require("fs");
 // exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
 const seed = (() => { const m = { exports: {} };

package/skills/wix-vibe-headless/references/events/seed/SEED.md

@@ -13,7 +13,7 @@ after create, and **publishing is one-way**. So per event: create DRAFT → (tic
 
 ```js
 // build-time exec_tool
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const fs = require("fs");
 // exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
 const seed = (() => { const m = { exports: {} };

package/skills/wix-vibe-headless/references/portfolio/seed/SEED.md

@@ -16,7 +16,7 @@ first, then thread their real ids into each project.
 
 ```js
 // build-time exec_tool
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const fs = require("fs");
 // exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
 const seed = (() => { const m = { exports: {} };

package/skills/wix-vibe-headless/references/pricing-plans/seed/SEED.md

@@ -9,7 +9,7 @@ plain data.
 
 ```js
 // build-time exec_tool
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const fs = require("fs");
 // exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
 const seed = (() => { const m = { exports: {} };

package/skills/wix-vibe-headless/references/restaurants/seed/SEED.md

@@ -17,7 +17,7 @@ across exec calls. Online ordering and table reservations run only when the plan
 
 ```js
 // build-time exec_tool
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const fs = require("fs");
 // exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
 const seed = (() => { const m = { exports: {} };

package/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md

@@ -24,12 +24,15 @@ so you don't need to open them:**
 | `context/CartContext.jsx` | `useCart()` provider: server cart, add/update/remove, checkout |
 | `hooks/useProductDetail.js` | PDP data — product + variant resolution for a slug, plus load/add state |
 | `hooks/useShop.js` | catalog listing — category menu, cursor paging, sort, failure state |
-| `components/ProductCard.jsx`, `ProductGrid.jsx` | product listing UI (grid + card, skeletons, empty state). The tile carries quick add for single-variant products, colour dots + an option summary, and pre-order / sold-out / limited-stock / percent-off / merchant-ribbon badges — all from the list query, no extra request |
+| `hooks/useProductCard.js` | headless data layer for a grid tile — returns `leftBadges`, `promoBadge`, `priceDisplay`, `compareAtDisplay`, `colors`, `optionLabel`, `isQuickAddable`, `image`, `hoverImage`; **always use this to build your own product card UI on the grid** |
+| `components/ProductCard.jsx` | reference implementation of a grid tile built on `useProductCard` — read it for inspiration, build your own component rather than using it directly |
+| `components/ProductGrid.jsx` | reference grid layout (2-col mobile → auto-fill desktop) with skeleton + empty state — read it for the skeleton/empty-state patterns, build your own layout rather than using it directly |
 | `components/ProductGallery.jsx` | PDP main image + thumbnails |
 | `lib/storeImage.js` | `productImage()` / `productGallery()` / `storeImage()` — normalise Wix image urls |
 | `components/CartButton.jsx` | header cart **icon** button with a live-count badge |
 | `components/CartDrawer.jsx` | slide-over cart (mount once; opens from `useCart`) |
-| `components/VariantPicker.jsx` | option/variant selector used on the PDP — colour options render as real swatches, and picking one moves the gallery to that colour's photo |
+| `hooks/useVariantOptions.js` | headless data layer for options/modifiers — returns `optionGroups` + `modifierGroups` (normalised, render-agnostic); **always use this to build your own variant UI on the PDP** |
+| `components/VariantPicker.jsx` | reference implementation of a variant selector built on `useVariantOptions` (pills + colour swatches) — read it for inspiration, but build your own component rather than using it directly |
 | `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 3) |
 | `pages/Shop.jsx`, `pages/ProductDetail.jsx` | the two shipped routes (`/shop`, `/product/:slug`) |
 | `rest/wix-config.js` | the two ids, written by the install step |
@@ -70,6 +73,69 @@ replace it.
   banner is dismissed.
 - Routes under the Layout: `/shop` → `Shop`, `/product/:slug` → `ProductDetail` (both shipped, as-is).
   **You add `/` → your own Home** page.
+- **Build your own variant selector on the PDP — this is required, not optional, and it's your chance to be creative.** `ProductDetail.jsx` ships with a `VariantPicker` import — remove it and replace with your own component built on `useVariantOptions`. Design the controls to fit the brief: the business type, the tone, the audience. A fashion brand might want large colour swatches and a size chart link; a tech store might want a compact dropdown. `VariantPicker.jsx` is in `src/` for reference — read it, don't use it:
+- **Build your own product card for the grid — this is required, not optional, and it's your chance to be creative.** `ProductGrid.jsx` ships with a `ProductCard` import — replace it with your own component built on `useProductCard`. The hook hands you everything the tile needs (badges, price display, colour dots, quick-add flag, images) — you decide the layout, shape, hover behaviour, and CTA style. A lifestyle brand might want full-bleed images with an overlay gradient; a tech store might want a compact horizontal list item. `ProductCard.jsx` is in `src/` for reference — read it, don't use it:
+- **Build your own grid layout — this is required, not optional, and it's your chance to be creative.** `ProductGrid.jsx` ships as a reference (2-col mobile → auto-fill desktop, 220px min) — replace it with an arrangement that fits the brief. A curated boutique might want a 3-col asymmetric editorial layout; a high-volume store might want a dense 4-col grid; a featured strip on the home page might want horizontal scroll. Keep the skeleton and empty-state patterns from `ProductGrid.jsx` (copy them into your own component) — the states themselves are correct, just the layout is yours to choose.
+
+```jsx
+import { Link } from "react-router-dom";
+import { useCart } from "@/context/CartContext";
+import { useProductCard } from "@/hooks/useProductCard";
+
+export default function MyProductCard({ product }) {
+  const { addToCart } = useCart();
+  const {
+    isSoldOut, isPreorder,
+    leftBadges,       // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }] — render left side of image
+    promoBadge,       // { type: 'discount'|'ribbon', label } | null — render right side
+    priceDisplay,     // "€10" or "€10 – €20" (range when variants differ)
+    compareAtDisplay, // original price string | null
+    colors,           // hex strings → render as dots (slice to how many you want)
+    optionLabel,      // "3 sizes · 2 materials" or empty string
+    isQuickAddable,   // true for single-variant, in-stock products
+    image,            // primary image URL | null
+    hoverImage,       // second image URL | null
+  } = useProductCard(product);
+
+  // Then render however you want:
+  return (
+    <div>
+      {/* image, badges, price, colour dots, quick-add or "Choose options" CTA */}
+      {isQuickAddable && <button onClick={() => addToCart(product.id)}>Quick add</button>}
+      {!isQuickAddable && !isSoldOut && <Link to={`/product/${product.slug}`}>Choose options</Link>}
+      {isSoldOut && isPreorder && <Link to={`/product/${product.slug}`}>Pre-order</Link>}
+    </div>
+  );
+}
+```
+
+```jsx
+import { useVariantOptions } from "@/hooks/useVariantOptions";
+
+// options/modifiers/selectedOptions/modifierValues come from useProductDetail:
+const { optionGroups, modifierGroups } = useVariantOptions(options, modifiers, selectedOptions, modifierValues);
+
+// optionGroups: [{ id, name, isColor, choices: [{ choiceId, name, colorCode, isColorSwatch, inStock, selected }] }]
+// modifierGroups: [{ key, name, mandatory, type: 'choices'|'text', choices?: [{ key, name, selected }], value?: string }]
+
+// Then render however you want:
+optionGroups.map((group) =>
+  group.choices.map((c) =>
+    c.isColorSwatch
+      ? <MySwatch key={c.choiceId} color={c.colorCode} active={c.selected} disabled={!c.inStock}
+                  onClick={() => selectOption(group.id, c.choiceId)} />
+      : <MyPill  key={c.choiceId} active={c.selected} disabled={!c.inStock}
+                  onClick={() => selectOption(group.id, c.choiceId)}>{c.name}</MyPill>
+  )
+);
+modifierGroups.map((m) =>
+  m.type === "text"
+    ? <MyInput key={m.key} label={m.name} value={m.value} onChange={(v) => setModifier(m.key, v)} />
+    : m.choices.map((c) =>
+        <MyPill key={c.key} active={c.selected} onClick={() => setModifier(m.key, c.key)}>{c.name}</MyPill>
+      )
+);
+```
 
 ```jsx
 import { useRef, useState, useEffect } from "react";