@wix/agent-skills 1.18.1 → 1.19.0

package/skills/wix-manage/references/seo/manage-content-plan.md

@@ -0,0 +1,247 @@
+---
+name: "Generate and Read a Wix Site's Content Plan"
+description: Generate an SEO content plan and read its blog post topics, or troubleshoot an existing content plan flow stuck at KEYWORD_RESEARCH while polling GetContentPlanFlow. Use this recipe for both generation and stalled-flow questions: it explains the intentional pause, the Create Content Plan release request, missing flow IDs, and the exact public API paths and response fields.
+---
+
+# Generate and Read a Wix Site's Content Plan
+
+## Choose the request path before calling an API
+
+For a request to **generate a new plan**, follow the generation sequence below.
+For a request about an **existing flow**, use this branch instead; do not start
+the generation sequence or make a discovery call to look for the flow.
+
+`KEYWORD_RESEARCH` is an intentional pause, even after ten minutes. Explain
+that Create Content Plan (step 3) releases the existing flow; do not cancel it
+or trigger a replacement just because it is parked.
+First check whether the conversation or a prior response contains the actual
+`contentPlanFlowId`:
+
+- **Missing ID:** Explain the intentional pause and ask for the existing flow
+  ID. End the turn without making a status or release call. You can name the
+  release endpoint, `POST https://www.wixapis.com/promote/seo/v1/create-content-plan`,
+  but do not execute an example request. Placeholder text such as
+  `<YOUR_FLOW_ID>` is never an API argument.
+- **Known ID:** Use that actual flow UUID in the step 3 request's
+  `contentPlanFlowId` field to release the existing flow when requested.
+
+For example, when the user reports a flow parked at `KEYWORD_RESEARCH` but
+provides only a site ID, the next action is a reply, not an API call:
+
+> That status is an intentional pause. Create Content Plan releases the
+> existing flow. Please send the content plan flow ID from your trigger or
+> status response so I can use it in the release request.
+
+The user's reported status is enough to explain the pause; checking it first
+requires the very flow ID that is missing. A site ID is not a flow ID, even
+though both have UUID format.
+Do not guess a collection endpoint to discover the active flow.
+
+The complete status URL is
+`https://www.wixapis.com/promote/seo/v1/content-plan-flows/{contentPlanFlowId}`.
+Use this exact public base path and substitute the known ID. Do not call
+`GET /content-plan-flows` without an ID or construct a URL from a service name.
+
+Trigger, poll, release, poll, read. That is the full loop. The API is
+asynchronous — generation takes minutes — and the flow **parks at
+`KEYWORD_RESEARCH` until you explicitly release it**.
+
+All paths are relative to `https://www.wixapis.com/promote/seo/v1`.
+The API selects the site from the caller's authorization context.
+Writing requires the **Manage SEO Settings** permission.
+
+For a generation request, the only writes in this workflow are Trigger and
+Create Content Plan. Do not update the site's business profile, name,
+description, categories, or publication state to try to accelerate generation.
+Those are separate tasks requiring the user's actual data and authorization.
+`CREATED` can persist while work is queued; it does not justify setup changes
+or extra discovery calls. Continue checking the same flow without modifying
+the site.
+
+Keep every call scoped to the site the user selected. If site context cannot
+be resolved, report the lookup failure and request clarification; do not
+substitute another available site or change its business information. Missing
+context is not proof that the selected site does not exist or belongs to a
+different account. Say that its context could not be retrieved; do not claim
+that the user's site ID is invalid or offer replacement sites. Likewise, unmet
+prerequisites do not authorize switching sites or inventing business data.
+
+## Polling without losing progress
+
+Treat each numbered step below as a separate API execution, not sections of
+one script. Even a loop capped at 60 polls can outlive the execution timeout
+and lose the returned flow ID. A polling script must issue one GET and return
+`{ contentPlanFlowId, status }` immediately; decide the next action after that
+response. Never embed the trigger, polling loops, release, and candidate read
+in a single execution. Trigger and release are mutations: if the client asks
+whether an execution changes data, identify them as writes, not read-only.
+
+Generation waits on an external process. Do not put the entire generation in
+one long-running function, an unbounded `while` loop, or a busy-wait. Trigger
+once and return the flow ID immediately. Use separate, bounded status checks
+for the same ID so each response is visible and you can act on its status.
+A status check is one GET, not a loop that waits for a terminal state.
+Use the client's supported waiting mechanism between checks; do not assume
+that timers or sleep functions exist inside an API execution sandbox.
+
+Continue across status checks while the flow is progressing. At
+`KEYWORD_RESEARCH`, release it immediately once, then keep checking that same
+flow until `SUCCESS` and read its candidates. Do not keep polling the parked
+state instead of releasing it, or stop with only a promise to finish later.
+If the client cannot continue waiting, report the flow ID and last observed
+status honestly; that is an incomplete generation, not success.
+
+## The exact call sequence
+
+### 1. Trigger
+
+```
+POST /content-plan-flows/trigger
+{}
+```
+
+Returns `{ "contentPlanFlowId": "..." }`. Return this response and end this
+execution here. Save the ID in the conversation before making any status
+request. Do not append step 2 to the trigger script.
+
+### 2. Poll until KEYWORD_RESEARCH
+
+```
+GET /content-plan-flows/{contentPlanFlowId}
+```
+
+Execute this GET once and return its response. This execution contains no
+`for`/`while` loop and no timer. Repeat it as a separate call when another
+status check is needed. Keep the response compact: flow ID and status suffice.
+
+The response is `{ "contentPlanFlow": { "id": "...", "status": "..." } }`.
+Read `contentPlanFlow.status`, not a top-level `status`. A missing status is a
+response-shape problem: inspect the response instead of silently looping.
+`CREATED` alone does not identify a missing prerequisite. If the flow remains
+there without progressing, report the stalled flow ID and observed status; do
+not invent a missing business category or description.
+Always send the trigger's ID when following this generation. The documented
+omitted-ID behavior selects a previous successful flow, not the active flow;
+it is not a way to discover the ID of a parked flow.
+See [Get Content Plan Flow](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-content-plan-flow-v1/get-content-plan-flow).
+
+Typical status progression: `CREATED` → `SITE_ANALYSIS` → `KEYWORD_RESEARCH`. Check every
+few seconds using the bounded approach above. Completion time varies.
+
+**Stop polling and act on these terminal states:**
+- `PENDING_REQUIREMENTS` — the site has unmet prerequisites, such as missing
+  business location information. Identify the actual missing prerequisite from
+  available evidence; do not assume category or description is the cause.
+  Report what needs completing and do not repeatedly trigger new flows.
+- `FAIL` — the pipeline failed. Trigger a new flow to retry.
+- `CANCELED` — someone canceled the flow.
+
+### 3. Release the flow
+
+```
+POST /create-content-plan
+{ "contentPlanFlowId": "..." }
+```
+
+This advances the flow past `KEYWORD_RESEARCH`. Check `success` in the
+response. If `false`, read `message`.
+
+**Without this call the flow waits forever.**
+
+### 4. Poll until SUCCESS
+
+Same single-GET execution as step 2, returning after each check. Status walks
+`CONTENT_PLAN` → `SUCCESS`. Read candidates in a subsequent execution after
+observing `SUCCESS`.
+
+### 5. Read the briefs
+
+```
+GET /content-plan-flows/{contentPlanFlowId}/blog-post-candidates
+```
+
+Returns `{ "blogPostCandidates": [...] }`. Each candidate's brief fields are
+nested under `briefData`, not at the candidate's top level. Map them directly:
+
+```js
+const topics = response.blogPostCandidates.map(candidate => ({
+  id: candidate.id,
+  title: candidate.briefData?.h1Title,
+  keyword: candidate.briefData?.keyword,
+  mainKeyword: candidate.briefData?.mainKeyword,
+  supportingPageUrl: candidate.briefData?.pageUrl
+}));
+```
+
+`pageUrl` identifies the existing site page the proposed post supports; it is
+not the URL of a newly published blog post. Generation creates briefs, not
+published posts. Do not read `candidate.title`, `candidate.keyword`, or
+`candidate.pageUrl`, or infer missing data from those nonexistent top-level
+fields. If a nested field is absent, report it as unavailable and inspect the
+raw candidate before making another request. Report the actual returned
+titles and available keywords/supporting page URLs. Do not invent briefs or
+claim completion from the release response.
+See [List Blog Post Candidates](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-blog-post-candidate-v1/list-blog-post-candidates).
+
+### Present the result
+
+Start with the flow ID, observed `SUCCESS` status, and returned candidate count.
+Use a compact table with one row per topic: suggested title, target keyword,
+main keyword, and supporting page URL. Include the actual returned URL as a
+link; do not merely say that each brief contains a URL. Avoid repeating SEO
+titles and descriptions unless requested. If the answer must be shortened,
+label the displayed subset and total explicitly instead of claiming to show all
+topics. These are AI-generated suggestions; do not promise rankings or traffic.
+Assess the returned topics before recommending them: if they are repetitive,
+mostly restate the site name, or lack a clear connection to the site's business,
+say so plainly. Successful generation does not establish editorial quality.
+Still show the actual results; do not silently replace weak titles with invented
+ones or call them optimized without evidence. Explain what business context
+would help assess or refine them, without modifying the site's settings.
+
+## Editing keywords (optional)
+
+After step 2, before or after step 3, read the keywords:
+
+```
+GET /content-plan-keyword-research-items
+```
+
+Edit one keyword (field-masked, only `keyword` and `main_keyword` writable):
+
+```
+PATCH /keyword-research-items/{itemId}
+{
+  "keywordResearchId": "...",
+  "item": { "id": "...", "keyword": "new keyword" },
+  "fieldMask": "keyword"
+}
+```
+
+**Copy-on-write:** the response may carry a different `keywordResearchId`.
+Always use the one from the response for the next write. Edits are not
+durable across generations.
+
+## What this recipe adds over the docs
+
+The published reference documents each method. This recipe adds:
+
+1. **The parking gate.** The docs say `KEYWORD_RESEARCH` is a status. This
+   recipe says: the flow stops there until you call Create Content Plan.
+   Without that call, polling runs forever.
+
+2. **PENDING_REQUIREMENTS handling.** This explicit status signals unmet
+   prerequisites. Report it and identify the missing requirement only from
+   evidence; do not infer it from a queued `CREATED` status or fill in business
+   information on the user's behalf.
+
+3. **Copy-on-write on keyword edits.** The `keywordResearchId` can change
+   on the first write. Use the one from the response.
+
+## Do not
+
+- Poll forever without calling Create Content Plan (step 3).
+- Read candidates before `SUCCESS`.
+- Retry after `PENDING_REQUIREMENTS`.
+- Ask for a site ID.
+- Retry after a 403 — the caller lacks **Manage SEO Settings**.

