@wix/agent-skills 1.16.3 → 1.17.0

package/skills/wix-manage/references/seo/manage-url-redirects.md

@@ -0,0 +1,250 @@
+---
+name: "Manage URL Redirects on a Wix Site"
+description: "Retrieve, create, and delete URL redirects on a Wix site using the public SEO Redirects API. Covers exact and group redirects, language-scoped redirects for multilingual sites, batches of up to 500, and the change flow for a redirect that already exists. This API has no query, search, or update method: List Redirects is the only read-many. Redirects do not chain, so creating one that points at a path another redirect starts from permanently deletes that other redirect; list and check before every write."
+---
+
+# Manage URL Redirects on a Wix Site
+
+Use the public **SEO Redirects API** to manage where a Wix site sends visitors who
+request an old or moved URL. The API selects the site from the caller's
+authorization context.
+
+If the run already identifies a site - one connected site, or a site ID supplied
+by the environment - use it and continue. Ask which site only when several are
+available and nothing in the request or the context picks one. Do not stop to ask
+for a site ID the API never takes.
+
+A redirect returns a 301 permanent redirect, takes effect on the live site
+immediately with no site publish, and **takes precedence over a real page at the
+same path**. Creating a redirect from a path that still serves a page makes that
+page unreachable until the redirect is deleted.
+
+## Redirects do not chain, they replace
+
+This is the single most important thing to know, and it is not what most agents
+assume. If an existing redirect **starts at** the path your new redirect points
+to, the two do not form a chain. The existing one is **deleted**, and your create
+proceeds.
+
+So with `/blog` -> `/news` already on the site, creating `/old-blog` -> `/blog`
+does **not** produce `/old-blog` -> `/blog` -> `/news`. It produces
+`/old-blog` -> `/blog`, and `/blog` -> `/news` is gone for good. Never describe
+the result as a chain, a hop, or a redirect sequence.
+
+## Run this check before every create
+
+Do not skip it because the user's request was explicit. The user asking for a
+redirect is not the same as the user agreeing to lose a different one.
+
+1. Call **List Redirects**.
+2. Compare the redirect you are about to create against every existing one:
+   - an existing redirect whose `from` equals your new `to` **will be deleted**
+     (loop resolution, described above);
+   - an existing redirect whose `from` equals your new `from` means your create
+     **fails** with `FROM_URL_EXISTS` and writes nothing.
+   - Paths differing only by a trailing slash count as equal for both checks.
+3. **If either matched, end your turn without writing.** Name the exact redirect
+   at stake and what happens to it, then stop and wait for the user's answer.
+
+   This is a rule about turn structure, not about intent: **never put a create in
+   the same response as the List Redirects that found the conflict.** Reporting
+   the conflict and creating the redirect anyway is the failure this rule exists
+   to prevent - the user cannot answer a question you already acted on. If your
+   next action after listing is a write, you have skipped this step.
+4. If neither matched, no deletion is possible: create it in the same turn and
+   report the result. Do not ask permission you do not need.
+
+`options.forceReplace` is the only way to overwrite a taken `from` path, and it
+**deletes** the redirect holding it. Never set it on your own initiative. Offer it
+only after reporting the conflict, and only if the user asks to replace.
+
+## The six methods and their request shapes
+
+Every path is under `https://www.wixapis.com/seo-redirects-service/v1`. Use these
+directly - do not go looking for the shapes in the docs first.
+
+| Method | Call |
+|---|---|
+| List Redirects | `GET /redirects` - no body, no parameters |
+| Get Redirect | `GET /redirects/{redirectId}` |
+| Create Redirect | `POST /create-redirect` - body below |
+| Delete Redirect | `DELETE /redirects/{redirectId}` - empty response |
+| Bulk Create Redirects | `POST /bulk/redirects/create` |
+| Bulk Delete Redirects | `POST /bulk/redirects/delete` |
+
+Create Redirect takes the redirect nested under `redirect`. `options` and
+`language` are optional, `id` only when preserving an existing redirect's
+identity:
+
+```json
+{
+  "redirect": {
+    "from": "/old-blog",
+    "to": "/blog",
+    "options": { "groupRedirect": true },
+    "language": "fr"
+  }
+}
+```
+
+The two bulk methods take flat lists. Bulk Create's `returnFullEntity` returns
+each created redirect in `results[].item`:
+
+```json
+{ "redirects": [ { "from": "/old-pricing", "to": "/pricing" } ], "returnFullEntity": true }
+```
+
+```json
+{ "redirectIds": ["5b07d9de-6a9f-494d-8066-a7b66c970270"] }
+```
+
+## Worked example: the request that deletes something
+
+The user asks to send `/old-blog` and everything under it to `/blog`.
+
+**1. List first.**
+
+```
+GET https://www.wixapis.com/seo-redirects-service/v1/redirects
+```
+
+```json
+{
+  "redirects": [
+    {
+      "id": "583fe7d7-2944-436f-870a-09eb6d2e52fa",
+      "from": "/blog",
+      "to": "/news",
+      "createdDate": "2026-08-20T09:12:44.000Z"
+    }
+  ]
+}
+```
+
+**2. Compare.** The new `to` is `/blog`, and an existing redirect's `from` is
+`/blog`. That is the deletion case. **End the turn here** - report that creating
+this redirect deletes `/blog` -> `/news` permanently, and that the two will not
+chain, then wait.
+
+**3. Only after the user agrees**, create it:
+
+```
+POST https://www.wixapis.com/seo-redirects-service/v1/create-redirect
+```
+
+```json
+{ "redirect": { "from": "/old-blog", "to": "/blog", "options": { "groupRedirect": true } } }
+```
+
+```json
+{
+  "redirect": {
+    "id": "9c4a1f2e-77b0-4b13-a2c8-6e0d3f5b8a91",
+    "from": "/old-blog",
+    "to": "/blog",
+    "options": { "groupRedirect": true }
+  }
+}
+```
+
+`/blog` -> `/news` is now gone. Say so - do not report it as still in place, and
+do not describe the result as `/old-blog` -> `/blog` -> `/news`.
+
+## When a write fails
+
+Report the failure and stop. Do **not** retry with a different request shape, a
+different path, `forceReplace` added, or a bulk call in place of a single one. A
+failed create wrote nothing, so there is nothing to clean up, and a mutated retry
+is a second attempt at a decision the user has not agreed to.
+
+On the first `403` or `PERMISSION_DENIED`, stop and report the missing
+authorization for managing SEO settings. Do not try another site, path, or method.
+
+## Choose exact or group
+
+| User intent | Setting |
+|---|---|
+| "Redirect this one URL" | omit `options`, or `options.groupRedirect: false` |
+| "Redirect this section", "everything under /blog" | `options.groupRedirect: true` |
+
+A group redirect carries the rest of the URL over to the target: from
+`/forum/questions/` to `/forum/faqs/` sends `/forum/questions/my-post` to
+`/forum/faqs/my-post`. An exact and a group redirect that share a `from` path are
+two different redirects.
+
+For a multilingual site, set `language` to apply the redirect to one language
+only; omit it to apply to every language. A language-scoped path is stored
+**without** the language prefix, so `/fr/about` with `language: "fr"` comes back
+as `/about`. Deleting a language-scoped redirect stops it working but it can
+still appear in List Redirects.
+
+`from` cannot be the site root, and two paths differing only by a trailing slash
+count as the same path.
+
+## Read: List Redirects is the only way to read many
+
+**There is no query endpoint and no search endpoint.** Most Wix APIs have one, so
+this is the second place an agent goes wrong. Do not call, construct, or go
+looking for `POST /v1/redirects/query`, a `/search` path, or any filtered variant:
+they do not exist, and trying one wastes a turn and returns nothing useful.
+
+- **List Redirects** returns every redirect on the site in one response. It takes
+  no filter, sort, cursor, or paging parameter at all. Filter, sort, and slice the
+  returned array yourself. It also returns redirects Wix created for the site
+  owner, such as when a page's URL slug was renamed in the editor.
+- **Get Redirect** retrieves one by ID.
+
+## Change an existing redirect
+
+There is **no update method**, and as above no query method. To change a redirect:
+
+1. Call **Get Redirect** and keep the whole response.
+2. Call **Delete Redirect** with the same ID.
+3. Call **Create Redirect** with every field you retrieved, with your change applied.
+
+Carry the whole redirect across, not only what changed. Create Redirect fills an
+omitted field with its default rather than the previous value, so dropping
+`options` turns a group redirect into an exact one and dropping `language` turns a
+language-scoped redirect into a global one. Keep `id` to preserve the redirect's
+identity, or omit it for a new one.
+
+Confirm with the user before step 2: between the delete and the create the
+redirect is not in effect, and if the create fails the old redirect is gone.
+
+## Batches
+
+**Bulk Create Redirects** and **Bulk Delete Redirects** take 1 to 500 items and
+report each one separately **inside a successful response**:
+
+- Read every outcome from `results[].itemMetadata`, matched to your request by
+  `originalIndex`. A failed item carries `error.code`, such as `FROM_URL_EXISTS`
+  or `REDIRECT_NOT_FOUND`.
+- `bulkActionMetadata.undetailedFailures` counts items whose outcome is
+  **unknown**: they carry no error and may or may not have been written. Call
+  List Redirects to find out. Never report them as successes.
+- A malformed request, such as an empty list, is rejected as a whole with a 400
+  and returns no per-item results.
+
+Two more sharp edges to report truthfully:
+
+- A successful **Bulk Delete** item means the deletion was found and sent, not
+  confirmed. Call List Redirects if the user needs confirmation.
+- Bulk Create is **not atomic**. If an item's conflicting or loop-causing
+  redirect is deleted and the write then fails, the deleted redirect is gone and
+  nothing replaces it. Repeating the same request recreates it.
+
+Creating a redirect identical to one already on the site changes nothing and
+succeeds: Create Redirect echoes the request back without an `id` or
+`createdDate`, and Bulk Create reports success with no `id`. Do not present that
+as a newly created redirect.
+
+## Reading errors
+
+- On a 400, read `details.validationError.fieldViolations` and report the named
+  field rather than guessing.
+- **Known divergence:** the reference documents `REDIRECT_NOT_FOUND` for an
+  unknown redirect ID on Get Redirect and Delete Redirect. The API currently
+  returns a generic 404 without that code. Treat any 404 on those two methods as
+  "no redirect with that ID", and do not tell the user the ID was valid.
+- No webhook or event is emitted when a redirect is created or deleted. Never
+  treat the absence of an event as the absence of a change.

