@wix/agent-skills 1.18.0 → 1.18.2

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

@@ -20,6 +20,19 @@ Canonical example:
 - 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.**
 
+## Sections
+
+- [Preflight](#preflight-respond-and-return-before-mutation) — whether this turn may mutate at all, and what to answer when it may not
+- [Core flow](#core-flow) — the order the rest of this recipe runs in
+- [Choose the endpoint](#choose-the-endpoint) — single vs bulk, with or without inventory
+- [Build each product](#build-each-product) — the product object: type, media, options, variants, prices, SKUs
+- [Generated descriptions and SEO](#generated-descriptions-and-seo) — what copy written from an image may claim
+- [Add images](#add-images) — uploading a supplied image, or generating one
+- [Wrap the request](#wrap-the-request) — the envelope the chosen endpoint expects
+- [Request projected media](#request-projected-media-when-validating-images) — which fields to project so images are proven on create
+- [Validate before reporting success](#validate-before-reporting-success) — what counts as proof, and what may be claimed
+- [Failure guide](#failure-guide) — reading a rejection
+
 ## 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.
@@ -180,7 +193,9 @@ With no file supplied, create the product and report it as not sellable until on
 
 ## 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`:
+Skip this step when no image was supplied — unless the user asked for one to be generated, in which case create it first with [Generate an Image with AI](../media/generate-image-with-ai.md) and continue below with the Media Manager file it returns. Do not offer generation unprompted, and never generate a substitute for a supplied image that failed to upload.
+
+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"}

package/skills/wix-manage/references/stores/update-product-with-options.md

@@ -218,6 +218,14 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
 
 When updating existing variants, include each existing variant `id`. If no GUID is passed, a variant is created with a new GUID. Each variant object is replaced whole rather than merged, so carry over the fields you are not changing: rebuilding a variant from just its `id` plus the field you want to set drops everything else and is rejected on the first required field it lost (`price must not be empty`). Start from the variant as returned by Get Product and override only what the user asked to change.
 
+### Renaming an Existing Choice Is Not Supported
+
+`options[].choicesSettings.choices` is immutable once a choice exists — this includes the choice's own `name`. If the user asks to rename, fix a typo in, or standardize the name of an **existing** option choice (for example a shared/reusable customization like "Color" or "Patch Design" that already has variants), do not attempt an Update Product or Update Customization PATCH: it returns `200`, `product.revision`/`customization.revision` increments, but the name is silently left unchanged — confirm this yourself with a fresh Get Product/Get Customization call and you will still see the old name. There is currently no endpoint that renames an existing choice, even when you pass back the same `choiceId` and preserve every other choice, option, and variant exactly.
+
+Do not try workarounds that risk the existing variant matrix — do not delete and recreate the choice/option (this destroys all variants using it, along with their prices, SKUs, and inventory), and do not use Set Customization Choices (it fails once the choice is assigned to any product). Tell the user this specific rename isn't possible via the API today and that manually renaming the choice in the Wix dashboard (Site → Products → the product's options) is the only way, or point them to `SupportAndFeedback` to report the gap.
+
+This only blocks renaming an *existing* choice. Adding brand-new choices to an option (Add/Bulk Add Customization Choices, or including a new choice name in a full Update Product `options` payload) works normally.
+
 ### Convert a Simple Product to Color Variants
 
 When adding the first option to a simple product, do not preserve a choice-less default variant unchanged. A simple product often has one existing variant with price or stock but no `choices`. After you add a `Color` option, every variant in `variantsInfo.variants` must include choices that match the product options.
@@ -413,6 +421,7 @@ Confirm from `product.variantsInfo.variants[].digitalProperties.digitalFile` in
 - To update `variantsInfo.variants`, also pass `options`, and vice versa. Variants and options are mutually dependent and must stay aligned.
 - When converting a simple product to an optioned product, rebuild the variants list so every variant has `choices`; do not keep an existing choice-less default variant unchanged.
 - Always include `choicesSettings` with the complete list of choices when updating a product with options.
+- An existing choice's `name` can't be changed via Update Product or Update Customization. The request succeeds and revision increments, but the rename is silently dropped — see "Renaming an Existing Choice Is Not Supported" above.
 - Use `optionChoiceNames` rather than `optionChoiceIds` in variants for more reliable updates. Reading them back is not symmetric: Get Product returns each variant's `choices` with `optionChoiceIds` only, and fills in `optionChoiceNames` just when the request's `fields` array includes `"VARIANT_OPTION_CHOICE_NAMES"`. So to find the variant for a named choice such as `Large`, either pass that field and match on the name, or take the choice GUID from `options[].choicesSettings.choices[].choiceId` and match it against `variants[].choices[].optionChoiceIds.choiceId`. Matching on a name the response never carried raises nothing — it just selects no variant.
 - Include the `renderType` in `optionChoiceNames`.
 

package/skills/wix-vibe-headless/SKILL.md

@@ -86,34 +86,35 @@ This skill is the deliberately **client-only, REST-only** path. It is independen
   genuine gap (a field, an endpoint, or an error the snippets don't cover), extend the client with
   `wixApiRequest` — confirming the exact endpoint, method, and body first. **For that iteration and
   troubleshooting** — finding the right endpoint, reading a method's request/response schema, or
-  diagnosing an API error — fall back to the **`wix-docs`** skill (`../wix-docs/SKILL.md` when
-  co-installed): it covers `curl` doc-search, reading pages, and structured API-spec queries.
+  diagnosing an API error — consult the official Wix API documentation using the documentation
+  skill available in your environment to search methods, read pages, and inspect API schemas.
   Reference index: https://dev.wix.com/docs/api-reference.md
 - **Provide the user with deep links to the Wix dashboard**: In many cases, the user will need to modify the default vertical data in the Wix dashboard. Always provide the user with these links. The relevant information for each vertical's links is in its `INSTRUCTIONS.md` file.
 
 ## How this skill is structured
 
-`<SKILL_ROOT>` is this file's directory (strip `/SKILL.md`). Each vertical ships a **complete UI
-client as files** under `references/<vertical>/app/` — `components/`, `pages/`,
-`hooks/`/`context/`, and its REST helpers in `app/rest/` — plus the **shared transport** in
+`<SKILL_ROOT>` is this file's directory (strip `/SKILL.md`). Each vertical supplies integration
+code under `references/<vertical>/app/`: REST helpers in `app/rest/`, and, depending on the
+vertical, utilities, hooks, context, components, or pages. All use the **shared transport** in
 `references/shared/app/` (`app/rest/wix-client.js` + `wix-config.js`, identical for every vertical).
 Set `WIX_CLIENT_ID` (and `WIX_METASITE_ID`) in `wix-config.js`. Deploying `references/<vertical>/app/`
-and `references/shared/app/` into the app's `src/` puts every file in place — the helpers all land in
+and `references/shared/app/` into the app's `src/` puts every file in place — the REST helpers land in
 `src/rest/`, so their relative imports resolve.
 
 **Where these files live in the app, and how they get there** (pre-installed at setup, or copied
 in) **is your platform's call — follow your platform instructions for that.**
 
-Each vertical's `INSTRUCTIONS.md` is the full playbook for that solution: when to use it,
-prerequisites, the exported API, how to wire it, the hard rules, and a verification checklist.
-**Open the relevant `INSTRUCTIONS.md` before wiring** — the shapes and gotchas live there.
+Each vertical's `INSTRUCTIONS.md` specifies its prerequisites, supplied pieces, exported interfaces,
+and the presentation you must build. **Read it before implementation**: reuse the supplied pieces
+and build the missing presentation without reimplementing shipped logic. Follow the platform's
+and vertical's completion guidance where provided.
 
 ## Routing — pick the vertical(s) from the request
 
 Load the vertical(s) the user's app needs; a project may combine several (e.g. a restaurant
 with a blog, or a store with pricing plans).
 
-Each vertical's UI + helpers ship in `references/<vertical>/app/`; copy that dir plus
+Each vertical's integration files ship in `references/<vertical>/app/`; copy that dir plus
 `references/shared/app/` into the app's `src/` (base44 does this at install via `deploy.cjs`).
 
 | The user wants… | Vertical | Read |
@@ -165,14 +166,12 @@ installed, not what the business is about. Never default to store/bookings on si
    `references/shared/app/` into the app's `src/`, and set `WIX_CLIENT_ID` in `wix-config.js`. (Where
    and how they get there is your platform's call — see its instructions. On base44 the install step
    writes and verifies `wix-config.js` for you, so there's nothing to set by hand.)
-4. **Wire the shipped client** following the vertical's INSTRUCTIONS: the components are themed by
-   base44's design tokens (`src/index.css` — shadcn palette, already set by the design phase), so
-   there's no re-skin step; just wire routes + header/footer through the Layout. The UI ships as
-   files — you compose the home page and wire it, you don't rebuild the client. Style what you add
-   from the same tokens: every background paired with its own foreground (`bg-primary` with
-   `text-primary-foreground`), `border-input` on form controls, `border-border` on cards and dividers.
-5. **Verify** against the vertical's checklist before declaring done: token persists across
-   reload, live data renders (or a real empty state), and purchases go through the Wix redirect.
+4. **Build the presentation and wire the integration** following the vertical's `INSTRUCTIONS.md`.
+   Reuse its supplied pieces through their documented interfaces, build the presentation it leaves
+   to you, and connect routes/providers as specified. Do not reimplement shipped logic. Style new
+   presentation using the existing platform theme.
+5. **Complete the applicable platform and vertical guidance**, including any required checks and
+   handoff instructions they provide.
 
 > Some flows need Wix-side setup the user completes later (payments connected, the deployed
 > domain allow-listed on the OAuth client for hosted-checkout return, collection permissions).

package/skills/wix-vibe-headless/install/pin-agents-md.cjs

@@ -25,7 +25,7 @@ The Wix skills live under \`.agents/skills/\` — on ANY turn, read them from th
   - **events** — publish events and handle RSVPs or ticket sales.
   - **members** — let visitors create an account and sign in — this is **auth**.
   - **restaurants** — publish a menu, take online orders, and manage table reservations.
-- \`wix-docs\` — **fallback** for **frontend code**, **backend code**, or **runtime / API management operations** alike: search + read the Wix API reference docs.
+- **Documentation fallback** for **frontend code**, **backend code**, or **runtime / API management operations** alike: consult the official Wix API documentation using the documentation skill available in your environment.
 `;
 
 const amd = '/app/AGENTS.md';

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

@@ -0,0 +1,118 @@
+# 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.
+
+The shipped client is already configured. Use its documented hooks and components; no ID lookup
+or configuration changes are needed.
+
+> **The Wix skills installed below are the complete build and seed path for this app.** **Do NOT use the Base44 commerce kit (or any Base44 solution kit).**
+
+**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).
+
+## STEP 1 — Install the Wix skills and deploy the storefront vertical to the app
+
+Install three skills — they land under `.agents/skills/`:
+- **`wix-vibe-headless`** — storefront build instructions, hook/component contracts, and seeding modules.
+- **`wix-manage`** — REST recipes for managing and configuring the Wix site.
+- **`wix-base44-connector`** — Wix connector usage, API contracts, and documentation discovery.
+
+
+Run this through exec_tool, exactly as written — installs all three 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-manage', 'wix-base44-connector']) {
+  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) };
+```
+
+## 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.
+
+The shipped storefront provides catalog, cart, and checkout. Identify the additional workflows
+in the user's request and implement them alongside the storefront. If a workflow needs an
+external service or missing information, continue the work you can complete and identify the
+remaining dependency.
+
+For code or actions not covered by this skill, read and follow the installed connector skill at
+`.agents/skills/wix-base44-connector/SKILL.md` to find Wix documentation and APIs.
+
+Build the client using the component outlines, interfaces, and theme guidance in `INSTRUCTIONS.md`.
+The shipped files are already deployed and configured; you do not need to read their source or
+rebuild them. If you encounter an error after building the client, read or change whatever you
+need to diagnose and fix it.
+
+## 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, `seed-store.cjs` — `require()` it and use its
+one-call `setupStore` (build-time exec_tool). Read
+`.agents/skills/wix-vibe-headless/references/storefront/seed/SEED.md` for the full `setupStore`
+contract — the `ctx` and the product/category shapes.
+
+```js
+const seed = require(require("path").resolve(".agents/skills/wix-vibe-headless/references/storefront/seed/seed-store.cjs"));
+const result = await seed.setupStore(ctx, { products, categories }); // one call: install → products → categories → images
+```
+
+For code or actions not covered by this skill, read and follow the installed connector skill at
+`.agents/skills/wix-base44-connector/SKILL.md` to find Wix documentation and APIs.
+
+**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.
+
+**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.
+
+## STEP 4 — Wrap up
+
+### Preview
+
+Images that are still generating may show `/__generating__/…` placeholders;
+the platform replaces these automatically at turn end, with a stock fallback if generation
+fails. You can finish without waiting for those images or replacing their placeholder URLs.
+
+### Final text response
+
+**Never paste a Wix dashboard link or path.**
+
+**Before writing your final text response, make one handoff call** — `search_base44_docs(query="how do I manage my store's products, orders and inventory?", prefer_dashboard=true)`. Use its handoff guidance, note that the seeded catalog is mock data they can edit, replace or delete, and state any requested workflows that remain unfinished and what is needed to complete them.
+
+## Additional Wix functionality
+
+During the initial build or later, use the installed connector skill at
+`.agents/skills/wix-base44-connector/SKILL.md` to find Wix documentation and APIs for writing code
+or performing actions not covered by this skill.

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

@@ -3,65 +3,64 @@
 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.
+The shipped client is already configured. Use its documented hooks and components; no ID lookup
+or configuration changes are needed.
 
-> **The Wix skills installed below are the complete build and seed path for this app.** **Do NOT use the Base44 commerce kit (or any Base44 solution kit).**
+> **The installed Wix skills 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).
+**Banner disabled for this entry flow:** do not add `<WixManageBanner/>`; skip the shared
+storefront instructions' optional banner integration.
 
-## STEP 1 — Install the Wix skills and deploy the storefront vertical to the app
+## STEP 0 — Setup already completed by Base44
 
-Install three skills — they land under `.agents/skills/`:
-- **`wix-vibe-headless`** — the storefront build + seed guide (STEPs 2–3): your main source of truth.
-- **`wix-manage`** — REST recipes for managing and configuring the site (install apps, seed
-  catalogs, business setup).
-- **`wix-base44-connector`** — building on Wix from the Base44 sandbox: site context, API
-  contracts, and the docs **fallback** — find + read the Wix API docs for anything
-  `wix-vibe-headless` doesn't cover.
+These skills are already installed under `.agents/skills/`:
+- **`wix-vibe-headless`** — storefront build instructions, hook/component contracts, and seeding modules.
+- **`wix-manage`** — REST recipes for managing and configuring the Wix site.
+- **`wix-base44-connector`** — Wix connector usage, API contracts, and documentation discovery.
 
-Run this through exec_tool, exactly as written — installs all three skills, deploys the `storefront` REST scaffolds + UI into `src/`, and pins the AGENTS.md note.
+Base44 has also deployed the storefront hooks, cart components/context, image helpers, and REST
+scaffolds into `src/`, configured the Wix connector/client, and added the Wix note to `AGENTS.md`.
+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.
 
-```js
-const { execSync } = require('child_process');
-const { existsSync, readdirSync } = require('fs');
-const results = {};
-for (const skill of ['wix-vibe-headless', 'wix-manage', 'wix-base44-connector']) {
-  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/`.
+Follow STEPs 1–3 below exactly (run STEP 2 in parallel with STEP 1).
 
-## STEP 2 — Build the client
+## STEP 1 — 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.
+The shipped storefront provides catalog, cart, and checkout. Identify the additional workflows
+in the user's request and implement them alongside the storefront. If a workflow needs an
+external service or missing information, continue the work you can complete and identify the
+remaining dependency.
 
-**`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.
+For code or actions not covered by this skill, read and follow the installed connector skill at
+`.agents/skills/wix-base44-connector/SKILL.md` to find Wix documentation and APIs.
 
-## STEP 3 — Seed the storefront
+Build the client using the component outlines, interfaces, and theme guidance in `INSTRUCTIONS.md`.
+The shipped files are already deployed and configured; you do not need to read their source or
+rebuild them. If you encounter an error after building the client, read or change whatever you
+need to diagnose and fix it.
+
+## STEP 2 — 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-base44-connector`** skill's doc discovery.
+Seed by calling the storefront's ready-made seed module, `seed-store.cjs` — `require()` it and use its
+one-call `setupStore` (build-time exec_tool). Read
+`.agents/skills/wix-vibe-headless/references/storefront/seed/SEED.md` for the full `setupStore`
+contract — the `ctx` and the product/category shapes.
+
+```js
+const seed = require(require("path").resolve(".agents/skills/wix-vibe-headless/references/storefront/seed/seed-store.cjs"));
+const result = await seed.setupStore(ctx, { products, categories }); // one call: install → products → categories → images
+```
+
+For code or actions not covered by this skill, read and follow the installed connector skill at
+`.agents/skills/wix-base44-connector/SKILL.md` to find Wix documentation and APIs.
 
 **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:
@@ -76,35 +75,29 @@ Inline via exec_tool, `base44` is already declared — use it directly; do **not
 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-base44-connector` doc discovery if the module
-doesn't cover it.
+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). 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
+call (images included). `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
+## STEP 3 — Wrap up
 
-**Do NOT add the `<WixManageBanner/>` component** and never paste a Wix dashboard link or path.
+### Preview
 
-**Hand off with one call, before you write anything** — `search_base44_docs(query="how do I manage my store's products, orders and inventory?", prefer_dashboard=true)`. It comes back telling you what to say; add only that the catalog you seeded is mock data they can edit, replace or delete.
+Images that are still generating may show `/__generating__/…` placeholders;
+the platform replaces these automatically at turn end, with a stock fallback if generation
+fails. You can finish without waiting for those images or replacing their placeholder URLs.
 
-**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.
+### Final text response
 
-## Later admin requests
+**Never paste a Wix dashboard link or path.**
 
-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:
+**Before writing your final text response, make one handoff call** — `search_base44_docs(query="how do I manage my store's products, orders and inventory?", prefer_dashboard=true)`. Use its handoff guidance, note that the seeded catalog is mock data they can edit, replace or delete, and state any requested workflows that remain unfinished and what is needed to complete them.
 
-```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();
-```
+## Additional Wix functionality
 
-`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 the `wix-base44-connector` skill's doc discovery.
+During the initial build or later, use the installed connector skill at
+`.agents/skills/wix-base44-connector/SKILL.md` to find Wix documentation and APIs for writing code
+or performing actions not covered by this skill.

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

@@ -3,22 +3,23 @@
 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.
+The shipped client is already configured. Use its documented hooks and components; no ID lookup
+or configuration changes are needed.
 
 > **The Wix skills installed below 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.**
 
+**Banner disabled for this entry flow:** do not add `<WixManageBanner/>`; skip the shared
+storefront instructions' optional banner integration.
+
 Follow STEPs 1–3 below exactly.
 
 ## STEP 1 — Install the Wix skills and deploy the storefront vertical to the app
 
 Install three skills — they land under `.agents/skills/`:
-- **`wix-vibe-headless`** — the storefront build guide (STEP 2): your main source of truth.
-- **`wix-manage`** — REST recipes for managing and configuring the site (install apps, seed
-  catalogs, business setup).
-- **`wix-base44-connector`** — building on Wix from the Base44 sandbox: site context, API
-  contracts, and the docs **fallback** — find + read the Wix API docs for anything
-  `wix-vibe-headless` doesn't cover.
+- **`wix-vibe-headless`** — storefront build instructions, hook/component contracts, and seeding modules.
+- **`wix-manage`** — REST recipes for managing and configuring the Wix site.
+- **`wix-base44-connector`** — Wix connector usage, API contracts, and documentation discovery.
+
 
 Run this through exec_tool, exactly as written — installs all three skills, deploys the `storefront` REST scaffolds + UI into `src/`, and pins the AGENTS.md note.
 
@@ -40,40 +41,41 @@ const agentsMd = execSync(`node /app/.agents/skills/wix-vibe-headless/install/pi
 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.
+The shipped storefront provides catalog, cart, and checkout. Identify the additional workflows
+in the user's request and implement them alongside the storefront. If a workflow needs an
+external service or missing information, continue the work you can complete and identify the
+remaining dependency.
 
-**`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.
+For code or actions not covered by this skill, read and follow the installed connector skill at
+`.agents/skills/wix-base44-connector/SKILL.md` to find Wix documentation and APIs.
+
+Build the client using the component outlines, interfaces, and theme guidance in `INSTRUCTIONS.md`.
+The shipped files are already deployed and configured; you do not need to read their source or
+rebuild them. If you encounter an error after building the client, read or change whatever you
+need to diagnose and fix it.
 
 ## 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 never paste a Wix dashboard link or path.
+### Preview
 
-**Hand off with one call, before you write anything** — `search_base44_docs(query="how do I manage my store's products, orders and inventory?", prefer_dashboard=true)`. It comes back telling you what to say.
+Images that are still generating may show `/__generating__/…` placeholders;
+the platform replaces these automatically at turn end, with a stock fallback if generation
+fails. You can finish without waiting for those images or replacing their placeholder URLs.
 
-**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.
+### Final text response
 
-## Later admin requests
+**Never paste a Wix dashboard link or path.**
 
-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:
+**Before writing your final text response, make one handoff call** — `search_base44_docs(query="how do I manage my store's products, orders and inventory?", prefer_dashboard=true)`. Use its handoff guidance, state any requested workflows that remain unfinished and what is needed to complete them.
 
-```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();
-```
+## Additional Wix functionality
 
-`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 the `wix-base44-connector` skill's doc discovery.
+During the initial build or later, use the installed connector skill at
+`.agents/skills/wix-base44-connector/SKILL.md` to find Wix documentation and APIs for writing code
+or performing actions not covered by this skill.

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

@@ -8,11 +8,14 @@ only), safe in the frontend; use it directly for the Wix client setup.
 
 > **The Wix skills installed below are the complete build and seed path for this app — the Wix connector supplies the token for admin API calls.** **Do NOT use the Base44 commerce kit (or any Base44 solution kit).**
 
+**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).
 
 ## STEP 1 — Install the Wix skills locally
 
-Install three skills under `.agents/skills/`: **`wix-vibe-headless`** (the client build + seed guide — your main source of truth), **`wix-manage`** (REST recipes to manage/configure the site), and **`wix-base44-connector`** (site context + API-doc discovery, the fallback for anything the others don't cover).
+Install three skills under `.agents/skills/`: **`wix-vibe-headless`** (the client build + seed guide — your main source of truth), **`wix-manage`** (REST recipes to manage/configure the site), and **`wix-base44-connector`** (site context + API-doc discovery).
 
 Run this through exec_tool, exactly as written — installs all three skills, deploys REST scaffolds + UI into `src/`, writes `wix-config.js`, and pins the AGENTS.md note.
 
@@ -96,7 +99,7 @@ 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 **`wix-base44-connector`** skill's doc discovery.
+shape are there). Gaps or an unexpected shape → the documentation skill available in your environment.
 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.
@@ -104,14 +107,18 @@ Seeding is **admin-only** — not part of the client, which is built solely per
 
 ## STEP 5 — Wrap up
 
-1. **Mount `<WixManageBanner/>`** (required) in your Layout's fixed top region, above the header, per your vertical's INSTRUCTIONS — it links the app to its Wix back office, self-gates to the preview, and never shows on the published site.
-2. **Ask the user to open** `https://manage.wix.com/dashboard/{metaSiteId}` (your metasite id) to complete setup in Wix.
+**Ask the user to open** `https://manage.wix.com/dashboard/{metaSiteId}` (your metasite id) to complete setup in Wix.
 
 **Don't chase images.** A `/__generating__/…` placeholder is swapped for the final url automatically at turn end — do **not** edit, re-seed, or debug image urls.
 
 ## Later admin requests
 
 For any later admin/management request, work as in STEP 4: your vertical's seed module first, else
-`wix-base44-connector` doc discovery — all over the connector.
+consult official Wix API documentation using the documentation skill available in your environment.
+Keep admin calls on the connected Wix connector.
+
+**A change to what the business data COLLECTS is one of these, however UI it sounds** — a new form
+field, product option or service setting. Change it on Wix first per the vertical's `seed/SEED.md`,
+then edit the client against the verified result.
 
 version: v1341