@wix/agent-skills 1.18.2 → 1.19.1

package/skills/wix-manage/references/seo/manage-google-search-console.md

@@ -0,0 +1,272 @@
+---
+name: "Manage Google Search Console for a Wix Site"
+description: "Connect a Wix site to Google Search Console and drive its setup through the public GSC Connection and Site Readiness APIs: check connection and readiness, start the Google authorization, verify ownership, add the property, submit the sitemap, request indexing, read search performance, run URL inspection, recover a stale connection, or disconnect. The site owner authorizes in their own browser via a single-use connect URL."
+---
+
+# Manage Google Search Console for a Wix Site
+
+The **GSC Connection API** links a Google account to the site. The **GSC Site
+Readiness API** acts through that account: verifies ownership, adds the Search
+Console property, submits the sitemap, requests indexing, reads search performance
+and URL inspection. Both select the site from the caller's authorization context
+and take no site ID. Use the site already selected in the environment. If none is
+selected, list the available sites. Select the only site automatically; if several
+are available, ask the user to choose by name before making site-specific calls.
+Never invent a site ID or ask the user to type one.
+
+All endpoints are under `https://www.wixapis.com`: Connection calls under
+`/gsc/connection/v1`, everything else under `/gsc/v1`.
+
+## Start every task with two reads
+
+Both are side-effect free. Do them before describing the site's state.
+
+```
+GET https://www.wixapis.com/gsc/connection/v1/connection
+```
+
+```json
+{ "connection": { "status": "VALID", "connectedEmailMasking": "m*******@gmail.com", "ownedByCaller": true } }
+```
+
+```
+GET https://www.wixapis.com/gsc/v1/site-readiness
+```
+
+```json
+{ "siteReadiness": { "status": "NOT_READY", "blockingReason": "SITE_OWNER_NOT_VERIFIED" } }
+```
+
+Read them together:
+
+| `connection.status` | `siteReadiness` | Meaning | Next |
+|---|---|---|---|
+| `NOT_CONNECTED` | `NOT_READY` / `SITE_OWNER_NOT_VERIFIED` | No Google account linked | Connect (below) |
+| `PENDING` | any | An authorization attempt is open | Ask the user to finish it in their browser, do not start another |
+| `VALID` | `READY` | Connected and verified | Property steps if the user wants them |
+| `VALID` | `NOT_READY` / `SITE_OWNER_NOT_VERIFIED` | Connected, not verified | Verify Site |
+| `INVALID` | `NOT_READY` / `TOKEN_INVALID` | Credentials rejected by Google | Reconnect |
+| `VALID` | `NOT_READY` / `DOMAIN_MISSING` | No connected domain | User connects a domain first |
+
+`blockingReason` is `UNKNOWN_BLOCKING_REASON` when the status is `READY`; not an
+error. Treat an unrecognized reason as "not ready, no known next action".
+
+`READY` covers connection and verification only. Whether the property was added,
+the sitemap submitted, or indexing requested comes from **List Events**.
+
+## `VALID` can be stale, and `MISSING_TOKEN` means reconnect
+
+`INVALID` is only written when a real call to Google is rejected, so a site nobody
+has queried since its credentials broke keeps reporting `VALID`. The tell arrives
+on the first Google-facing call:
+
+```json
+{ "message": "FAILED_PRECONDITION: Missing Token", "details": { "applicationError": { "code": "MISSING_TOKEN" } } }
+```
+
+The reference describes `MISSING_TOKEN` as "no Google account is connected"; it
+also fires when the stored credentials are gone while Get Connection still said
+`VALID`. Either way: the Google account must be reconnected. Do not retry, and do
+not tell the user the site is connected.
+
+## Connect a Google account
+
+Get Connect URL is `GET`, but it **writes**: every call starts a new single-use
+authorization attempt (two-hour expiry) and Get Connection reports `PENDING` while
+it is open. Use Get Connection to check connection status. Call Get Connect URL
+when starting a connection or reconnection attempt; while the user completes that
+attempt, use Get Connection for status checks. Request a new URL when a new attempt
+is needed, such as after expiry. On an already-connected site it is allowed: the
+same Google account refreshes the credentials, a different one replaces the
+connection. Say which before you do it.
+
+1. Read Get Connection. If `VALID`, stop unless the user wants to reconnect.
+2. Call [Get Connect URL](https://dev.wix.com/docs/api-reference/business-management/seo/google-search-console/connection-v1/get-connect-url). The request takes no parameters or body.
+
+   ```
+   GET https://www.wixapis.com/gsc/connection/v1/connect-url
+   ```
+
+   ```json
+   { "connectUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=407408718192.apps.googleusercontent.com&redirect_uri=https%3A%2F%2Fwww.wixapis.com%2Fgsc%2Fconnection%2Fv1%2Fconnect-callback&response_type=code&scope=openid%20email%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fwebmasters&state=EXAMPLE_STATE" }
+   ```
+
+   The response above is illustrative. Wix generates the authorization URL,
+   including its OAuth query parameters. Give the user the exact returned
+   `connectUrl`; do not construct, modify, or reuse the example URL.
+
+3. Give the URL to the user and ask them to tell you when they have finished. Wix
+   completes the exchange server-side; there is no code to send back.
+4. When the user says they are done, read Get Connection once and confirm `VALID`.
+   Do not poll while waiting. If it is still `PENDING`, the user has not finished;
+   if the attempt expired (two hours), request a fresh URL only after they agree.
+
+## Writes need a published, indexable site with a connected domain
+
+Get Connect URL, Verify Site, Add Site, and Submit Sitemap fail with
+`FAILED_PRECONDITION` until the site is published, has a connected (premium)
+domain, and allows indexing. The code names the first failing check:
+
+```json
+{ "message": "FAILED_PRECONDITION: The site has no connected domain. Connect a domain before connecting the site to Google Search Console",
+  "details": { "applicationError": { "code": "DOMAIN_NOT_CONNECTED" } } }
+```
+
+Codes: `SITE_NOT_PUBLISHED`, `DOMAIN_NOT_CONNECTED`, `SITE_NOT_INDEXABLE`. A free
+site on a `wixsite.com` address cannot complete these writes. Report the missing
+prerequisite and stop. When listing sites to find one that qualifies, filter for
+premium sites with a connected domain.
+
+## Set the site up in Search Console
+
+Run the steps the user asked for, in this order, confirming before each write.
+Bodies are empty unless shown.
+
+| Step | Call | Notes |
+|---|---|---|
+| Verify ownership | `POST /gsc/v1/verify-site` with `{ "method": "META" }` | Synchronous against Google, allow up to 60 s. Idempotent. Wix already places the meta tag. |
+| Add the property | `POST /gsc/v1/add-site` | Requires a verified site. |
+| Submit the sitemap | `POST /gsc/v1/submit-sitemap` | Wix hosts and generates the sitemap. Google processes it asynchronously. |
+| Request indexing | `POST /gsc/v1/request-site-indexing` | Success means Google accepted the request, not that the site is indexed. |
+| Request one page | `POST /gsc/v1/request-page-indexing` with `{ "url": "https://www.example.com/about" }` | Full URL of a page on this site. |
+
+All succeed with `{}`. Re-read Get Site Readiness after each step and act on the
+current `blockingReason`. Verify Site on an already-verified site returns `{}` and
+re-stamps the `SITE_VERIFIED` event date: safe, but not a change to report.
+
+Two Google-side failures are retryable. `RESOURCE_EXHAUSTED` (`GOOGLE_QUOTA_EXCEEDED`):
+the quota is daily, tell the user to retry tomorrow. `UNAVAILABLE`
+(`GOOGLE_UNAVAILABLE`): retry once after a few seconds. On any other error your next
+message is the final response: name the step that failed and the error code, and
+make no further Search Console calls.
+
+## Check what was done: List Events and List Sitemaps
+
+```
+GET https://www.wixapis.com/gsc/v1/events
+```
+
+```json
+{ "events": [
+  { "eventType": "ACCOUNT_CONNECTED", "occurredDate": "2025-10-29T11:10:15.869Z" },
+  { "eventType": "SITE_VERIFIED", "occurredDate": "2026-09-07T11:39:31.992Z" },
+  { "eventType": "SITE_ADDED", "occurredDate": "2025-10-29T11:07:39.050Z" } ] }
+```
+
+One entry per event type with the date it **last** occurred, **not sorted by
+date**: never read the last entry as the latest event. Types: `ACCOUNT_CONNECTED`,
+`SITE_VERIFIED`, `SITE_ADDED`, `SITEMAP_SUBMITTED`, `SITE_INDEXING_REQUESTED`,
+`PAGE_INDEXING_REQUESTED`. A missing type means that step never happened.
+
+```
+GET https://www.wixapis.com/gsc/v1/sitemaps
+```
+
+```json
+{ "sitemaps": [ { "url": "https://www.example.com/blog-posts-sitemap.xml", "type": "sitemap", "pending": false,
+  "lastDownloadedDate": "2026-09-05T15:14:47.210Z", "errorCount": "0", "warningCount": "0",
+  "contents": [ { "type": "web", "submittedCount": "1", "indexedCount": "1" } ] } ] }
+```
+
+Wix submits several sitemaps, typically one per content type. `pending: true` with
+an empty `type` means Google has not processed it yet. Counts are strings.
+
+## Read search performance
+
+```
+GET https://www.wixapis.com/gsc/v1/search-analytics?startDate=2026-08-01&endDate=2026-08-31&dimensions=query&rowLimit=5
+```
+
+```json
+{ "results": [ { "keys": ["best of santorini"], "clicks": 0, "impressions": 3, "ctr": 0, "position": 36 } ] }
+```
+
+- `startDate` and `endDate` are required, `YYYY-MM-DD`, end inclusive.
+- `dimensions` repeats: `date`, `query`, `page`, `country`, `device`,
+  `searchAppearance`; omit for one aggregate row. `keys` follow your order.
+- `type`: `web` (default), `image`, `video`, `news`. Page with `rowLimit`/`startRow`.
+- It is Google's own report: the latest days are usually missing, and there is no
+  history from before the property was added. Empty `results` is a real answer.
+
+## Inspect pages
+
+Page IDs are Wix static-page IDs, not URLs. Discover them with
+[List Item SEO Tags](https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/list-item-seo-tags)
+for `STATIC_PAGE`. The request has no body:
+
+```
+GET https://www.wixapis.com/promote/seo/v1/item-seo-tags/STATIC_PAGE
+```
+
+Relevant response fields (unrelated SEO fields omitted; IDs are illustrative):
+
+```json
+{ "itemSeoTags": [ { "id": "STATIC_PAGE:c1dmp", "itemType": "STATIC_PAGE", "itemId": "c1dmp" } ],
+  "pagingMetadata": { "count": 1, "hasNext": false, "cursors": {} } }
+```
+
+If `pagingMetadata.hasNext` is `true`, pass `pagingMetadata.cursors.next` back as
+`paging.cursor` in the next request's query string, URL-encoded. Continue until
+`hasNext` is `false`. The optional `paging.limit` controls the page size; omit the
+cursor on the first request. Treat cursors as opaque.
+
+Use each selected entry's `itemId` as a `pageIds` entry for Inspect URLs. Do not
+use the composite `id` (`STATIC_PAGE:c1dmp`) or a page URL, and never invent an ID.
+The example below assumes discovery returned `c1dmp` for the selected page.
+
+```
+POST https://www.wixapis.com/gsc/v1/inspect-urls
+```
+
+```json
+{ "pageIds": ["c1dmp"], "updateResults": true }
+```
+
+```json
+{ "results": [ { "page": { "pageId": "c1dmp", "name": "Home", "path": "/", "itemType": "STATIC_PAGE" },
+  "status": "OK", "createdDate": "2026-09-07T12:09:55.301Z",
+  "data": { "inspectionResultLink": "https://search.google.com/search-console/inspect?resource_id=https%3A%2F%2Fwww.example.com%2F&id=EXAMPLE_INSPECTION_ID",
+    "indexStatusResult": { "verdict": "PASS", "coverageState": "Submitted and indexed",
+      "indexingState": "INDEXING_ALLOWED", "lastCrawlTime": "2026-08-16T11:39:45Z",
+      "googleCanonical": "https://www.example.com/", "userCanonical": "https://www.example.com/" } } } ],
+  "status": "COMPLETE", "remainingPageCount": 0 }
+```
+
+- `data.inspectionResultLink` is returned by Google. The complete URL above is
+  illustrative; use the actual returned link unchanged, including its query
+  parameters. Do not construct a link from the example values.
+- Each page spends one unit of the account's Google quota (2,000 per property per
+  day): confirm the page list first. Sites over 2,000 pages fail with
+  `SITE_EXCEEDS_INSPECTION_LIMIT`.
+- The site stores **one** inspection; without `updateResults: true` a new call
+  replaces it. Prefer `true` unless the user wants a clean run.
+- `ONGOING`: poll `GET https://www.wixapis.com/gsc/v1/inspection` every few
+  seconds until `COMPLETE` or `ERROR` (same shape plus `updatedDate`).
+- `remainingPageCount > 0` on `COMPLETE` means quota ran out. Name the missing
+  pages; do not call it done.
+- `data` is Google's raw URL Inspection payload: read `indexStatusResult.verdict`
+  (`PASS`, `PARTIAL`, `FAIL`, `NEUTRAL`) and `coverageState`; text is English only.
+  `UNKNOWN_INSPECTION_STATUS` with empty `results` means never inspected.
+
+## Disconnect and clear
+
+Two different removals; confirm which one the user wants.
+
+| Call | Removes | Keeps |
+|---|---|---|
+| `POST /gsc/connection/v1/disconnect` | Stored Google credentials | Verification tag, Search Console property |
+| `POST /gsc/v1/clear-verification` | Verification tag, verification state, **and** credentials | Search Console property |
+
+Neither removes the site from Search Console or revokes Wix's access on Google's
+side. Disconnect with no stored credentials returns `NOT_FOUND`
+(`CONNECTION_NOT_FOUND`).
+
+## When a call fails
+
+- `403` or `PERMISSION_DENIED`: stop after the first and report the missing SEO
+  permission (reads need view access to SEO settings, writes need manage access).
+  Do not try another site, path, or method.
+- `FAILED_PRECONDITION`: act on `details.applicationError.code` as above. Do not
+  retry the same call.
+- Get Connect URL is a recovery step only for `MISSING_TOKEN`, `INVALID`, or
+  `TOKEN_INVALID`, and only after the user agrees to reconnect.