package/skills/wix-manage/references/sites/query-sites.md

@@ -1,173 +1,58 @@
 ---
 name: "Query Sites"
-description: Lists and queries all sites associated with a Wix account using the Sites API. Covers filtering, sorting, and cursor-based pagination.
+description: List, count, and find the sites in a Wix account. Covers the namespace filter for headless sites, counting before enumerating, cursor pagination, and resolving a site by name.
 ---
 # Query Sites
 
-This recipe demonstrates how to list and query the sites associated with a Wix account.
+List, count, and find the sites in a Wix account.
 
-## Prerequisites
+- **Auth**: account-level (a Wix user token, or an account-level API key). `wix token` prints one.
+- **Permission**: `SITE_LIST.READ` (scope `SCOPE.ACC-DC-OS.READ-SITE`).
+- **Endpoints**: list `POST https://www.wixapis.com/site-list/v2/sites/query` · count
+  `POST https://www.wixapis.com/site-list/v2/sites/count`.
 
-- Account-level API access (authenticated as a Wix user or using an account-level API key)
-- Permission `SITE_LIST.READ` (scope `SCOPE.ACC-DC-OS.READ-SITE`)
+## Include headless sites — filter by `namespace`
 
-## Required APIs
+Both endpoints see only `WIX`-namespace sites by default; **headless sites** (anything built on a
+connected OAuth app) are silently excluded. Filter on both namespaces to see everything:
 
