@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -275,6 +275,8 @@ curl -X POST "https://www.wixapis.com/stores/v3/bulk/inventory-items/create" \
 
 ### Update Media Only
 
+Sets the product-level gallery (`media.itemsInfo.items`). For an image shown per option choice (a swatch's photo), see **Per-choice media** below.
+
 ```bash
 curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   -H "Content-Type: application/json" \
@@ -297,6 +299,56 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   }'
 ```
 
+### Choice & variant fields (what you can set)
+
+Send these inside the `options` / `variantsInfo.variants` arrays — **both arrays complete, in the
+same PATCH**, with the current `revision`, and **identity-preserving** (see *Update Options and
+Variants*): keep the option's `id` and every `choiceId`, or the ids are re-minted and the existing
+variants no longer resolve (`400 "Variant choice not found in product options"`). Each variant needs
+its `id`, its `choices` (by `optionChoiceIds` — or `optionChoiceNames`, see *Gotchas*) **and** a
+`price` — omitting price is `400 "price must not be empty"`.
+
+**Option choice** (`options[].choicesSettings.choices[]`):
+- `name`, `choiceType`, `colorCode` — the choice's identity and swatch colour.
+- `media` = `{ "items": [ { "mediaId" } | { "url" } ] }` — the product photos shown when this choice is picked. `url` is write-only; on read you get `mediaId` (request the `PRODUCT_CHOICES_MEDIA_REFERENCES` mask). Use `media`, **not** `linkedMedia` (a separate display-filter, returned empty when you read `media`).
+  - **Gallery-first; the id you link is the gallery item's, not the upload's.** Add the `url` to the gallery, then read the product back and link the id you see there:
+
+    ```
+    GET /stores/v3/products/{id}?fields=MEDIA_ITEMS_INFO
+    #  → media.itemsInfo.items[].id = "abc~mv2.jpg"   ← link THIS as choice media.items[].mediaId
+    # the id from POST /site-media/v1/files/import or /files/get-file-by-id 400s as a choice mediaId
+    ```
+    `{ "url" }` works in place of `{ "mediaId" }` too, but only once the image is already in the gallery.
+- `displayImage` — the image shown on the swatch itself (distinct from `media`).
+- Read-only, don't send: `inStock`, `visible`, `key`.
+
+**Variant** (`variantsInfo.variants[]`, by its `id` from Get Product; always send `choices` + `price` with it):
+- `price` = `{ "actualPrice": { "amount" }, "compareAtPrice": { "amount" } }` — set `compareAtPrice` above `actualPrice` for a strikethrough sale; omit it for full price.
+- `sku`, `barcode` — per combination.
+- `visible` — hide a single variant.
+- `revenueDetails` — cost / profit tracking.
+- Read-only, don't send: `media` (derived from the choices' media), `inventoryStatus` (stock — use the Inventory API, see *Set Stock for New Variants*), `subscriptionPricesInfo`.
+
+```bash
+# A choice image + a variant's sale price, one PATCH. Both arrays are complete and keep their ids —
+# this exact shape is the one that succeeds; the two shortcuts (choices by name only, or a variant
+# without its choices/price) each 400.
+curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
+  -H "Content-Type: application/json" -H "Authorization: <AUTH>" \
+  -d '{ "product": { "id": "{productId}", "revision": "{currentRevision}",
+        "options": [ { "id": "{optionId}", "name": "Color", "optionRenderType": "COLOR_CHOICES",
+          "choicesSettings": { "choices": [
+            { "choiceId": "{choiceId1}", "name": "Red", "choiceType": "ONE_COLOR", "colorCode": "#C0392B",
+              "media": { "items": [ { "mediaId": "abc~mv2.jpg" } ] } },
+            { "choiceId": "{choiceId2}", "name": "Blue", "choiceType": "ONE_COLOR", "colorCode": "#2C3E50" } ] } } ],
+        "variantsInfo": { "variants": [
+          { "id": "{variantId1}", "sku": "TEE-RED-L",
+            "price": { "actualPrice": { "amount": "20" }, "compareAtPrice": { "amount": "30" } },
+            "choices": [ { "optionChoiceIds": { "optionId": "{optionId}", "choiceId": "{choiceId1}" } } ] },
+          { "id": "{variantId2}", "price": { "actualPrice": { "amount": "20" } },
+            "choices": [ { "optionChoiceIds": { "optionId": "{optionId}", "choiceId": "{choiceId2}" } } ] } ] } } }'
+```
+
 ### Update Variant Price Only
 
 Read `{existingVariantId}` off the Get Product response; a Search or Query Products result does not carry it.