package/skills/wix-manage/references/seo/manage-seo-tags.md

@@ -1,6 +1,6 @@
 ---
 name: "Manage a Wix Site's SEO Tags"
-description: Read and update the SEO tags of a Wix site at the right level — site-wide tags, page-type patterns, or one item's tags. Discover item IDs and pattern variables instead of inventing them, read before every full-replace write, and report resolved tags with the source each one came from.
+description: Read and update SEO titles and tags at the right level. For "change my site's SEO title", clarify homepage, specific page, or page-type pattern before discovery or writes; site-level tags accept meta tags only, never titles. Discover item IDs and pattern variables, read before every full-replace write, and report resolved tags with their sources.
 ---
 
 # Manage a Wix Site's SEO Tags
@@ -38,6 +38,21 @@ Match the user's request to the level that owns the change:
 | "All my product/blog/event pages should be titled like X" — a convention for every item of a page type | Pattern | **SEO Patterns** |
 | "Change the title of this page/product/post" — one specific item | Item | **Item SEO Tags** |
 
+**Site SEO Tags accepts meta tags only** (including site-level social image
+and robots settings). Never send `title`, `link`, or `script` tags to
+`PATCH /site-seo-tags`. Use Item SEO Tags for a specific page's title, or
+SEO Patterns for a page-type title convention. See the
+[Site SEO Tags object](https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/site-seo-tags-object).
+
+If the user says "change my site's SEO title" without identifying a page or
+page type, ask whether they mean the homepage, another specific page, or a
+page-type title convention. Ask immediately after reading this recipe; do not make discovery or schema
+queries until scope is clear. For an explicit
+homepage request, discover its actual ID; never assume an ID such as `home`.
+Use Item SEO Tags with `STATIC_PAGE`, read its current tags, and merge the title
+into the complete set. Follow the static-page publication rules below.
+Do not substitute `og:title` for the requested SEO title.
+
 Work at the level that matches the change. Writing the same title onto many
 items is the same outcome as one pattern and much harder to undo. If the user's
 words fit more than one level, ask one short question before writing. An