package/skills/wix-manage/references/sites/upload-static-site.md

@@ -0,0 +1,53 @@
+---
+name: "Upload a Website or HTML Files"
+description: Get a user's ready-made website live on Wix when they already have the site files — an index.html, a zip, or a static build exported from an AI builder or any other tool — by sending them to the Wix Headless drop page, where they upload the files and instantly get a live hosted site they can claim into their account. Use whenever the user wants to upload, publish, or host their own HTML/CSS/JS files as a NEW site. Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
+---
+
+# Upload a Website or HTML Files
+
+The user already has a finished website as files — hand-written HTML, a zip
+export, or the output of an AI site builder — and wants it live on Wix as a
+new site. There is no API call to make. Send them to the upload page and
+explain the flow:
+
+```
+https://www.wix.com/headless/drop?utm_campaign=mcp
+```
+
+**Always give the URL exactly as written above, including the
+`utm_campaign=mcp` query parameter.** It attributes the visit to an
+assistant/MCP referral; dropping or rewriting it breaks that attribution.
+
+## What happens on that page
+
+1. The user drags in their files (or a zip) — no login needed.
+2. Wix hosts them immediately on a live URL they can open and share.
+
+## Tell the user before they upload
+
+Share the requirements that match their situation — these are the common
+reasons an upload fails:
+
+- The upload must contain an **HTML file at the top level of the site's
+  files**. It does not need to be named `index.html` — a single HTML file of
+  any name is served as the homepage — and a zip or folder that wraps
+  everything in one top-level folder (e.g. `my-site/index.html`) is unwrapped
+  automatically.
+- Size limits: **3 MB per file, 20 MB total.**
+- **Static files only** — HTML, CSS, JavaScript, and assets. If the user has
+  framework source code that needs a build step (a `package.json`, React/Vue
+  source, etc.), they must run their build first and upload the build output
+  folder's contents, not the source.
+
+## Route the request correctly
+
+| The user has… | Do this |
+|---|---|
+| Site files on their machine (HTML/zip/AI-builder export), wants a new site | This recipe — send them to the drop URL above |
+| A live site or store on another platform (a URL), or CSV/TSV exports, and wants content/products migrated | [Site Import](site-import.md) |
+| An existing Wix site they want to add HTML, an embed, or custom code into | Not this recipe — that's embedding custom code in the site editor |
+| Images, videos, or documents to add to a site | [Upload Media to Wix](../media/upload-media-to-wix.md) — media goes to the site's media files, not a new site |
+
+Do not try to perform the upload for the user through an API, and do not
+create a site for them with other site-creation tools instead — the drop page
+is the flow.