-- **Query Sites API**: [REST](https://dev.wix.com/docs/api-reference/account-level/sites/sites/query-sites)
-
-> Returns up to **100** sites per request. Use cursor paging (below) to retrieve more.
-
----
-
-## Query Sites
-
-**Endpoint**: `POST https://www.wixapis.com/site-list/v2/sites/query`
-
-The request takes a `query` object that supports `filter`, `sort`, and `cursorPaging`.
-
-**Request Body**:
-```json
-{
-  "query": {
-    "filter": { "editorType": "EDITOR" },
-    "sort": [{ "fieldName": "createdDate", "order": "ASC" }],
-    "cursorPaging": { "limit": 50 }
-  }
-}
-```
-
-All three fields are optional — `{ "query": { "cursorPaging": { "limit": 50 } } }` lists every site.
-
-**Request**:
 ```bash
-curl -X POST \
-  'https://www.wixapis.com/site-list/v2/sites/query' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "query": {
-      "filter": { "editorType": "EDITOR" },
-      "sort": [{ "fieldName": "createdDate", "order": "ASC" }],
-      "cursorPaging": { "limit": 50 }
-    }
-  }'
-```
-
----
-
-## Response Structure
-
-The response has the sites array plus **two** paging objects: a top-level `cursorPaging`
-(echoes the applied limit and the next cursor) and `metadata` (count, `cursors.next`, `hasNext`).
-
-> ⚠️ There is **no** `pagingMetadata` field. Read paging info from `metadata`.
-
-```json
-{
-  "sites": [
-    {
-      "id": "f6061c5f-6aa3-42f8-8822-36a4981dabb2",
-      "htmlAppId": "70df538d-906c-44ca-9f27-c186b62f2b2b",
-      "name": "my-site-47",
-      "displayName": "My Site 47",
-      "createdDate": "2023-02-01T14:56:09.831Z",
-      "updatedDate": "2026-06-22T03:55:49.031Z",
-      "published": true,
-      "premium": false,
-      "viewUrl": "https://username.wixsite.com/my-site-47",
-      "editUrl": "/editor/f6061c5f-6aa3-42f8-8822-36a4981dabb2?editorSessionId=...",
-      "thumbnail": "/site-thumbnail/f6061c5f-6aa3-42f8-8822-36a4981dabb2",
-      "ownerAccountId": "e6a89eda-d100-4b2d-8a47-3040e2134497",
-      "contributorAccountIds": [],
-      "editorType": "EDITOR",
-      "blocked": false,
-      "namespace": "WIX",
-      "domainConnected": false,
-      "parentChildRole": "NONE"
-    }
-  ],
-  "cursorPaging": {
-    "limit": 50,
-    "cursor": "<cursor-for-next-page>"
-  },
-  "metadata": {
-    "count": 50,
-    "cursors": {
-      "next": "<cursor-for-next-page>"
-    },
-    "hasNext": true
-  }
-}
+curl -X POST 'https://www.wixapis.com/site-list/v2/sites/query' \
+  -H 'Authorization: <ACCOUNT_TOKEN>' -H 'Content-Type: application/json' \
+  -d '{ "query": { "filter": { "namespace": { "$in": ["WIX", "HEADLESS"] } }, "cursorPaging": { "limit": 100 } } }'
 ```
 
-### Site object fields
-
-Each entry in `sites` has these fields (from the `Site` schema):
-
-| Field | Type | Notes |
-|---|---|---|
-| `id` | string | Site ID — use for site-level API calls |
-| `htmlAppId` | string | Internal HTML app ID |
-| `name` | string | URL slug / internal name |
-| `displayName` | string | Human-readable site name |
-| `createdDate` / `updatedDate` | datetime | |
-| `trashedDate` | datetime | Present only if the site is in the trash |
-| `published` | boolean | Whether the site is published |
-| `premium` | boolean | Whether the site has a Wix Premium (paid) plan |
-| `viewUrl` | string | Public site address; empty string when unpublished. **There is no `siteUrl` field.** |
-| `editUrl` | string | Relative editor path; prefix with `https://manage.wix.com` to open |
-| `thumbnail` | string | Relative thumbnail path |
-| `ownerAccountId` | string | |
-| `contributorAccountIds` | string[] | |
-| `editorType` | string | e.g. `EDITOR`, `ODEDITOR` — also a valid `filter` field |
-| `blocked` | boolean | |
-| `folderId` / `parentId` | string | Set for sites organized in folders / parent-child setups |
-| `namespace` | string | e.g. `WIX` |
-| `domainConnected` | boolean | |
-| `parentChildRole` | string | e.g. `NONE` |
+`query` takes optional `filter`, `sort` (e.g. `[{ "fieldName": "createdDate", "order": "DESC" }]`),
+and `cursorPaging` (max `limit` 100).
 
----
+## Count before you enumerate
 
-## Pagination
+An account can hold thousands of sites. To find one by name, search (see "Find a site by name")
+rather than enumerate. To walk the whole list, count first and decide whether that's worth it:
 
-Cursor-based. Read the next cursor from `metadata.cursors.next` and stop when
-`metadata.hasNext` is `false`.
+```bash
+curl -X POST 'https://www.wixapis.com/site-list/v2/sites/count' \
+  -H 'Authorization: <ACCOUNT_TOKEN>' -H 'Content-Type: application/json' \
+  -d '{ "filter": { "namespace": { "$in": ["WIX", "HEADLESS"] } } }'   # → { "count": 1335 }
+```
 
-> The cursor does **not** carry the page limit, and it already encodes the filter/sort
-> from the first request. On follow-up pages send **only** the cursor (plus `limit` if you
-> want a non-default page size) — do **not** repeat `filter` or `sort`.
+Enumerating costs **~0.7s per 100 sites** (100 → ~0.7s, 500 → ~3.4s, ~1,300 → ~9s). For a large
+count, render the first N sites with a "…and N more" note instead of fetching all of them.
 
-**First request**:
-```json
-{
-  "query": {
-    "filter": { "editorType": "EDITOR" },
-    "sort": [{ "fieldName": "createdDate", "order": "ASC" }],
-    "cursorPaging": { "limit": 50 }
-  }
-}
-```
+## Paginate
 
-**Next page** (cursor from `metadata.cursors.next`):
-```json
-{
-  "query": {
-    "cursorPaging": {
-      "limit": 50,
-      "cursor": "<metadata.cursors.next from previous response>"
-    }
-  }
-}
-```
+The next cursor is at `metadata.cursors.next` (there is **no** `pagingMetadata` field); it already
+encodes the filter/sort, so follow-up pages send only the cursor:
 
-**Loop**:
 ```javascript
-async function listAllSites() {
+async function listAllSites(wixPost) {
   const sites = [];
   let cursor = null;
   do {
-    const cursorPaging = cursor ? { limit: 100, cursor } : { limit: 100 };
-    const res = await wixRequest({ query: { cursorPaging } }); // POST .../site-list/v2/sites/query
+    const query = cursor
+      ? { cursorPaging: { limit: 100, cursor } }
+      : { filter: { namespace: { $in: ["WIX", "HEADLESS"] } }, cursorPaging: { limit: 100 } };
+    const res = await wixPost("/site-list/v2/sites/query", { query });
     sites.push(...res.sites);
     cursor = res.metadata.hasNext ? res.metadata.cursors.next : null;
   } while (cursor);
@@ -175,23 +60,49 @@ async function listAllSites() {
 }
 ```
 
----
-
-## Common Use Cases
+## Find a site by name
 
-### List all sites
-Omit `filter` and page through with `cursorPaging` until `metadata.hasNext` is `false`.
+Substring-search by display name with `GET manage.wix.com/account/sites/api/sites/search`. It
+returns full site records (headless included) and, with `getCount=true`, the total:
 
-### Find a specific site
-Prefer server-side `filter` (e.g. `{ "editorType": "EDITOR" }`) and `sort` over fetching
-everything and filtering client-side. Filterable fields match the site object (e.g. `name`,
-`displayName`, `editorType`, `published`).
+```bash
+curl 'https://manage.wix.com/account/sites/api/sites/search?query=kintsugi&getCount=true' \
+  -H 'Authorization: <ACCOUNT_TOKEN>' -H 'accept: application/json'
+# → { "sites": [ { "metaSiteId", "displayName", "namespace", "published", "editUrl", … } ], "totalCount": 5 }
+```
 
----
+## Response — the `Site` object
+
+`sites` is an array of:
+
+```typescript
+interface Site {
+  id: string;                 // site ID — use for site-level API calls
+  htmlAppId: string;
+  name: string;               // URL slug / internal name; opaque `headless-<id>` for headless sites
+  displayName: string;        // human-readable name
+  createdDate: string;        // ISO datetime
+  updatedDate: string;        // ISO datetime
+  trashedDate?: string;       // present only when the site is in the trash
+  published: boolean;
+  premium: boolean;           // has a Wix Premium (paid) plan
+  viewUrl: string;            // public address; "" when unpublished (there is no `siteUrl` field)
+  editUrl: string;            // relative; prefix with https://manage.wix.com to open
+  thumbnail: string;
+  ownerAccountId: string;
+  contributorAccountIds: string[];
+  editorType: string;         // EDITOR | ODEDITOR | STUDIO | EDITORLESS
+  blocked: boolean;
+  folderId?: string;          // set for sites organized in folders / parent-child setups
+  namespace: string;          // WIX | HEADLESS
+  domainConnected: boolean;
+  parentChildRole: string;    // e.g. NONE
+}
+```
 
 ## Next Steps
 
-After finding a site:
-- Use the site `id` for site-level API calls
-- Create new sites using [Create Site from Template](create-site-from-template.md)
-- Manage site settings and content
+Use a site's `id` for site-level API calls — derive a site token from the account token
+(`wix token --site <id>`, or the `oauth2/token` refresh-grant in wix-auth `device-flow`), then read
+its context via [Read Site Context](read-site-context.md) or create sites with
+[Create Site from Template](create-site-from-template.md).

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/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`
@@ -101,4 +105,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`,
@@ -71,4 +74,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.