@@ -84,7 +99,38 @@ No request body. Returns `itemSeoTags` with `tags`, `resolvedTags`,
 
 ### List Item SEO Tags — `GET /item-seo-tags/{itemType}?paging.limit=100`
 
-No request body. Returns `itemSeoTagsList[]` and `pagingMetadata` with cursors.
+No request body. Returns `itemSeoTags[]` and `pagingMetadata` with cursors.
+`itemSeoTagsList` is not a response field. Each array entry is an Item SEO Tags
+object directly, not a wrapper: read `entry.itemId`, `entry.tags`, and
+`entry.resolvedTags`, not `entry.itemSeoTags`. Use `itemId` as the path ID;
+`id` is a composite identifier and `hostPageId` is not the item identifier.
+
+For static-page discovery, call this with `STATIC_PAGE`. Example response:
+
+```json
+{
+  "itemSeoTags": [
+    {
+      "itemType": "STATIC_PAGE",
+      "itemId": "<page-id>",
+      "tags": [],
+      "resolvedTags": [
+        { "tag": { "type": "title", "children": "Home | Studio Shop" },
+          "source": "TAG_SOURCE_DEFAULT_PATTERN" }
+      ]
+    }
+  ],
+  "pagingMetadata": { "hasNext": false }
+}
+```
+
+Inspect the returned page identities and resolved tags to identify the requested
+page, then Get that exact `itemId` before writing. If the response does not
+unambiguously identify it, ask the user to identify the page. Do not interpret
+a missing response field as an empty page list, assume the first entry is the
+homepage, or create/update a pattern as a fallback for a missing page. A
+single-page request never authorizes changing all pages of its type.
+See [List Item SEO Tags](https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/list-item-seo-tags).
 
 ### Set Site SEO Tags — `PATCH /site-seo-tags`
 