package/skills/wix-manage/references/stores/change-store-currency.md

@@ -5,6 +5,6 @@ description: "Changes the store's payment currency through Site Properties and e
 
 # Change Store Currency
 
-Use the [Site Properties currency recipe](https://dev.wix.com/docs/api-reference/business-management/site-properties/skills/change-payment-currency-site-properties.md) to set the requested payment currency and read it back. Confirm the change with the user before updating it.
+Use the [Change a Site's Regional Properties (Currency, Time Zone, Language) via Site Properties API](../site-properties/change-payment-currency-site-properties.md) recipe to set the requested payment currency and read it back. Confirm the change with the user before updating it.
 
 Catalog product responses may temporarily show the previous currency after carts and checkout use the new one. Allow time for propagation, then recheck.

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

@@ -83,9 +83,22 @@ If any product is missing a price, **do not call the API**. Ask for the missing
 
 ## Build each product
 
+> [!WARNING]
+> **Hard requirement before every create call:** If `productType` is `"PHYSICAL"`, the request MUST include `physicalProperties` on the product and on every variant:
+>
+> ```json
+> {
+>   "productType": "PHYSICAL",
+>   "physicalProperties": {},
+>   "variantsInfo": {"variants": [{"physicalProperties": {}}]}
+> }
+> ```
+>
+> Put supplied physical fields such as weight or dimensions inside those objects; use `{}` when none were supplied. Never invent them, and never execute or retry a physical-product request when either object is absent.
+
 | Concern | Rule |
 |---|---|
-| Type | `PHYSICAL` uses product- and variant-level `physicalProperties`; `DIGITAL` omits them and carries `inventoryItem.inStock` plus `digitalProperties.digitalFile` on each variant. |
+| Type | `PHYSICAL` requires both `productType: "PHYSICAL"` and product-level `physicalProperties`, plus both `productType: "PHYSICAL"` and variant-level `physicalProperties` on every variant. `DIGITAL` omits physical properties and carries `inventoryItem.inStock` plus `digitalProperties.digitalFile` on each variant. |
 | 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. |
@@ -221,6 +234,8 @@ The first is for single endpoints; the second is for bulk endpoints. If the user
 
 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 a physical product on either create endpoint, never send `productType: "PHYSICAL"` by itself. Include `physicalProperties: {}` on the product and `physicalProperties: {}` on every physical variant (or populate those objects with the supplied physical dimensions/weight). The API validates these as aligned one-of pairs and returns 400 if either corresponding field is missing.
+
 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
@@ -300,4 +315,5 @@ Retry only failed transient items, not successful products. If a requested field
 - `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`.
+- `productType` alignment 400 (`product is invalid: productType and the corresponding physical_properties field must be passed together`): pair `productType: "PHYSICAL"` with `physicalProperties` on the product and on every physical variant. The API validates these as aligned one-of pairs, so do not retry with only one level populated. Pair `productType: "DIGITAL"` with the digital variant fields instead.
 - Digital product rejected at add-to-cart: `ITEM_NOT_FOUND_IN_CATALOG` means the variant has no `digitalProperties.digitalFile`; `exceeds available inventory` means it has no `inventoryItem.inStock`. Both read back as a healthy product.

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

@@ -11,7 +11,8 @@ or configuration changes are needed.
 **Banner disabled for this entry flow:** do not add `<WixManageBanner/>`; skip the shared
 storefront instructions' optional banner integration.
 
-Follow STEPs 1–4 below exactly (run STEP 3 in parallel with STEP 2).
+Follow STEPs 1–4 below exactly. Fire product image generations first, then build the client
+(STEP 2), and seed (STEP 3) **after** the client is built — generation finishes while you build.
 
 ## STEP 1 — Install the Wix skills and deploy the storefront vertical to the app
 
@@ -89,17 +90,19 @@ Inline via exec_tool, `base44` is already declared — use it directly; do **not
 `@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.
-
-**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). `generate_image` runs in the background while you build the client, so the
-urls are ready by the time you seed.
+**Product images.** Fire every `generate_image` **before you build the client**, and seed **after**
+it — generation finishes while you build, so by the time you write the seed call your images are
+ready: each finished result now reads `status: "completed"` with its final
+`https://media.base44.com/...` url. Read every `imageUrl` from the results **as they read at that
+moment** — not from what they said when you called the tool — and pass them in the single
+`setupStore` call. A result without a final url by then (still running, or failed) → seed that
+product **without** `imageUrl` and attach it afterwards with `attachProductImages`.
 
 ## STEP 4 — Wrap up
 
-### Preview
+### Verify
+
+Verify **once, after the seed** — home, shop, and a product page against the populated catalog.
 
 Images that are still generating may show `/__generating__/…` placeholders;
 the platform replaces these automatically at turn end, with a stock fallback if generation

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

@@ -24,7 +24,8 @@ No installation, deployment, or AGENTS.md update is needed.
 The deployed implementation and configuration files do not need to be read; use the build and seed
 guides below for their contracts and usage. Continue with STEP 1.
 
-Follow STEPs 1–3 below exactly (run STEP 2 in parallel with STEP 1).
+Follow STEPs 1–3 below exactly. Fire product image generations first, then build the client
+(STEP 1), and seed (STEP 2) **after** the client is built — generation finishes while you build.
 
 ## STEP 1 — Build the client
 
@@ -74,17 +75,19 @@ Inline via exec_tool, `base44` is already declared — use it directly; do **not
 `@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.
-
-**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). `generate_image` runs in the background while you build the client, so the
-urls are ready by the time you seed.
+**Product images.** Fire every `generate_image` **before you build the client**, and seed **after**
+it — generation finishes while you build, so by the time you write the seed call your images are
+ready: each finished result now reads `status: "completed"` with its final
+`https://media.base44.com/...` url. Read every `imageUrl` from the results **as they read at that
+moment** — not from what they said when you called the tool — and pass them in the single
+`setupStore` call. A result without a final url by then (still running, or failed) → seed that
+product **without** `imageUrl` and attach it afterwards with `attachProductImages`.
 
 ## STEP 3 — Wrap up
 
-### Preview
+### Verify
+
+Verify **once, after the seed** — home, shop, and a product page against the populated catalog.
 
 Images that are still generating may show `/__generating__/…` placeholders;
 the platform replaces these automatically at turn end, with a stock fallback if generation

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

@@ -62,7 +62,7 @@ need to diagnose and fix it.
 
 **No seeding in this flow** — the client is the only deliverable. Do not seed, populate, or write data to Wix.
 
-### Preview
+### Verify
 
 Images that are still generating may show `/__generating__/…` placeholders;
 the platform replaces these automatically at turn end, with a stock fallback if generation

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

@@ -11,7 +11,8 @@ only), safe in the frontend; use it directly for the Wix client setup.
 **Banner enabled for this entry flow:** mount `<WixManageBanner/>` once in the Layout, above
 the header in the fixed top region, per the vertical instructions. It is preview-only.
 
-Follow STEPs 1–5 below exactly (run STEP 4 in parallel with STEP 3 — **except `forms`**, see STEP 3).
+Follow STEPs 1–5 below exactly (run STEP 4 in parallel with STEP 3 — **except `forms`**, see
+STEP 3, and **except a seed that attaches entity images**, which runs after the build; see STEP 4).
 
 ## STEP 1 — Install the Wix skills locally
 
@@ -98,8 +99,15 @@ rejects the write. Wire routes/imports in with `find_replace`, leave the rest as
 
 Seed by calling your vertical's ready-made seed module — read
 `.agents/skills/wix-vibe-headless/references/<vertical>/seed/SEED.md` and follow it (the loader
-snippet, admin connector token, entity images with the final `media.base44.com` url, and every field
-shape are there). Gaps or an unexpected shape → the documentation skill available in your environment.
+snippet, admin connector token, and every field shape are there). Gaps or an unexpected shape → the
+documentation skill available in your environment.
+
+**Entity images:** fire every image generation **before you build the client**, and run an
+image-carrying seed **after** the build — generation finishes while you build, and each finished
+result then reads `status: "completed"` with its final `https://media.base44.com/...` url. Read
+every image url from the results **as they read at that moment**, not from what they said when you
+called the tool. No final url by then (still running, or failed) → seed without that image and
+attach it afterwards per the vertical's `SEED.md`.
 Seeding is **admin-only** — not part of the client, which is built solely per the `wix-vibe-headless` skill.
 
 - **Additive only:** never delete or overwrite the user's content, even apparent sample data; ask first if a cleanup truly seems needed.

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