@@ -325,6 +377,35 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   }'
 ```
 
+### Attach a Digital File
+
+A `DIGITAL` product is **sellable** only when its variant carries both a digital file and stock. Upload the file first ([Upload Media to Wix](../media/upload-media-to-wix.md) → Generate Upload URL, then `PUT` the bytes), then send its `file.id` on the variant — `digitalProperties` is a variant field, never a product field.
+
+```bash
+curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: <AUTH>" \
+  -d '{
+    "product": {
+      "id": "{productId}",
+      "revision": "{currentRevision}",
+      "variantsInfo": {
+        "variants": [
+          {
+            "id": "{existingVariantId}",
+            "price": { "actualPrice": { "amount": "9.99" } },
+            "visible": true,
+            "inventoryItem": { "inStock": true },
+            "digitalProperties": { "digitalFile": { "id": "{fileId}" } }
+          }
+        ]
+      }
+    }
+  }'
+```
+
+Confirm from `product.variantsInfo.variants[].digitalProperties.digitalFile` in the response.
+
 ## Important Notes
 
 - A request to hide a product is a `visible: false` update on the product, never a Delete Product call and never a variant-only change.
@@ -348,3 +429,5 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
 | `variantsInfo is invalid: variants has size 0, expected 1 or more` | Variants were read from a Search or Query Products response, which does not return them | Re-read the product with Get Product and send its `variantsInfo.variants` |
 | `Missing option choices` or `INVALID_DEFAULT_VARIANT` | Product has options but at least one variant has no matching choices | Rebuild `variantsInfo.variants` so every variant includes choices for all product options |
 | `DIGITAL_PRODUCT_CANNOT_BE_VISIBLE_IN_POS` | Sent `visibleInPos: true` on a digital product | Digital products can't be visible in POS; leave `visibleInPos` out of the body |
+| `ITEM_NOT_FOUND_IN_CATALOG` at add-to-cart, product exists | A `DIGITAL` variant has no `digitalProperties.digitalFile` | Attach a file — see [Attach a Digital File](#attach-a-digital-file) |
+| `exceeds available inventory` at add-to-cart, product exists | The variant has no stock (`DIGITAL` products included) | Set `inventoryItem.inStock: true` on the variant |

package/skills/wix-replatform/resources/rp-mapper/wix-business-solutions-taxonomy.md

@@ -25,8 +25,7 @@ This distinction must stay explicit in mapper output.
 It owns the purchase flow and operational commerce entities that are reused across multiple vertical apps.
 
 Typical `eCommerce` entities:
-- carts
-- checkouts
+- carts (the unified cart + checkout entity)
 - orders
 - order billing / refunds
 - payment and fulfillment state tied to orders
@@ -90,19 +89,19 @@ Main page:
 - [Integrating with Wix's Business Solutions](https://dev.wix.com/docs/build-apps/get-started/overview/integrating-with-wix-s-business-solutions)
 
 Short description:
-- Shared commerce platform for purchase flow and order operations. It is the canonical target for carts, checkouts, and orders, even when catalog data originates in a vertical app such as Stores or Bookings.
+- Shared commerce platform for purchase flow and order operations. It is the canonical target for carts (Cart V2, which now also covers checkout) and orders, even when catalog data originates in a vertical app such as Stores or Bookings.
 
 Primary entities:
 
 | Entity | What it does | Docs |
 | --- | --- | --- |
-| `cart` | First phase of the purchase flow; holds line items, buyer references, discounts, and pricing context before checkout | [About the eCommerce Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart/cart/introduction) |
-| `current-cart` | Visitor/member scoped cart used in live purchase flows | [About the eCommerce Current Cart API](https://dev.wix.com/docs/sdk/backend-modules/ecom/current-cart/introduction) |
-| `checkout` | Second phase of purchase flow; holds calculated prices, tax, billing, shipping, and discount state before order creation | [About the eCommerce Checkout API](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction) |
+| `cart` | The unified purchase-flow entity — holds line items, buyer/contact info, discounts, delivery, billing, and payment context all the way through placing the order. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
+| `current-cart` | The current cart for a visitor/member session — the same entity as `cart`, addressed by the shopper's session rather than a cart id. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
 | `order` | Final commerce record for completed or externally recorded purchases | [About the Orders API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/introduction) |
 | `order-billing` | Payment capture, void, and refund operations for eCommerce orders | [About the Order Billing API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-billing/introduction) |
 
 Mapper notes:
+- **A source system's separate "checkout" has no distinct Wix target.** The cart is the unified purchase-flow entity (there's no separate checkout), so map a source checkout's *input* state onto `cart`: billing → `paymentInfo.billingAddress`, shipping/delivery → `deliveryInfo`, applied coupons → cart `coupons`. **Calculated price *and* payment figures are NOT stored on the cart** — both the price totals (`summary.priceSummary`) and the payment breakdown (`summary.paymentSummary` — amount due, gift-card deductions, and the like) are computed on demand by Calculate/Estimate Cart (returned in a `CartSummary`), and the final figures live on the `order` after placement — so don't try to persist a source checkout's computed totals on the cart.
 - If the source platform exposes products and orders in one model, split catalog entities into the vertical app and transaction entities into `ecommerce`.
 - If the source has historical orders but no cart or checkout history, map directly to `order` and document missing pre-purchase state.
 

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

@@ -1,6 +1,6 @@
 ---
 name: wix-vibe-headless
-description: "Client-only, dependency-free REST scaffolds for connecting an already-built front end (a vibe-coded app, an HTML/JSX/Vite project, a design-tool export) to a live Wix site over the site's public WIX_CLIENT_ID — the browser talks to Wix directly, no SDK, no backend, no build step. One skill covering every Wix business solution: Stores/eCommerce storefront (products, cart, checkout), Bookings (services, slots, appointments), Blog (posts, categories, tags), Events & Tickets (browse, RSVP, ticketing), Portfolio (collections, projects, galleries), Restaurants (menu, online ordering, reservations), CMS / Wix Data (list, detail, filter, forms, CRUD), Pricing Plans (memberships, subscriptions, checkout), and Members (custom login — email+password, Google/Facebook, and custom SSO — plus account areas and member-gated content). Each vertical ships a copy-as-is REST layer plus wiring instructions. Read-only over the owner's content — never provisions, never mocks data. Triggers: connect my Wix store/shop, build a storefront over Wix, add a cart and checkout, connect Wix Bookings, take appointments/reservations, show my Wix blog, list my Wix events, sell tickets, take RSVPs, build a portfolio from Wix Portfolio, show my restaurant menu / order online / book a table, display my Wix CMS collection, wire a contact form to Wix, sell membership/subscription plans, add member login / sign up, let members log in with Google or Facebook, custom login page, account / profile page, gate content behind login, sign in with SSO/Okta, 'here is my WIX_CLIENT_ID', connect this app to my Wix site over REST. Use this for CLIENT-ONLY REST integration over an existing site; use `wix-headless` instead for SDK + Wix CLI builds, hosting, and one-prompt new-site creation."
+description: "Client-only, dependency-free REST scaffolds for connecting an already-built front end (a vibe-coded app, an HTML/JSX/Vite project, a design-tool export) to a live Wix site over the site's public WIX_CLIENT_ID — the browser talks to Wix directly, no SDK, no backend, no build step. One skill covering every Wix business solution: Stores/eCommerce storefront (products, cart, checkout), Bookings (services, slots, appointments), Blog (posts, categories, tags), Events & Tickets (browse, RSVP, ticketing), Portfolio (collections, projects, galleries), Restaurants (menu, online ordering, reservations), Forms (any visitor-fillable form — contact/enquiry, signup, waitlist, application, survey, quote request; schema-driven render + submit), CMS / Wix Data (list, detail, filter, CRUD), Pricing Plans (memberships, subscriptions, checkout), and Members (custom login — email+password, Google/Facebook, and custom SSO — plus account areas and member-gated content). Each vertical ships a copy-as-is REST layer plus wiring instructions. Read-only over the owner's content — never provisions, never mocks data. Triggers: connect my Wix store/shop, build a storefront over Wix, add a cart and checkout, connect Wix Bookings, take appointments/reservations, show my Wix blog, list my Wix events, sell tickets, take RSVPs, build a portfolio from Wix Portfolio, show my restaurant menu / order online / book a table, display my Wix CMS collection, wire a contact form to Wix, add a contact/enquiry form, build a signup or application form, take survey responses, sell membership/subscription plans, add member login / sign up, let members log in with Google or Facebook, custom login page, account / profile page, gate content behind login, sign in with SSO/Okta, 'here is my WIX_CLIENT_ID', connect this app to my Wix site over REST. Use this for CLIENT-ONLY REST integration over an existing site; use `wix-headless` instead for SDK + Wix CLI builds, hosting, and one-prompt new-site creation."
 ---
 
 # Wix Vibe Headless — client-only REST connectors
@@ -119,15 +119,29 @@ Each vertical's UI + helpers ship in `references/<vertical>/app/`; copy that dir
 | The user wants… | Vertical | Read |
 |---|---|---|
 | Online store: products, categories, cart, checkout | **storefront** | `references/storefront/INSTRUCTIONS.md` |
-| Appointments: services, time slots, booking, checkout | **bookings** | `references/bookings/INSTRUCTIONS.md` |
+| Appointments: services, time slots, booking, checkout — **and the form attached to a bookable service** | **bookings** | `references/bookings/INSTRUCTIONS.md` |
+| Rentals: an item hired for a length **the customer picks** (by the hour or by the day) — Wix Rentals runs on the Bookings APIs, so it is the same vertical | **bookings** | `references/bookings/INSTRUCTIONS.md` ("Rentals") |
 | Blog/news: post feed, post pages, categories, tags | **blog** | `references/blog/INSTRUCTIONS.md` |
-| Events: browse, event page, RSVP, ticketing | **events** | `references/events/INSTRUCTIONS.md` |
+| Events: browse, event page, RSVP, ticketing — **an RSVP is here, not `forms`**, even for one occasion with no tickets | **events** | `references/events/INSTRUCTIONS.md` |
 | Portfolio/showcase: collections, projects, media galleries | **portfolio** | `references/portfolio/INSTRUCTIONS.md` |
 | Restaurant: menu, online ordering, table reservations | **restaurants** | `references/restaurants/INSTRUCTIONS.md` |
-| CMS content: list/detail, filter/search, forms, data CRUD | **cms** | `references/cms/INSTRUCTIONS.md` |
+| Any visitor-fillable form: contact/enquiry, lead, signup, waitlist, application, feedback/survey, quote request, intake or registration. **Not** an event RSVP (`events`) or a per-service booking form (`bookings`) | **forms** | `references/forms/INSTRUCTIONS.md` |
+| CMS content: list/detail, filter/search, data CRUD. **A visitor-fillable form is `forms`** — cms only when the app must read the entries back | **cms** | `references/cms/INSTRUCTIONS.md` |
 | Plans & pricing: memberships/subscriptions, subscribe, my plans | **pricing-plans** | `references/pricing-plans/INSTRUCTIONS.md` |
 | Member accounts: custom login/sign-up (email+password, Google/Facebook, SSO), account area, gated content | **members** | `references/members/INSTRUCTIONS.md` |
 
+**⚠️ Anything a visitor fills in and submits is `forms` — with three exceptions:**
+
+1. **The app must read the entries back → `cms`.** A public gallery, a listing, a member's "my
+   submissions". A visitor cannot read Forms submissions, so those need a collection. Submit-only is
+   always `forms`: a form wired to `insertDataItem` works, but gives up the dashboard form builder,
+   spam protection, submission notifications and CRM contact mapping, and needs the owner to set
+   collection permissions by hand before anyone can submit at all.
+2. **Confirming attendance to an event or occasion → `events`.** A wedding, party or gathering —
+   events ships a built-in RSVP registration form. Route there even for a single occasion with no
+   tickets.
+3. **A form attached to a bookable service → `bookings`.**
+
 ### When the request doesn't name a Wix Business Solution — ask, or check the site
 
 Don't infer which Wix Business Solution to build (stores, bookings, blog, events, portfolio,

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

@@ -1,6 +1,6 @@
 // Post-install deploy — run by base44.md STEP 1 with the vertical(s) the app needs:
 //   node deploy.cjs <vertical> [<vertical> …] --client-id <id> --metasite-id <id>
-//   (storefront | bookings | blog | cms | portfolio | pricing-plans | events | members)
+//   (storefront | bookings | blog | cms | forms | portfolio | pricing-plans | events | members | restaurants)
 // Pass the two ids from the prompt and this writes src/rest/wix-config.js for you — see WRITE below.
 // Retyping those ids into the file by hand is how a storefront ships with a dead client id.
 // ONE mechanism: recursively copy `app/` -> /app/src. The shared transport (app/rest/wix-client.js,
@@ -9,7 +9,7 @@
 // members and cms names both, and its CMS helpers then come from the skill instead of being
 // hand-written. Order matters only where two verticals ship a file at the SAME path (both have
 // components/…, pages/…): the first one listed wins, since the copy never overwrites. Verticals whose
-// file sets don't overlap (cms ships utils only, no UI) combine freely.
+// file sets don't overlap (cms and forms ship utils only, no UI) combine freely.
 // paths are the Base44 sandbox's /app. Re-running is non-destructive: it fills in only missing files,
 // never overwriting the agent's edits (see COPY), so a later call can add a vertical safely.
 // No vertical arg -> deploys just the shared transport; re-run with the vertical(s) once known.
@@ -19,7 +19,7 @@ const { existsSync, cpSync, readFileSync, writeFileSync } = require('fs');
 
 const REF = '/app/.agents/skills/wix-vibe-headless/references';
 const WIX_CONFIG = '/app/src/rest/wix-config.js';
-const VERTICALS = ['storefront', 'bookings', 'blog', 'cms', 'portfolio', 'pricing-plans', 'events', 'members', 'restaurants'];
+const VERTICALS = ['storefront', 'bookings', 'blog', 'cms', 'forms', 'portfolio', 'pricing-plans', 'events', 'members', 'restaurants'];
 
 // force:false + errorOnExist:false — fill in only files that AREN'T there yet; never overwrite.
 // A re-run (e.g. the "files missing? re-run" fallback) then restores what's missing without
@@ -117,8 +117,16 @@ const clientId = flag('client-id');
 const metaSiteId = flag('metasite-id');
 // Verticals are the positional args — drop the flags and their values.
 const flagArgs = new Set(['--client-id', '--metasite-id', clientId, metaSiteId].filter(Boolean));
-const requested = [...new Set(argv.filter((a) => !flagArgs.has(a)))];
+// `rentals` is an alias of the Bookings vertical — Wix Rentals runs on the Bookings APIs. A rental
+// business picks `rentals` and gets the bookings scaffolds; it resolves to bookings everywhere.
+const ALIASES = { rentals: 'bookings' };
+const positional = argv.filter((a) => !flagArgs.has(a));
+const requested = [...new Set(positional.map((a) => ALIASES[a] || a))];
 const deployed = { verticals: [] };
+// Report any alias resolution so the caller sees an intended mapping (rentals -> bookings), not a
+// silent `bookings` result it might read as "rentals unsupported" and wastefully re-deploy.
+const aliased = [...new Set(positional.filter((a) => ALIASES[a]))].map((a) => `${a} -> ${ALIASES[a]}`);
+if (aliased.length) deployed.aliased = aliased;
 
 // Shared transport — always (app/rest/wix-client.js, wix-config.js -> src/rest/).
 if (existsSync(`${REF}/shared/app`)) cpSync(`${REF}/shared/app`, '/app/src', COPY);

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

@@ -18,7 +18,8 @@ The Wix skills live under \`.agents/skills/\` — on ANY turn, read them from th
   - **storefront** — sell physical or digital products online.
   - **bookings** — let customers book appointments or services with your business.
   - **blog** — publish articles for visitors to read.
-  - **cms** — model and serve your own custom, structured content — for anything the other verticals don't cover.
+  - **forms** — any visitor-fillable form: contact/enquiry, lead, signup, waitlist, application, feedback/survey, quote request, intake or registration. **Not forms** — an event or occasion RSVP is **events** (built-in RSVP registration form), and a per-service booking form is **bookings**.
+  - **cms** — model and serve your own custom, structured content — for anything the other verticals don't cover. **Not cms** — a visitor-fillable form is **forms**; reach for cms only when the app must read the entries back.
   - **portfolio** — showcase creative work in collections and project pages.
   - **pricing-plans** — sell memberships or subscriptions to your service.
   - **events** — publish events and handle RSVPs or ticket sales.

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

@@ -6,24 +6,27 @@ 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).**
+> **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).**
 
 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/`:
+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-docs`** — a **fallback**: search + read the Wix API docs for anything `wix-vibe-headless`
-  doesn't cover.
+- **`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.
 
-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.
+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-docs']) {
+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`,
@@ -58,7 +61,7 @@ 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.
+shape → the **`wix-base44-connector`** skill's doc discovery.
 
 **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:
@@ -73,7 +76,8 @@ 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-docs` if the module doesn't cover it.
+storefront seed module's image-attach step — `wix-base44-connector` doc discovery 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`
@@ -83,7 +87,9 @@ 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.
+**Do NOT add the `<WixManageBanner/>` component** and never paste a Wix dashboard link or path.
+
+**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.
 
 **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.
 
@@ -101,4 +107,4 @@ const res = await fetch("https://www.wixapis.com/<api-path>", {
 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`.
+`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.

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

@@ -6,24 +6,27 @@ 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.**
+> **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.**
 
 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/`:
+Install three 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.
+- **`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.
 
-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.
+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-docs']) {
+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`,
@@ -53,7 +56,9 @@ rejects the write. Wire routes/imports in with `find_replace`, leave the rest as
 
 **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.
+**Do NOT add the `<WixManageBanner/>` component** and never paste a Wix dashboard link or path.
+
+**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.
 
 **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.
 
@@ -71,4 +76,4 @@ const res = await fetch("https://www.wixapis.com/<api-path>", {
 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`.
+`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.

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

@@ -6,47 +6,40 @@ initial prompt, and the Wix connector is already configured; use it for all admi
 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 — the Wix connector supplies the token for admin API calls.** **Do NOT use the Base44 commerce kit (or any Base44 solution kit).**
+> **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).**
 
-Follow STEPs 1–5 below exactly (run STEP 4 in parallel with STEP 3).
+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 two skills — they land under `.agents/skills/`:
-- **`wix-vibe-headless`** — the client build **and** seed guide (STEPs 3–4): your main source of
-  truth. Seeding lives here too, per-vertical under `references/<vertical>/seed/`.
-- **`wix-docs`** — a **fallback**: search + read the Wix API docs for anything `wix-vibe-headless`
-  doesn'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, the fallback for anything the others don't cover).
 
-Run this through exec_tool, exactly as written — installs both skills, deploys REST scaffolds + UI into `src/`, writes `wix-config.js`, and pins the AGENTS.md note.
+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.
 
-**Set `VERTICALS`** to what the prompt asks for (too vague to tell? do STEP 2 first, then set it):
+**Set `VERTICALS`** to what the prompt asks for — **list every vertical the app uses**, since several often join the main one (too vague to tell? do STEP 2 first, then set it). Adding one later: re-run with the extra name.
 
 | vertical | pick it when the app needs to |
 |---|---|
 | `storefront` | sell products |
 | `bookings` | take appointments or service bookings |
+| `rentals` | rent out an item for a length the customer picks (by the hour or by the day) |
 | `blog` | publish articles |
 | `events` | publish events with RSVPs or ticket sales |
 | `portfolio` | showcase creative work |
-| `pricing-plans` | sell memberships or subscriptions |
+| `pricing-plans` | sell memberships or subscriptions, incl. paid enrollment/access to an online course or program — but an "online store selling courses" is still `storefront` |
 | `restaurants` | show a menu, take orders, book tables |
 | `members` | let visitors sign in — this is **auth** |
-| `cms` | keep its own structured content — user submissions, galleries, listings, anything the rows above don't already cover |
-
-**List every vertical the app uses.** `cms` for app-stored content, `members` for visitor sign-in — these often join the main vertical. Adding one later: re-run with the extra name.
+| `forms` | any visitor-fillable form: contact, signup, waitlist, application, survey, quote request (an event RSVP is `events`; a per-service booking form is `bookings`) |
+| `cms` | structured content the app reads back — galleries, listings, "my submissions" (a visitor-fillable form is `forms`) |
 
 ```js
 const { execSync } = require('child_process');
 const { existsSync, readdirSync } = require('fs');
-const VERTICALS = ['storefront'];        // ← set from the prompt; list every vertical the app uses
-// const VERTICALS = ['members', 'cms']; // ← e.g. visitors sign in AND the app stores what they submit
-// COPY these two straight from the prompt — deploy writes them into src/rest/wix-config.js, so never
-// retype either one into a file by hand afterwards.
-const WIX_CLIENT_ID = '<client id from the prompt>';
+const VERTICALS = ['storefront'];         // ← set from the prompt; list every vertical the app uses (e.g. ['members','cms'])
+const WIX_CLIENT_ID = '<client id from the prompt>';   // copy both from the prompt — deploy writes them into src/rest/wix-config.js
 const WIX_METASITE_ID = '<site id from the prompt>';
 const results = {};
-for (const skill of ['wix-vibe-headless', 'wix-docs']) {
+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`,
@@ -90,63 +83,35 @@ truth for how the client is built.
 
 **REST scaffolds + `wix-config.js` are already in `src/rest/`** (STEP 1 wrote them). Some verticals also ship 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.
 
+**⚠️ `forms` is the ONE vertical that does NOT run in parallel with STEP 4** — its UI is gated on a
+file the seed writes. Read its `INSTRUCTIONS.md` **Prerequisites** before building any form UI; seed
+it first (STEP 4) and build the rest of the app meanwhile.
+
 **`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 4 — Manage and seed the business
 
-**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 your vertical's ready-made seed module — read
-`.agents/skills/wix-vibe-headless/references/<vertical>/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 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."*).
+`.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.
+Seeding is **admin-only** — not part of the client, which is built solely per the `wix-vibe-headless` skill.
 
-**Entity images.** For image-bearing entities (store products, blog covers, bookings services,
-restaurant items, portfolio projects, event heroes, CMS items), generate with **Base44's built-in
-image generation**, then attach via the vertical seed module's image-attach step — `wix-docs` if the
-module doesn't cover that entity.
-
-**Seed images with the FINAL url, in one call.** Seeding writes to Wix, so use the real
-`https://media.base44.com/...` url from the **completed** `generate_image` result and pass it straight
-into your single `setupStore`/seed 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.
-
-The connector + seeding are **admin-only** (STEP 4) — **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.
+- Inline in exec_tool, `base44` is already declared — use it directly; do **not** `import @base44/sdk`, re-declare it, or call `createClient()` (throws *"Identifier 'base44' has already been declared."*).
 
 ## STEP 5 — Wrap up
 
-Once the site is built and seeded:
-
-1. **Mount the preview-only manage banner** (required; links the app to its Wix back office; shipped,
-   self-gates to the preview, never on the published site): render the `<WixManageBanner/>` component
-   in your Layout's fixed top region, above the header, per your vertical's INSTRUCTIONS STEP 4.
-2. **Ask the user to open** `https://manage.wix.com/dashboard/{metaSiteId}` (substitute your
-   metasite id) to complete setup in Wix (required), and mention that the preview shows a dismissible
-   top banner linking to this same dashboard.
+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.
 
-**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, re-seed, or debug image urls.** Leave them and finish.
+**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-docs` — all over the connector.
+`wix-base44-connector` doc discovery — all over the connector.
 
-version: v1338
+version: v1341

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

@@ -27,7 +27,7 @@ Everything is under `.agents/skills/wix-vibe-headless/references/`.
 - `INSTRUCTIONS.md` — the vertical's build guide + field-shape snippets; `seed/SEED.md` — how the seed
   module is run.
 
-**The nine verticals — data layer (`app/rest/`) + seed module (`seed/`):**
+**The verticals — data layer (`app/rest/`) + seed module (`seed/`):**
 
 | vertical | `app/rest/` data layer | seed module |
 |---|---|---|
@@ -37,7 +37,8 @@ Everything is under `.agents/skills/wix-vibe-headless/references/`.
 | events | `wix-events-browse.js`, `wix-events-registration.js` — events & categories; RSVP / ticketing + checkout | `seed-events.js` |
 | portfolio | `wix-portfolio.js` — collections, projects, galleries | `seed-portfolio.js` |
 | restaurants | `wix-restaurants-menu.js`, `-ordering.js`, `-reservations.js` — menu; online ordering; table reservations | `seed-restaurants.js` |
-| cms | `wix-cms.js` — Wix Data collections: list / detail / filter + form CRUD | `seed-cms.js` |
+| forms | `wix-forms.js`, `wix-forms-submissions.js` — any visitor-fillable form: read the schema; upload attachments, create a submission (schema accessors ship alongside in `lib/wix-form-schema-utils.js`) | *(none — REST shapes in `seed/SEED.md`)* |
+| cms | `wix-cms.js` — Wix Data collections: list / detail / filter | `seed-cms.js` |
 | pricing-plans | `wix-pricing-plans.js` — plans list + subscribe/checkout | `seed-pricing-plans.js` |
 | members | `wix-members-auth.js` — custom login/signup (email+password, social, SSO), session, account | *(none — members sign up at runtime; nothing to seed)* |
 
@@ -49,7 +50,9 @@ the token set) is **universal — follow it as-is**.
 
 ## The flow — install → build client → seed → done
 
-Run **build the client** (step 2) and **seed** (step 3) in parallel; parallelize independent work within each.
+Run **build the client** (step 2) and **seed** (step 3) in parallel; parallelize independent work
+within each. **One exception — `forms` must be seeded before its UI is built; read that gate in
+`references/forms/INSTRUCTIONS.md` (Prerequisites) first.** Everything else still parallelizes.
 
 ### 1 · Install the skills
 

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

@@ -165,6 +165,8 @@ stale render.
 ## Using the client from your own UI
 The two shipped hooks are the whole flow. If you build a custom surface, drive it the same way:
 
+> Migrating from Cart V1 / Checkout V1? These helpers are V2-only — see the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide) for the before/after.
+
 ```jsx
 // LIST — every list helper returns an OBJECT, not a bare array. Destructure it:
 const { services, total, nextOffset } = await queryServices({ limit: 24 });   // total 0 → empty state
@@ -223,6 +225,49 @@ the areas they sit in:
 - eCommerce checkout (paid bookings): https://dev.wix.com/docs/api-reference/business-solutions/e-commerce.md
 - Headless redirect session (hosted checkout): https://dev.wix.com/docs/api-reference/business-management/headless/redirects.md
 
+## Rentals — the same client, one extra step
+
+**Wix Rentals has no APIs of its own.** A rental is a Bookings *service* with rentals-specific
+field values, so this whole client works on it: the catalog read, the booking form, and the
+`createBooking → cart → checkout` chain are all unchanged. `rest/wix-bookings-rentals.js` and
+`hooks/useRentalDuration.js` carry the only differences.
+
+**What tells a rental apart — the DATA, never the brief.** A service carries either a fixed
+session length or a duration RANGE the customer picks within; the two are mutually exclusive:
+
+```js
+import { isRental, rentalDuration, rentalRateLabel } from "@/rest/wix-bookings-rentals";
+isRental(service)   // true only when schedule.availabilityConstraints.durationRange is present
+```
+
+A 60-minute yoga class and a 60-minute massage are **not** rentals even though a massage is
+`type: "APPOINTMENT"` exactly like a rental is. Never branch on the service's name, its
+category, or what the brief called it.
+
+**The extra step.** An ordinary service is one choice (a slot). A rental is two: pick a START,
+then pick HOW LONG — and the price follows the length.
+
+```jsx
+const detail = useServiceDetail(serviceId);                        // service + start times
+const rental = useRentalDuration(detail.service, detail.selectedSlot, detail.timeZone);
+
+<SlotPicker … />                                                   {/* pick a start, as ever */}
+{rental.isRental && <RentalDurationPicker rental={rental} />}      {/* then pick a length */}
+```
+
+Book with `rental.endDate` as the slot's `localEndDate`; everything else in the booking call is
+identical.
+
+**Hard rules on top of the ones below:**
+
+- **Filter every catalog read by `appId`.** `queryRentals()` does it. On a site with both apps
+  an unfiltered `queryServices` returns haircuts next to meeting rooms.
+- **Never compute the total yourself.** A rental is charged as a rate, hourly at per-minute
+  granularity — 90 minutes of a $10/hour room is $15. `useRentalDuration` prices the chosen
+  length on the server; multiplying the displayed rate disagrees with checkout.
+- **Show the total before the customer commits.** A rate alone is not a price.
+- **One unit type per service.** A room rented by the hour *and* by the day is two services.
+
 ## Hard rules
 - Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
 - Header/footer live in a `Layout` around `<Outlet/>` (STEP 3) — never edit the shipped