@@ -255,8 +301,9 @@ issue another Get — the write response is the confirmation.
 - **Calling List Item SEO Tags expecting product names.** List returns IDs
   and tags, not names. Use Search Products to find the ID by name first.
 - **Retrying a 400 with a different request shape without checking why.** A 400
-  means the shape was wrong. Compare against the shapes in this recipe, fix the
-  mismatch, send once. Three retries with guessed shapes is three wasted calls.
+  can mean the target level is wrong, not just the shape. Read the validation
+  message and check the level rules first. Compare against the shapes in this
+  recipe, fix the mismatch, send once. Three retries with guessed shapes is three wasted calls.
 
 Tags can currently be written only for the site's primary language: leave
 `language` unset on every write. There is no revision checking — the last write
@@ -298,12 +345,18 @@ success.
 - **`UNSUPPORTED_ITEM_TYPE`:** the error message lists the item types the API
   supports; use it to redirect the request rather than retrying blindly.
 - **`ITEM_NOT_FOUND`:** re-discover the item ID; do not guess a new one.
+- **Unsupported site-level tag / `FIELD_NOT_ALLOWED`:** a rejected `title`,
+  `link`, or `script` is a wrong-level error, not a nesting or field-mask error.
+  Do not retry it at site level or silently drop the requested tag. Clarify the
+  target if needed, then use the appropriate item or pattern API. Get that
+  target's current tags before merging and writing; never reuse the site's
+  tags as the new target's complete set. A rejected write saved no changes.
 - **Invalid tags:** tags are validated before anything is saved, so nothing
   changed; fix the tag and resend the same complete set.
 - **`400` on a request you built from this recipe:** compare the request you
   sent against the shapes in this recipe's "REST request and response shapes"
-  section. Fix the mismatch — a wrong nesting level, a missing wrapper key, or
-  `fieldMask` sent as an array instead of a string — and send again. Never
+  section and the wrong-level recovery rule above. Fix the mismatch — a wrong
+  nesting level, a missing wrapper key, or `fieldMask` sent as an array instead of a string — and send again. Never
   resend the same shape, and never walk through variations hoping one is
   accepted.
 - **Setting tags for `EVENTS_PAGE` items:** not supported yet, although reading

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