@@ -9,7 +9,7 @@ or configuration changes are needed to build the UI. Never mock products or hand
 `/checkout` URL; the shipped cart uses the eCom redirect session.
 
 ## Prerequisites
-- The site's **Wix Stores** catalog is the read/cart target. It's installed and seeded separately, in parallel with this build — so it may be empty at build time; render the empty state until products land.
+- The site's **Wix Stores** catalog is the read/cart target. It may be empty while the client is being built — render the empty state cleanly. Flows that seed do so after the client is built; verify the storefront once the catalog is populated, not against the empty state.
 
 ## Already installed in `src/`
 Successful deployment verified these files are in place; use this map without needing to read their source (`@/` → `src/`).
@@ -336,6 +336,10 @@ wire these exactly as shown below.
 When adding storefront routes and providers to `src/App.jsx`, preserve the existing platform
 authentication setup, including `AuthProvider`, `useAuth`, and their `@/lib/AuthContext` imports.
 Do not remove or replace that authentication logic.
+The shipped commerce flow needs no login: shoppers browse, cart, and check out on the Wix visitor
+session, which is separate from platform user auth. Whether the storefront is public or members-only
+is the brief's call — default to public, and gate routes behind platform auth only when the brief
+asks for it. Neither choice affects the commerce flow.
 - Wrap the routed tree in `<CartProvider>` (from `@/context/CartContext`).
 - Put your **header + footer in a `Layout`** that renders `<Outlet/>` between them, and nest every
   route under one pathless `<Route element={<Layout/>}>`. Your brand chrome then wraps **every** page

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

