@wix/agent-skills 1.16.1 → 1.16.2

package/skills/wix-manage/references/sites/read-site-context.md

@@ -0,0 +1,125 @@
+---
+name: "Read Account or Site Context"
+description: Probe a Wix site or account for full context in one call — installed apps by display name, locale, currency, timezone, and status. Account token + siteId targets one site; account token alone returns up to 10; site-scoped token alone returns the site it is scoped to.
+---
+# Read Account or Site Context
+
+Returns a site's name, URL, status, locale/region, and all installed apps with human-readable display names.
+
+---
+
+## Markdown endpoint (recommended)
+
+**Endpoint**: `POST https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown`
+
+Returns `{ "markdown": "..." }`.
+
+### Account token + siteId — one specific site
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{"siteId": "<metaSiteId>"}'
+```
+
+Response:
+
+```
+## 1. Acme Store
+
+**ID**: `<metaSiteId>`
+**URL**: [https://example.wixsite.com/acme](https://example.wixsite.com/acme)
+**Status**: Published
+**Editor Type**: Editorless
+**Created**: Aug 14, 2026, 05:21 · **Updated**: Aug 17, 2026, 20:44
+**Velo**: Enabled
+
+### Properties
+
+**Locale & Region**
+- Language: **en**
+- Country: **US**
+- Timezone: **America/New_York**
+- Currency: **USD**
+
+### Apps
+
+- **Wix Stores** (ID: `215238eb-22a5-4c36-9e7b-e7c08025e04e`) — Catalog app version: **V3**
+- **Wix Bookings** (ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`)
+- **Wix Blog** (ID: `14bcded7-0066-7c35-14d7-466cb3f09103`)
+```
+
+### Without siteId
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+- **Account token**: returns up to 10 sites. If the account has more: `_Showing 10 sites (more available)_` — call again with a specific `siteId`.
+- **Site-scoped token** (e.g. the Wix connector in Base44): returns the one site the token is scoped to.
+
+---
+
+## JSON endpoint
+
+**Endpoint**: `POST https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context`
+
+Same request shape. `installedApps` contains raw `appId` UUIDs — extract only what you need:
+
+```javascript
+const res = await fetch(
+  "https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context",
+  {
+    method: "POST",
+    headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ siteId: metaSiteId }),
+  }
+);
+const { sites } = await res.json();
+const site = sites[0];
+
+const KNOWN_APPS = {
+  stores:       "215238eb-22a5-4c36-9e7b-e7c08025e04e",
+  bookings:     "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
+  blog:         "14bcded7-0066-7c35-14d7-466cb3f09103",
+  events:       "140603ad-af8d-84a5-2c80-a0f60cb47351",
+  pricingPlans: "1522827f-c56c-a5c9-2ac9-00f9e6ae12d3",
+  restaurants:  "13e8d036-5516-6f75-e025-2aca3b5d7930",
+};
+
+const appById = Object.fromEntries(
+  (site.installedApps ?? []).map((a) => [a.appId, a])
+);
+
+const context = {
+  id:              site.id,
+  name:            site.displayName,
+  url:             site.url,
+  currency:        site.properties?.paymentCurrency,
+  locale:          `${site.properties?.locale?.languageCode}-${site.properties?.locale?.country}`,
+  timezone:        site.properties?.timeZone,
+  hasStores:       !!appById[KNOWN_APPS.stores],
+  storesCatalogV:  appById[KNOWN_APPS.stores]?.catalogVersion ?? null, // "V3" | "V1" | null
+  hasBookings:     !!appById[KNOWN_APPS.bookings],
+  hasBlog:         !!appById[KNOWN_APPS.blog],
+  hasEvents:       !!appById[KNOWN_APPS.events],
+  hasPricingPlans: !!appById[KNOWN_APPS.pricingPlans],
+  hasRestaurants:  !!appById[KNOWN_APPS.restaurants],
+};
+```
+
+---
+
+## API Reference
+
+- [Get Dynamic Context — markdown](https://dev.wix.com/docs/api-reference/tools/dynamic-site-context/get-dynamic-context-markdown)
+- [Get Dynamic Context — JSON](https://dev.wix.com/docs/api-reference/tools/dynamic-site-context/get-dynamic-context)
+- [Query Sites](https://dev.wix.com/docs/api-reference/account-level/sites/sites/query-sites) — for paginating or filtering the full site list
+- [Get Installed Apps](https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/get-installed-apps) — raw app instances with fields not in the context snapshot
+- [Get Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties) — full properties including business description, address, social links

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: {} };