@@ -0,0 +1,10 @@
+---
+name: "Change Store Currency"
+description: "Changes the store's payment currency through Site Properties and explains delayed currency updates in catalog responses."
+---
+
+# Change Store Currency
+
+Use the [Site Properties currency recipe](https://dev.wix.com/docs/api-reference/business-management/site-properties/skills/change-payment-currency-site-properties.md) to set the requested payment currency and read it back. Confirm the change with the user before updating it.
+
+Catalog product responses may temporarily show the previous currency after carts and checkout use the new one. Allow time for propagation, then recheck.

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

@@ -83,9 +83,22 @@ If any product is missing a price, **do not call the API**. Ask for the missing
 
 ## Build each product
 
+> [!WARNING]
+> **Hard requirement before every create call:** If `productType` is `"PHYSICAL"`, the request MUST include `physicalProperties` on the product and on every variant:
+>
+> ```json
+> {
+>   "productType": "PHYSICAL",
+>   "physicalProperties": {},
+>   "variantsInfo": {"variants": [{"physicalProperties": {}}]}
+> }
+> ```
+>
+> Put supplied physical fields such as weight or dimensions inside those objects; use `{}` when none were supplied. Never invent them, and never execute or retry a physical-product request when either object is absent.
+
 | Concern | Rule |
 |---|---|
-| Type | `PHYSICAL` uses product- and variant-level `physicalProperties`; `DIGITAL` omits them and carries `inventoryItem.inStock` plus `digitalProperties.digitalFile` on each variant. |
+| Type | `PHYSICAL` requires both `productType: "PHYSICAL"` and product-level `physicalProperties`, plus both `productType: "PHYSICAL"` and variant-level `physicalProperties` on every variant. `DIGITAL` omits physical properties and carries `inventoryItem.inStock` plus `digitalProperties.digitalFile` on each variant. |
 | Variants | Include at least one. Price, SKU, barcode, inventory, and digital file are variant-level fields. |
 | Price | Use a string in `price.actualPrice.amount`; add `compareAtPrice` only when supplied. |
 | SKU | Preserve supplied strings exactly, including `#`, punctuation, and leading zeroes. Keep variant SKUs unique unless explicitly requested otherwise. |
@@ -221,6 +234,8 @@ The first is for single endpoints; the second is for bulk endpoints. If the user
 
 For one product when the user supplied no quantity, stock state, or inventory-tracking request, the complete direct path is `POST /stores/v3/products` with `{"product": PRODUCT}`. Do not infer `inStock: true`, add `inventoryItem`, or choose `/products-with-inventory`; physical product type does not imply inventory. If it has ready images, add `"fields": ["MEDIA_ITEMS_INFO"]` to the same no-inventory request.
 
+For a physical product on either create endpoint, never send `productType: "PHYSICAL"` by itself. Include `physicalProperties: {}` on the product and `physicalProperties: {}` on every physical variant (or populate those objects with the supplied physical dimensions/weight). The API validates these as aligned one-of pairs and returns 400 if either corresponding field is missing.
+
 For one physical product with inventory, the complete direct path is one `POST /stores/v3/products-with-inventory` call with `{"product": PRODUCT}`. Put `inventoryItem` on its priced variant. If it has ready images, add `"fields": ["MEDIA_ITEMS_INFO"]` to that same request. The product shape, envelope, endpoint, and validation paths are complete here: do not search another recipe or schema, probe an alternate endpoint, or make a post-create read unless the projected create response does not prove requested media.
 
 ### Request projected media when validating images
@@ -300,4 +315,5 @@ Retry only failed transient items, not successful products. If a requested field
 - `variantsInfo must not be empty`: include at least one priced variant per product.
 - Option/variant mismatch: create every requested combination and reference every option once per variant.
 - Media not visible: use the uploaded `wixstatic.com` URL in `media.itemsInfo.items`; do not set `media.main`.
+- `productType` alignment 400 (`product is invalid: productType and the corresponding physical_properties field must be passed together`): pair `productType: "PHYSICAL"` with `physicalProperties` on the product and on every physical variant. The API validates these as aligned one-of pairs, so do not retry with only one level populated. Pair `productType: "DIGITAL"` with the digital variant fields instead.
 - Digital product rejected at add-to-cart: `ITEM_NOT_FOUND_IN_CATALOG` means the variant has no `digitalProperties.digitalFile`; `exceeds available inventory` means it has no `inventoryItem.inStock`. Both read back as a healthy product.

package/skills/wix-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,119 @@
+# 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. Fire product image generations first, then build the client
+(STEP 2), and seed (STEP 3) **after** the client is built — generation finishes while you build.
+
+## STEP 1 — Install the Wix skills and deploy the storefront vertical to the app
+
+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.** Fire every `generate_image` **before you build the client**, and seed **after**
+it — generation finishes while you build, so by the time you write the seed call your images are
+ready: each finished result now reads `status: "completed"` with its final
+`https://media.base44.com/...` url. Read every `imageUrl` from the results **as they read at that
+moment** — not from what they said when you called the tool — and pass them in the single
+`setupStore` call. A result without a final url by then (still running, or failed) → seed that
+product **without** `imageUrl` and attach it afterwards with `attachProductImages`.
+
+## STEP 4 — Wrap up
+
+### Preview
+
+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.