@@ -19,9 +19,7 @@ const ctx = { token: accessToken };
 // ONE call: install (+ wait for V3) → create products → categories → attach images, ids kept
 // in memory (no hand-threading). Categories map name -> product NAMES. Pass an imageUrl per product
 // to attach its image; omit it to skip images.
-// imageUrl must be the FINAL https://media.base44.com/... url from the COMPLETED generate_image
-// result — not a still-generating /__generating__/<id>.png placeholder (Wix can't fetch that).
-// generate_image runs in the background while you build, so the urls are ready by seed time.
+// imageUrl: a public, fetchable https:// url — Wix copies the image bytes at attach time.
 const result = await seed.setupStore(ctx, {
   currency: "EUR", // Pass only if the user asked for a currency or it's obvious for the store; else omit this line.
   products: [
@@ -38,6 +36,8 @@ const result = await seed.setupStore(ctx, {
   categories: { "Legends": ["The Glam Rocker"], "Rising Stars": [] },   // omit if the brief names none
 });
 // result: { products:[{id,slug,revision,name}], categories:[{id,name}], imagesAttached,
+//   imagesSkipped (product names whose imageUrl was not an absolute https:// url — attach those afterwards),
+//   productsWithoutImages (product names seeded with no imageUrl — attach afterwards once urls exist),
 //   currency: { requested, actual, status, warnings } }
 ```
 
@@ -112,6 +112,8 @@ enrolls in — is **Pricing Plans**, not a Stores product, so it isn't seeded he
 download — uploaded and created with both the file and stock, which is what the cart requires
 (`quantity` is ignored). It's also the only way in: a file-less digital product is created
 successfully, reads back healthy, and is then rejected at add-to-cart as `ITEM_NOT_FOUND_IN_CATALOG`.
+No real, fetchable file in hand → seed the product as **physical** with `inStock: true` and tell the
+user; swap it to a digital download once a real file exists.
 
 Two things this module does **not** seed, so don't try:
 
@@ -138,7 +140,6 @@ const products = await seed.bulkCreateProducts(ctx, [                 // → [{i
 ]);
 const cats = await seed.createCategories(ctx, ["Legends"]);           // sequential → [{id,name}]
 await seed.addProductsToCategories(ctx, { [cats[0].id]: [products[0].id] });
-// images: use the FINAL https://media.base44.com/... url only (never a /__generating__/ placeholder)
 await seed.attachProductImages(ctx, products.map((p, i) => ({ id: p.id, url: imageUrls[i], altText: p.slug })));
 ```
 

package/skills/wix-vibe-headless/references/storefront/seed/seed-store.cjs

@@ -257,7 +257,8 @@ async function uploadDigitalFile(ctx, url, fileName) {
   if (!mimeType) throw new Error(`digitalFileName needs one of these extensions (${Object.keys(FILE_MIME).join(", ")}): ${fileName}`);
   const { uploadUrl } = await req(ctx, "/site-media/v1/files/generate-upload-url", { body: { mimeType, fileName } });
   const src = await fetch(url);
-  if (!src.ok) throw new Error(`digitalFileUrl ${url} -> ${src.status}`);
+  if (!src.ok) throw new Error(`digitalFileUrl ${url} -> ${src.status}. A digital product needs a real, ` +
+    `fetchable file — with none at hand, seed this product as physical with inStock: true and tell the user.`);
   const res = await fetch(uploadUrl, {
     method: "PUT", headers: { "Content-Type": mimeType }, body: Buffer.from(await src.arrayBuffer()),
   });
@@ -416,9 +417,17 @@ async function addProductsToCategories(ctx, mapping) {
 // caller never manages a revision token — attach any number of times, in any pass. Wix re-hosts the
 // image from the url server-side; the re-hosted media can take a little while to appear on read-back
 // (propagation) — that's normal, not a failure, so we don't block on it.
+// Wix imports the image bytes server-side, so an attach needs an absolute, publicly fetchable url.
+const isFetchableImageUrl = (url) => typeof url === "string" && /^https:\/\//.test(url);
+
 async function attachProductImages(ctx, items) {
   if (!items?.length) return;
   if (items.some((it) => !it.id)) throw new Error("Image attachment requires a product ID for every item; no image request was sent.");
+  const unfetchable = items.filter((it) => !isFetchableImageUrl(it.url));
+  if (unfetchable.length) throw new Error(
+    `Image url(s) for [${unfetchable.map((it) => it.altText || it.id).join(", ")}] are not absolute ` +
+    `https:// urls, and Wix copies the image bytes at attach time. Re-call attachProductImages once each ` +
+    `image has its final url. No image request was sent; products are unaffected.`);
   const ids = items.map((it) => it.id);
   const q = await req(ctx, "/stores/v3/products/query", { body: { query: { filter: { id: { $in: ids } }, paging: { limit: ids.length } } } });
   const revById = new Map((q.products ?? []).map((p) => [p.id, p.revision]));
@@ -475,7 +484,8 @@ async function configureCurrency(ctx, requested) {
  *                digitalFileUrl?, digitalFileName? }],
  *   categories?: { [categoryName]: string[] },   // map of category name -> product NAMES in it
  * }}
- * @returns { products: [{id,slug,revision,name}], categories: [{id,name}], imagesAttached: number, currency: {requested,actual,status,warnings} }
+ * @returns { products: [{id,slug,revision,name}], categories: [{id,name}], imagesAttached: number,
+ *             imagesSkipped?: string[], note?: string, currency: {requested,actual,status,warnings} }
  */
 async function setupStore(ctx, { products = [], categories = {}, currency } = {}) {
   validateProducts(products);
@@ -498,11 +508,29 @@ async function setupStore(ctx, { products = [], categories = {}, currency } = {}
   }
 
   const imageItems = withNames
-    .map((p, i) => ({ id: p.id, url: products[i]?.imageUrl, altText: products[i]?.altText ?? p.slug }))
+    .map((p, i) => ({ id: p.id, url: products[i]?.imageUrl, altText: products[i]?.altText ?? p.slug, name: p.name }))
     .filter((it) => it.url);
-  if (imageItems.length) await attachProductImages(ctx, imageItems);
+  // A url Wix cannot fetch would fail the attach: seed the product imageless and report it,
+  // so the caller attaches once the final url exists.
+  const readyItems = imageItems.filter((it) => isFetchableImageUrl(it.url));
+  const skipped = imageItems.filter((it) => !isFetchableImageUrl(it.url)).map((it) => it.name);
+  if (readyItems.length) await attachProductImages(ctx, readyItems);
 
-  return { products: withNames, categories: cats, imagesAttached: imageItems.length, currency: currencyResult };
+  const withoutImages = withNames.filter((p, i) => !products[i]?.imageUrl).map((p) => p.name);
+  return {
+    products: withNames, categories: cats, imagesAttached: readyItems.length,
+    ...(skipped.length && {
+      imagesSkipped: skipped,
+      note: "these products' image urls were not absolute https:// urls — attach them with " +
+        "attachProductImages once each image has its final url",
+    }),
+    ...(withoutImages.length && !skipped.length && {
+      productsWithoutImages: withoutImages,
+      note: "these products were seeded without an image — once their images have final urls, " +
+        "attach them with attachProductImages",
+    }),
+    currency: currencyResult,
+  };
 }
 
 module.exports = {