@wix/agent-skills 1.15.0 → 1.15.1

package/skills/wix-manage/references/marketing/generate-and-publish-marketing-plan.md

@@ -4,6 +4,22 @@ description: "End-to-end flow to generate an AI-powered social media marketing p
 ---
 # RECIPE: Generate a Marketing Plan and Schedule Its Posts
 
+## THE PROTOCOL (read this first — every rule is mandatory)
+
+Walk every marketing-plan request through this conversation, in this order. Skip a step only when the user's own words in this conversation already answered it.
+
+1. **Open with the current state.** Fetch the plan (STEP 3 endpoint) and the marketing settings (`GET .../marketing-settings`). Tell the user what the plan is shaped by and what they can change: goal, marketing tools, content pillars (topics), tone of voice, point of view, business profile, and per-tool cadence. Say which inputs are site-derived and **read-only**: language, business/target locations, industry — those change in the site's Language & Region / SEO business-location settings, never through marketing settings (details in STEP 1).
+2. **Decide the settings with the user.** For each setting they want to change, use their words. If they want help choosing, fetch the selectable values (`GET .../marketing-settings/plan-goal-options`, `GET .../marketing-settings/defaults`) and propose suggestions for them to confirm. Write only values the user gave or confirmed; leave everything else to the site defaults. Never fabricate a goal, tone, or topic list on their behalf, and never put `language`, `targetLocations`, or `businessLocation` in the request or claim the call changed them.
+3. **Save, then offer to generate.** Upsert the confirmed settings (STEP 1, `fieldMask` as a comma-separated string matching exactly what you send), then offer to generate the plan — or, if a plan already exists, to regenerate it so the new settings take effect (settings are read only at generation time; use the keyword-research variant when `topics` changed). Poll until `ACTIVE` (STEPs 2-3).
+4. **Present the plan from the API data only.** Show the returned activities and their post drafts. Never invent activities, dates, or captions and present them as "the plan" — if it isn't in the response, it isn't in the plan (also applies to STEP 5's post generation).
+5. **Show before scheduling.** Scheduling publishes AI-generated drafts. Before Schedule Drafts (STEP 4), show each draft's caption and media (render the image inline, or give its URL) and get explicit approval. Schedule exactly what was approved — never regenerate after approval.
+6. **Diff the schedule response.** Only drafts for Publisher-connected channels are scheduled; the rest silently stay `DRAFT`. Compare the returned `SCHEDULED` ids against the ids you sent, and tell the user which drafts didn't schedule and which channel needs connecting (STEP 4).
+7. **Respect cutoffs and gates.** Skip `TWITTER` drafts dated after July 31, 2026. `FAILED_PRECONDITION` on Schedule Drafts means the plan lacks the premium scheduling feature: say so once and stop; it is not a transient error to retry.
+
+The rest of this recipe is the reference for executing each step.
+
+---
+
 This recipe generates a site's AI marketing plan — a schedule of marketing activities (social campaigns, blog posts, emails) from today through the end of next month — and schedules the social posts it generates. Generation is **asynchronous and non-deterministic**: you fire it, poll until it's ready, then act on the results.
 
 Base URL for all endpoints: `https://www.wixapis.com/promote/marketing-plan-service/v1`.
@@ -20,7 +36,7 @@ For a first-time plan, configure marketing settings **before** generating (STEP
 
 **API Endpoint:** `POST https://www.wixapis.com/promote/marketing-plan-service/v1/marketing-settings`
 
-Both `marketingSettings` and `fieldMask` are **required**. `fieldMask` lists the paths to write, and **every path in `fieldMask` must be present** in `marketingSettings` (otherwise the call fails with `INVALID_FIELD_MASK_ERROR`).
+Both `marketingSettings` and `fieldMask` are **required**. `fieldMask` is a **single comma-separated string** of the paths to write (proto3 field-mask form) — **not a JSON array**. Sending it as an array (`["settings.marketingPlanGoal", …]`) fails with `400` `"Failed to parse request message"`. Every path in `fieldMask` must also be present in `marketingSettings`, or the call fails with `INVALID_FIELD_MASK_ERROR`.
 
 **Language and location cannot be set here.** If the request targets a language or a place ("posts in Spanish", "customers near Berlin"), those are site-derived, read-only fields on marketing settings — never put `language`, `targetLocations`, or `businessLocation` in the request, and never tell the user this call changed them. Set the fields that do belong here (goal, tone, audience description), and direct the user to the site-level settings for the rest — see **What you can't set here** below.
 
@@ -39,15 +55,7 @@ Both `marketingSettings` and `fieldMask` are **required**. `fieldMask` lists the
       "socialMarketing": { "frequency": { "interval": "WEEK", "count": 3 } }
     }
   },
-  "fieldMask": [
-    "settings.marketingPlanGoal",
-    "settings.marketingTools",
-    "settings.topics",
-    "settings.toneOfVoice",
-    "settings.pointOfView",
-    "settings.businessProfile",
-    "overrides.socialMarketing.frequency"
-  ]
+  "fieldMask": "settings.marketingPlanGoal,settings.marketingTools,settings.topics,settings.toneOfVoice,settings.pointOfView,settings.businessProfile,overrides.socialMarketing.frequency"
 }
 ```
 
@@ -189,6 +197,7 @@ For activities that have no `items` yet, generate their posts, then schedule the
 | Symptom | Cause | Fix |
 | --- | --- | --- |
 | Plan `status: FAILED`, or `ACTIVE` with no posts | Site not published, or `SOCIAL_MARKETING` not enabled in settings | Publish the site; ensure `settings.marketingTools` includes `SOCIAL_MARKETING`, then regenerate (STEP 2) |
+| `400` `"Failed to parse request message"` on Upsert Marketing Settings | `fieldMask` sent as a JSON array (or `{ "paths": [...] }`) instead of a comma-separated string | Send `fieldMask` as a single comma-separated string, e.g. `"settings.marketingPlanGoal,settings.toneOfVoice"` |
 | `INVALID_FIELD_MASK_ERROR` on Upsert Marketing Settings | A `fieldMask` path is missing from `marketingSettings` | Include every `fieldMask` path in the `marketingSettings` body |
 | Language, region, or location "won't change" via Upsert Marketing Settings | Those fields are read-only here (site-derived) | Change them in the site's Language & Region / SEO business-location settings, then regenerate |
 | `FAILED_PRECONDITION` on Schedule Drafts | Plan lacks the schedule-posts premium feature | Advise upgrading the social media marketing plan |

package/skills/wix-manage/references/sites/site-import.md

@@ -0,0 +1,270 @@
+---
+name: "Site Import"
+description: Drive the Wix Site Import agent to migrate an existing store or site from another platform (Shopify, WooCommerce, Magento, or any URL) into Wix. Use this skill whenever the user wants to import, migrate, or clone a store/site into Wix, mentions moving off Shopify/WooCommerce/Magento, or gives a source store URL and asks to bring it into Wix. Covers starting the import, polling progress, answering the agent's mid-import questions, handling deploy/failure/auth-expiry states, and sending post-deploy follow-up changes.
+---
+
+# Site Import
+
+Drives an autonomous Wix-hosted import agent over REST to migrate a store/site
+from another platform into Wix. You act as the relay between the user and the
+agent: start the job, poll it, surface its questions and progress like a chat,
+and report the final result.
+
+## Golden rules — apply to every single message
+
+1. **Only `DEPLOYED` means the site is live.** Any other status — including
+   `AUTH_EXPIRED` — means there is NO finished site yet. Never declare
+   success, completion, or "your site is live" otherwise, and never present a
+   URL from any other source as the result.
+2. **Never show the user ids** (`importId`), raw JSON, or HTTP codes. Track
+   them silently.
+3. **Never offer menus of monitoring or technical options** — pick the right
+   behavior yourself and do it quietly.
+4. **Plain language only** — write for a shopkeeper, not an engineer.
+5. **This API is the only site-creation tool for this task** — never
+   substitute other Wix site-builder tools (see Scope).
+
+Base URL: `https://www.wixapis.com/site-import`. All calls are scoped to the
+signed-in Wix user's account (use the Wix API tool available in this
+environment for auth — never handle credentials directly). A full import
+typically takes 15–60 minutes.
+
+Example: Start is `POST https://www.wixapis.com/site-import/v1/imports`;
+all endpoint paths below are relative to the base URL.
+
+## Calling the API (important — read before your first call)
+
+This API is **deliberately not listed in the public Wix REST documentation**,
+so do NOT search the Wix docs / API spec for it — the search will come up
+empty every time. That is expected and is NOT a reason to stop, ask the user
+for "special permissions", or switch to a different import product. This
+skill is the documentation; the endpoints below are real and live.
+
+With the Wix MCP in Claude, call them through `ExecuteWixAPI` using
+`wix.request` with `scope: "account"` and the **full URL**. Cite
+`sourceDocUrls: ["user-provided"]` (the user supplied this skill). Set
+`hasMutations: true` for Start/Reply/Cancel and `false` for Poll.
+
+In environments with a different Wix connector (e.g. ChatGPT), use its
+account-level API tool the same way — the `ManageWixSite` tool accepts
+`{method, url, body}` with the full URL directly.
+
+Platform quirk: if the chat UI shows a rendering error like *"Failed to load
+MCP app: HTML exceeds the maximum supported size"*, that is the connector's
+optional visual widget failing to display — NOT the API call. If the tool
+result contains the JSON, the call succeeded: continue normally and never
+report it to the user as a failure.
+
+**Every call goes through that tool, from your side of the conversation.**
+Never call this API from an artifact, a web page, or any browser/client-side
+code — those run in a sandboxed frame and fail with CORS. Do not build
+monitoring dashboards, status widgets, or any UI for this flow: the entire
+experience is plain chat — tool calls plus short messages. If an approach
+fails, quietly switch to plain tool-call polling; never present the user a
+menu of technical workarounds.
+
+Example — Start:
+
+```js
+async () => {
+  return await wix.request({
+    scope: "account",
+    method: "POST",
+    url: "https://www.wixapis.com/site-import/v1/imports",
+    body: { request: "Import https://example-store.com into a new Wix site" },
+  });
+}
+```
+
+Example — Poll:
+
+```js
+async () => {
+  return await wix.request({
+    scope: "account",
+    method: "GET",
+    url: "https://www.wixapis.com/site-import/v1/imports/<importId>",
+  });
+}
+```
+
+## Scope — this skill drives the import service, nothing else
+
+While an import is the task at hand, ALL site-creation work goes through this
+API. Never fall back to other site-building tools (site-builder/template/AI
+site-generation tools from your Wix connector) to "compensate" — not when the
+import is slow, and especially not when it FAILS.
+
+**Status comes ONLY from this API's Poll endpoint.** Never call
+`WixSiteBuilder`, `CreateSiteFromTemplate`, `pullSiteCreationJob`, or any
+other connector tool to "check on the build" — `WixSiteBuilder` in particular
+STARTS a new site build on every call, even when the prompt asks for status;
+"checking" with it silently creates sites the user never asked for. A failed import ends with a
+clear failure report and a full stop; the user must never discover a
+different site in their account that they didn't ask for. If an alternative
+(e.g. building an original site instead of importing) makes sense, propose it
+AFTER reporting the failure and act only on the user's explicit yes. If you
+already know the import agent refused the source (see `message`), don't
+retry the same source with other tools — relay the reason and let the user
+decide.
+
+## Before starting an import
+
+This creates real infrastructure and will eventually write to the user's Wix
+account. Before calling **Start**, confirm with the user:
+- The source URL and platform are correct
+- They understand this will run for up to ~60 minutes and may ask them
+  questions mid-way
+
+Also confirm before calling **Cancel** — it's a mutating, irreversible action
+on a running job.
+
+## What the user sees (presentation rules)
+
+You are the user experience; the API is plumbing. Keep the protocol invisible:
+
+- **Never show identifiers or raw protocol data**: `importId`, raw JSON
+  responses, HTTP status codes, the `tasks[]` rows, or
+  `sourcePlatform`/`sourceConfidence` values. Track them silently — you need
+  them for the API calls, the user never does. Never offer ids as a
+  "check back later" reference either.
+- **Write for a non-technical audience.** No jargon: no "endpoint", "API",
+  "poll", "HTTP", "429", "rate limit", "headers", "JSON", "scraping",
+  "session". Translate events into outcomes a shopkeeper understands —
+  "the source store limits how fast it can be read, so this step is taking a
+  minute" instead of "hit Cloudflare rate limit (HTTP 429)".
+- **Monitor quietly by default — do not ask the user to choose a monitoring
+  mode.** Quiet means low-noise, never uninformed: the user should always know
+  what stage their import is in. Match your environment:
+  - **If you can keep working between user messages** (background polling),
+    poll continuously and speak up only on meaningful milestones: the source
+    platform is identified, a plan step completes, the agent asks a question,
+    the site deploys, or something fails. A short update every few minutes is
+    plenty; never narrate each poll ("let me poll again", "retrying") or
+    transient errors — retry those silently.
+  - **If you can only act while answering a message** (turn-based clients):
+    before ending each turn, poll a few times over ~a minute and close with
+    one concrete update of what the import is doing right now, then remind the
+    user the import keeps running on Wix's side and they can ask "how's it
+    going?" anytime. On EVERY later user message, poll first and answer with
+    current specifics.
+- **Status answers must be substantive.** When the user asks how it's going,
+  never answer with a bare "still in progress". While the import is running,
+  the poll's `message` field is a ready-made plain-language progress line
+  ("Now: Importing products (2 of 6 steps done) — Latest update: …") — relay
+  it (lightly rephrased is fine), and add anything fresh from `recentActivity`
+  / `todos`. If `message` is empty it's still early — say the import is
+  setting up and check again on the next message.
+- **Never announce or describe the monitoring itself.** No "background monitor
+  is live", no feature lists of your polling/alerts/badges — the user asked
+  for a site import, not a monitoring product. After the one-sentence start
+  message, stay silent until the first milestone.
+- **Keep every routine update to 1–3 short sentences.** No headers, no emoji
+  walls, no bullet lists for ordinary progress — save structure for the final
+  result or a question that needs a decision.
+- On start, one friendly sentence: the import is underway and you'll keep them
+  posted. Mention the detected platform only when it helps ("Looks like a
+  Shopify store — I'll migrate the catalog accordingly"); never say
+  "confidence", "sandbox", "execution", or "session".
+- Progress updates come from `recentActivity` `TEXT` entries and the `todos`
+  checklist, rephrased in plain language ("setting up your product catalog"),
+  never echoed verbatim.
+- Ask `NEEDS_INPUT` questions conversationally, as if they were your own.
+- On `DEPLOYED`, lead with the live URL, then the agent's closing summary
+  **rewritten for a non-technical reader**: what the user got (pages,
+  products, look & feel), any honest limitations in plain words ("the buy
+  buttons aren't connected to a real checkout yet"), and 2–3 short follow-up
+  offers they can answer in one sentence (those become Reply messages). Leave
+  out how it was built — frameworks, SDKs, workarounds, and anything from the
+  jargon list have no place in the final message either.
+- On `FAILED` / `AUTH_EXPIRED` / `SESSION_EXPIRED`, explain what happened and
+  what you'll do next in plain words — no codes, no id dumps.
+- **A failure is the headline, never a footnote.** The moment a poll returns
+  `FAILED`, your very next message leads with that fact and the reason (from
+  `message`) — never bury it, never keep talking as if work is ongoing, and
+  never paper over it with work done by other tools (see Scope above).
+
+## Endpoints
+
+**There is exactly ONE id in this API: the latest `importId`.** Requests and
+responses carry nothing else — the service resolves everything from the
+signed-in user.
+
+1. **Start** — `POST /v1/imports`
+   Body: `{"request": "<natural language; MUST include the source store URL>"}`
+   Returns: `importId` (keep it — it's the import's id) and detected
+   `sourcePlatform`/`sourceConfidence`.
+
+2. **Poll** — `GET /v1/imports/{importId}`
+   Returns: `status`, `deployUrl`, `message`, `recentActivity[]`, `todos[]`,
+   `question` (only when status is `NEEDS_INPUT`), `tasks[]`.
+
+3. **Reply** — `POST /v1/imports/{importId}/reply`
+   Body: `{"message": "<answer or follow-up>"}`
+   Returns a **NEW `importId` — poll that one from now on.** The agent
+   continues the same conversation with full context.
+
+4. **Cancel** — `POST /v1/imports/{importId}/cancel`
+   Body: `{}`. Only meaningful while status is `IMPORTING`.
+
+## How to run the flow
+
+- After Start, poll every 5–10 seconds while `status` is `IMPORTING` —
+  quietly, per the presentation rules above: polling is background work, not
+  conversation.
+- Track progress from two fields (source material for your milestone updates,
+  not a transcript to relay):
+  - `recentActivity`: up to 20 entries `{kind, text}`, oldest first —
+    `TEXT` entries are the agent's own messages, `TOOL_USE` entries are short
+    labels of actions it took. It's a rolling window: track which entries you
+    have already covered so an update never repeats them.
+  - `todos`: the agent's plan, `{content, status, activeForm}` with status
+    `PENDING | IN_PROGRESS | COMPLETED`. Each poll returns the full latest
+    snapshot — replace your tracked list, don't append. `activeForm`
+    (e.g. "Importing products") describes the in-progress item.
+  - Empty `recentActivity`/`todos` in the first polls is normal.
+- Act on `status`:
+  - `IMPORTING` — keep polling.
+  - `NEEDS_INPUT` — the agent is blocked on a decision. Show `question.text`
+    (and `question.options` if present) to the user, collect their answer
+    (an option or free text), send it via Reply, then poll the NEW
+    `importId` from the Reply response.
+  - `DEPLOYED` — terminal success. Deliver `deployUrl` (already verified
+    reachable server-side) and `message` per the presentation rules above.
+  - `FAILED` — terminal. `message` usually contains the agent's own
+    explanation of what happened and what it needs — relay it in plain words.
+  - `AUTH_EXPIRED` — recoverable, but **NOT a success and nothing is live**
+    (golden rule 1). The user's Wix session expired mid-import. Tell the user
+    the secure connection to their account expired and you're restarting the
+    import, then call Start again with the same request — work done so far is
+    preserved and the import continues.
+  - `CANCELLED` — terminal; stopped by Cancel.
+- Follow-up changes after a deploy ("make the header blue", "also import the
+  blog"): send them via Reply on the latest `importId` — same mechanics as
+  answering a question. This works while the import environment is alive
+  (~60 minutes idle).
+- If Reply returns `409 { "code": "SESSION_EXPIRED" }`, the environment was
+  reclaimed and the conversation cannot resume — tell the user and offer to
+  start a fresh import.
+
+## Rules
+
+- Always use the **newest** `importId` (each Reply returns a new one) —
+  it is the only id you need to track.
+- Never invent a `deployUrl` — only report the one returned with `DEPLOYED`.
+- Treat `NEEDS_INPUT` and `AUTH_EXPIRED` as normal turns of the conversation,
+  not errors.
+- **Site Import is available to some accounts, not all users yet** (limited,
+  gradual rollout). If Start returns a `404` (or any response signalling the
+  API is not available for this account) or a `403` with
+  `"code": "NOT_ENABLED"`, this account is not in the rollout: tell the user
+  plainly that **site import isn't supported on their account yet, and they
+  can contact Wix support** to ask about access — then stop. Do not retry, do
+  not work around it, and do not fall back to another site-creation tool.
+- Any other `403` means the caller is not permitted or does not own this
+  import — check that you are using the ids from this user's own Start
+  response. A `400` means a required field is missing (`request`/`message`
+  must be 1–20000 chars).
+- `tasks[]` is low-level infrastructure progress (task ids, exit codes) — use
+  it for debugging only; `recentActivity`/`todos`/`message` are what you show
+  the user.

package/skills/wix-manage/references/stores/create-product-from-image.md

@@ -211,7 +211,7 @@ Store the result internally as `subscription_eligible: true/false`. If `true`, a
 
 ## V3 STEP 4: Present Review Card to User (INTERACTIVE)
 
-**You MUST present ALL generated fields to the user and ask for confirmation before proceeding.**
+**Present ALL generated fields to the user so they can review and refine them.** This is a content preview for editing — NOT the create approval. The single confirmation before creating happens later, in V3 STEP 6. Do not ask the user to approve creation at this step.
 
 Present a structured review card using the markdown format below. This provides a visual product-card-style layout:
 
@@ -242,15 +242,15 @@ Present a structured review card using the markdown format below. This provides
 ---
 ```
 
-After the card, present the action options:
+After the card, offer the ways they can adjust the content:
 
 > 1. **Refine** — tell me what to change (e.g., "make the description shorter", "the price should be lower")
 > 2. **Regenerate** — I'll start the analysis over, optionally with additional context from you
-> 3. **Approve** — lock in these details and continue to the next steps
+> 3. **Looks good** — continue to the next steps (options / subscription)
 
 If the user provided a text note that **contradicts** what's visible in the image (e.g., image shows blue but note says "available in red"), ask the user to clarify before proceeding.
 
-**Wait for user confirmation.** Apply any corrections they request. Do NOT proceed until approved.
+Apply any corrections the user requests. When they're happy (or have no changes), continue to the next step. **Do NOT treat this as the final create approval** — that single confirmation comes once, at V3 STEP 6.
 
 ---
 
@@ -342,13 +342,15 @@ If no options were detected:
 
 ## V3 STEP 6: Create the Product
 
-Before making the API call, ask the user one final time:
+> **CRITICAL — THIS IS THE ONLY CREATE CONFIRMATION. ASK EXACTLY ONCE.** The review card in V3 STEP 4 was a content preview for editing, not an approval. Here you ask for the single go-ahead before creating. Do NOT summarize-and-ask more than once — one clear confirmation is enough.
+
+Ask the user once:
 
 > Everything is ready. Shall I create the product now?
 > - **Yes, create it** — I'll submit the product to your store now.
 > - **No, go back** — return to a previous step to make changes.
 
-**Wait for confirmation.** Only proceed with the API call if the user says Yes.
+**Wait for confirmation.** Only proceed with the API call if the user says Yes. If the user already said something like "just create it", treat that as the confirmation and proceed without asking again.
 
 ---
 

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

@@ -18,20 +18,18 @@ The goal of this step is not just to create *a* product, but to help the user cr
 
 ### 0a. Opening the conversation
 
-**If the user hasn't named a product yet, open the conversation with this question up front:**
+**As soon as this skill is triggered — and the user hasn't already described a product — YOU open the conversation.** Proactively send a single opening message that invites *either or both* input paths and makes clear you'll generate the full product info from whatever they provide:
 
-> **What product would you like to create?**
+> **What would you like to sell? Just describe your product in a few words and/or upload a photo of it — I'll generate the full product info (name, description, price, and any options) for you from there.**
 
-If the user already gave you product details, skip the opening question and go straight to the gap check in 0b.
+The user can reply with a text prompt, an image, or both:
 
-**Offer a starting path.** When opening the conversation (and the user hasn't already committed to a method), let them choose how to provide the product details:
+- **An image is provided (with or without text)** → follow the **[Create Product from Image](https://dev.wix.com/docs/api-reference/business-solutions/stores/skills/create-product-from-image)** recipe to generate the product info from the image(s), then continue from the gap check in 0b for anything still missing.
+- **Text only** → continue with the gap check in 0b.
 
-> "You can either **upload a product image** and I'll create the product info from it, or just **describe the product in text** and I'll take it from there. Which would you prefer?"
+If the user *already* described a product when triggering the skill, skip this opening message and go straight to 0b.
 
-- If the user wants to start from an image → follow the **[Create Product from Image](https://dev.wix.com/docs/api-reference/business-solutions/stores/skills/create-product-from-image)** recipe to extract the product name, description, price, and any visible options from the image(s), then continue the conversation from 0b with whatever that recipe couldn't fill in.
-- If the user prefers text / a prompt → continue with the gap check in 0b as usual.
-
-> **Count this toward the 1–2 question budget.** If you ask the image-vs-text question, keep the remaining follow-ups to one so the total conversation stays short.
+> **This opening message is the entry point, not a follow-up — it does NOT count against the 1–2 follow-up-question budget in 0b.**
 
 ### 0b. Gap check — decide what (if anything) to ask
 
@@ -59,7 +57,15 @@ You may ask **one** enrichment question to make the product more complete. Ask a
 
 > **CRITICAL — ONCE A PRODUCT-CREATION CONVERSATION HAS STARTED, STAY ON IT.** Do not switch to other topics, suggest unrelated tasks, or start new workflows until the product has actually been created (saved) via STEP 1 — **unless the user explicitly asks to do something else**. If the user goes off-topic, briefly answer if needed, then steer back to finishing and saving the product.
 
-After the product is saved, you're free to suggest next steps (e.g. adding more products, setting up the store).
+### 0d. Confirm once — then create
+
+> **CRITICAL — VALIDATE EXACTLY ONCE BEFORE CREATING.** Right before calling the Create Product API (STEP 1), show a brief summary of what you're about to create and ask for a single go-ahead. Ask **only once**. Do NOT approve-and-then-ask-again (e.g. present a summary, get a "yes", and then ask "shall I create it now?" a second time) — that double confirmation is exactly what we want to avoid. Once the user approves, go straight to STEP 1 with no further approval prompts.
+
+For example:
+
+> "Here's what I'll add to your store: **[name]** — **[price]**[, options: …]. Ready to create it?"
+
+If the user already signaled approval (e.g. "just create it", "go ahead"), treat that as the single confirmation and proceed straight to STEP 1 — do not ask again.
 
 ## STEP 1: create the product with options and variants
 

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

@@ -40,6 +40,12 @@ This skill is the deliberately **client-only, REST-only** path. It is independen
   it only mints anonymous visitor tokens. It is **not a secret**; hardcoding and committing it
   is fine. The user provides it (their vibe/host platform surfaces a copyable prompt with the
   id filled in). Paste it into `wix-client.js` in place of the `<YOUR-CLIENT-ID>` placeholder.
+- **Money/price fields are objects, never scalars.** Every price/amount a Wix API returns —
+  Stores `price.actualPrice`, Bookings service `payment.fixed.price`, Events ticket
+  `registration.tickets.lowestPrice`, and the rest — has the shape `{ value, currency,
+  formattedValue }`. Render **`formattedValue`** (it already includes the currency symbol), or
+  fall back to building from `value` + `currency`. **Never** drop the object straight into the UI
+  or treat it as a number/string — that renders `[object Object]` or a bare unformatted number.
 - **Visitor token = identity.** `wix-client.js` mints an anonymous visitor token, persists the
   **refresh token to `localStorage`**, and refreshes on expiry. That token IS the identity of
   the cart / reservation / member session — **never re-mint anonymously per load** or the cart

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

@@ -0,0 +1,22 @@
+# Vibe platform handoff prompts
+
+One file per AI-builder platform (Base44, Lovable, Bolt, v0, Manus, …). Each file is the
+**handoff prompt** the Wix Headless funnel hands to that platform after it creates the site +
+OAuth app: build the client, then seed/manage the business.
+
+`generic.md` is the **platform-agnostic** version — same flow (install skills → build client →
+seed/manage → wrap up) with no assumptions about a specific platform's tooling. Use it as the
+default/fallback for platforms without their own tuned file; `base44.md` is the Base44-specific
+one (its exec tool, secret store, pre-configured connector, etc.).
+
+These are hosted (served at `https://www.wix.com/skills/vibe-headless/platforms/<platform>.md`)
+so the funnel loader can pass a short pointer to the prompt instead of inlining the whole
+script into the launch URL. Inlining tripped the Base44 edge WAF, which scans the POST body
+for command-injection patterns (`curl … | tar`, `require('child_process')`, etc.); a plain
+GET of a hosted file is not scanned that way.
+
+**Loader contract:** the funnel sends a short prompt that names the business, passes the Wix
+client id + metasite id, and points here — e.g. "Build a site for my Wix managed business:
+&lt;business&gt;. Then fetch and follow https://www.wix.com/skills/vibe-headless/platforms/base44.md
+exactly." The dynamic bits (business description, client id, metasite id) stay in the loader
+prompt; everything static lives in these files.

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

@@ -0,0 +1,142 @@
+# Wix Managed Headless — Base44 build instructions
+
+You are building a **Wix Managed** headless site inside Base44. The business to build is
+described in your initial prompt. The Wix connector is already configured for this app — use
+it for all Wix API calls.
+
+Your Wix client id is given in your prompt. It's a public, buyer/visitor-facing credential (it
+only mints anonymous visitor tokens), so it's safe in the frontend — use that value directly for
+the Wix client setup.
+
+Follow the steps below exactly.
+
+## STEP 0 — Install the Wix skills locally
+
+Install three skills — they land under `.agents/skills/` as:
+- **`wix-vibe-headless`** — the client build guide: how to build the frontend against the Wix
+  APIs. This is your main source of truth (STEP 1).
+- **`wix-headless`** — a broad skill for building full Wix apps with the Wix SDK packages, **most
+  of which does not apply to how you build here**. Use it **only** as a seeding/admin recipe
+  reference — its `references/SEED.md` and `references/inline-recipes/`, for STEP 2. **Ignore
+  everything else in it** — in particular do **not** follow its authentication / `@wix/cli` /
+  "managed project" setup (e.g. anything under `references/managed/`, such as `AUTHENTICATION.md`).
+  That is **not** how auth works here — auth is handled per STEP 2 below.
+- **`wix-docs`** — a **fallback**: how to search and read the Wix API reference docs, for anything
+  the seeding recipes above don't cover.
+
+**Option A — skills CLI.** This is the Base44-verified install path — run it first via
+exec_tool, exactly as written:
+
+```js
+const { execSync } = require('child_process');
+const { readdirSync } = require('fs');
+
+const skills = ['wix-headless', 'wix-vibe-headless', 'wix-docs'];
+const results = {};
+
+for (const skill of skills) {
+  try {
+    const out = execSync(`CI=1 npx -y skills add wix/skills/skills/${skill} --yes 2>&1`, {
+      cwd: '/app', timeout: 60000, shell: '/bin/bash', stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const text = out.toString().replace(/\x1b\[[0-9;]*m/g, '');
+    results[skill] = /installed 1 skill|found 1 skill/i.test(text)
+      ? 'success'
+      : text.includes('No valid skills') ? 'not_found' : 'unknown';
+  } catch (e) {
+    results[skill] = 'error: ' + e.message;
+  }
+}
+
+return { results, installed: readdirSync('/app/.agents/skills') };
+```
+
+**Option B — tarball.** Use this **only if Option A actually errored** (check its `results`) —
+do not skip Option A on a guess. Run via exec_tool:
+
+```js
+const { execSync } = require('child_process');
+for (const s of ['headless', 'vibe-headless', 'docs']) {
+  execSync(`mkdir -p /app/.agents/skills/wix-${s} && curl -s "https://www.wix.com/skills/${s}.tgz" | tar xz -C /app/.agents/skills/wix-${s} --strip-components=1`);
+}
+return 'done';
+```
+
+Either way you end up with `.agents/skills/{wix-headless,wix-vibe-headless,wix-docs}`. **Read them
+with the `read_file` tool** — it caps by line (~5000, well above these docs, so each comes through
+whole; page with offset/limit only if ever needed), whereas `cat` through exec_tool caps output at
+~5000 chars and silently truncates, and web-fetch tools truncate/summarise. The path form depends
+on the tool:
+- **`read_file` (preferred):** rooted at `/app`, so use the workspace-relative path
+  `.agents/skills/wix-vibe-headless/SKILL.md` — an absolute `/app/...` double-prefixes and fails.
+- **exec_tool / shell** (only if you must): use the absolute path
+  `/app/.agents/skills/wix-vibe-headless/SKILL.md`.
+
+## STEP 1 — Build the client
+
+Read `.agents/skills/wix-vibe-headless/SKILL.md` and follow it **EXACTLY** — it is the single
+source of truth for how the client app is built. To save time, prefer copying ready-made files
+the `wix-vibe-headless` skill provides (e.g. the Wix client setup) and adapting them over
+re-generating them from scratch.
+
+## STEP 2 — Manage and seed the business
+
+Seed the site with real content by following the **`wix-headless` skill**'s
+`references/SEED.md` (`.agents/skills/wix-headless/references/SEED.md`). Where its seed recipes
+don't cover what you need, **fall back to the `wix-docs` skill** (`.agents/skills/wix-docs`) to
+search and read the relevant Wix API docs.
+
+**Seeding is additive.** You may clean up the app install's **obvious default sample/mock data**
+right after a fresh install, but the site may already hold **real content** (a prior run, or
+owner-added) — if what's there isn't obviously install sample data, or you're unsure, **do not
+delete or overwrite it without the user's explicit ask or approval** (ask first).
+
+**Auth for these admin calls is the already-configured Wix connector — and nothing else.** Get the
+access token from it and send it as a bearer token — do **not** hand-roll a token getter (e.g. a
+custom `getAdminToken()`):
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+// then: fetch(url, { headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" }, ... })
+```
+
+Do **not** install or run the Wix CLI (`@wix/cli`), do a device-login, or follow `wix-headless`'s
+`references/managed/AUTHENTICATION.md` — that managed-project auth flow does not apply to Base44
+and will send you down the wrong path.
+
+When you run seed/management code **inline via exec_tool**, `base44` is already declared — use
+it directly. Do **not** import `@base44/sdk`, re-declare `base44`, or call `createClient()` —
+that pattern is only for standalone `.js` skill files, and inline it throws *"Identifier
+'base44' has already been declared."*
+
+**IMPORTANT:** the Wix connector and the `wix-headless` skill's seeding instructions are for
+management/admin operations only (STEP 2) — they are **NOT** part of the client. The client is
+built solely per the `wix-vibe-headless` skill.
+
+## Parallelism
+
+If possible, run STEP 1 and STEP 2 in parallel — building the client and seeding the business
+are independent, so don't wait for one to start the other. Within each step, also work in
+parallel where possible (e.g. independent API calls, seeding multiple entities) instead of
+one-by-one, to finish faster.
+
+## STEP 3 — Wrap up
+
+Once the site is built and seeded:
+
+1. **Leave a brief "Wix skills" note in `AGENTS.md`** (project root) so a future session has
+   context. If the file already exists, **`read_file` it first and only append your section** —
+   do **not** rewrite, reorder, or remove anything already there; if you can't append cleanly,
+   skip this rather than overwrite. Create the file only if none exists. Keep the note
+   high-level, e.g.: the Wix skills are installed under `.agents/skills/`; the client is built
+   per the `wix-vibe-headless` skill; seeding/management is done per the `wix-headless` +
+   `wix-docs` skills.
+2. **Ask the user to open** this URL to complete the setup in Wix (substitute the metasite id
+   you were given): `https://manage.wix.com/dashboard/{metaSiteId}`
+
+## Later admin requests
+
+For any later admin/management request the user makes, work the same way as STEP 2: check the
+`wix-headless` skill's inline recipes first (`.agents/skills/wix-headless/references/inline-recipes/`)
+and, where the operation isn't documented there, fall back to the `wix-docs` skill to search the
+Wix API docs — all over the Wix connector.