@wix/agent-skills 1.19.1 → 1.19.2

package/skills/wix-headless/references/inline-recipes/how-to-code-members-astro.md

@@ -1,6 +1,6 @@
 ---
 name: "How to Code Members (Astro)"
-description: The frontend contract for member sign-up / log-in / log-out and member-gated surfaces on a Wix-managed **Astro** frontend — the built-in `/api/auth/login` + `/api/auth/logout` routes that `@wix/astro` ships, the `returnToUrl` param, gating a page by resolving the member in SSR / a backend route, reading the current member with `@wix/members` `getCurrentMember`, and the two rules that keep this path from breaking: **no `OAuthStrategy`/no client** (that 500s under auto-auth) and **no `auth.elevate`** for a member reading their own data. Specifies the *how* for the Astro axis only — read `how-to-code-members-non-astro.md` for any non-Astro frontend.
+description: "The frontend contract for member sign-up / log-in / log-out and member-gated surfaces on a Wix-managed **Astro** frontend — the built-in `/api/auth/login` + `/api/auth/logout` routes that `@wix/astro` ships, the `returnToUrl` param, gating a page by resolving the member in SSR / a backend route, reading the current member with `@wix/members` `getCurrentMember`, and the two rules that keep this path from breaking: **no `OAuthStrategy`/no client** (that 500s under auto-auth) and **no `auth.elevate`** for a member reading their own data. Specifies the *how* for the Astro axis only — read `how-to-code-members-non-astro.md` for any non-Astro frontend."
 ---
 **RECIPE**: How to Code Member Auth on a Wix-managed **Astro** Frontend (built-in `/api/auth/*`, `@wix/members`)
 

package/skills/wix-headless/references/managed/CREATE.md

@@ -107,6 +107,11 @@ headlines, kickers, subtitles, and CTA labels per **`references/CONTENT.md`**
 Either way, `CONTENT.md` §1 (the business's category must read literally above the fold) always holds —
 a page a first-time visitor can't identify isn't done yet, regardless of voice.
 
+**If a loaded vertical ships an experience overlay** — `references/inline-recipes/experience-<vertical>.md`
+(today: `experience-store.md`) — read it after `DESIGN.md`/`CONTENT.md`. It carries that vertical's own
+design and copy bar (what its surfaces must show, how to derive the direction from its content); the
+general files stay the floor.
+
 Then build the pages the user's intent calls for, **wired to the live backend**, using
 **`references/SDK_HANDOFF.md`** for the per-capability packages, the SDK docs, and the seeded schema to
 bind (collection/form names + field keys; all other content is queried live). Install the SDK packages the loaded verticals need, author the pages/components directly in the

package/skills/wix-manage/SKILL.md

@@ -107,7 +107,7 @@ Full CRUD operations for Wix Bookings services using Services API. Covers servic
 "Answers whether an appointment-based Wix Bookings service currently has bookable availability — the primary question — and diagnoses the cause only when there's no availability or the owner asks why. To diagnose, first rules out service-level blockers the availability endpoint can't see (service hidden, online booking off), then runs DiagnoseAvailability for ordered, machine-readable staff/setup reasons, with a manual fallback for booking-policy and capacity causes. Use when someone asks whether a service has availability, or why a service shows no times / customers can't book it."
 
 ### [End-to-End Booking Flow](references/bookings/end-to-end-booking-flow.md)
-Complete booking flow from service discovery to payment. Query services, check availability with Time Slots V2, create bookings, and process payment via eCommerce checkout.
+Books and settles appointments, classes and courses with the site owner's credentials — an operator managing bookings, or server-side code booking as the owner. Covers service discovery, availability with Time Slots V2, creating the booking, and settling it by direct confirmation or eCommerce checkout. A visitor booking for themselves needs a visitor token instead; this recipe links that path.
 
 ### [External Calendar Integration](references/bookings/external-calendar-integration.md)
 OAuth-based integration with Google Calendar, Microsoft Outlook, and Apple Calendar. Covers authentication flows, sync configuration, and bidirectional event management.
@@ -289,7 +289,7 @@ Creates payment links for unpaid bookings using Payment Links API. Links booking
 **Routing — Google paid-advertising campaigns for a site (Smart & Performance Max).** All flows require a Google Ads account, created once via the setup recipe. Budgets are in micros (1,000,000 = 1 currency unit). REST base: `https://www.wixapis.com/_serverless/pa-google/v1`.
 - **First-time setup / "connect Google Ads" / `ACCOUNT_NOT_FOUND`** → [Install and Create an Account](references/google-ads/install-and-create-account.md) (do this before anything else).
 - **Suggested keywords / geo / budget / ad copy / images** → [Get AI Campaign Suggestions](references/google-ads/get-campaign-suggestions.md).
-- **Offer a Success Guide after creating a PMAX Leads campaign (a proactive offer requires approval) / improve it / success guide / says they completed or fixed a guide recommendation / mark or reopen a recommendation** → [Manage a Campaign Success Guide](references/google-ads/manage-campaign-success-guide.md) (a direct improvement/guide request is already approval; works while `LEARNING` and before metrics exist).
+- **Improve an existing campaign / see what to fix next / Campaign Success Guide / mark or reopen a recommendation** → [Manage a Campaign Success Guide](references/google-ads/manage-campaign-success-guide.md).
 - **Create a multi-channel / lead-gen / Shopping campaign** → [Create a Performance Max Campaign](references/google-ads/create-performance-max-campaign.md).
 - **Pause / resume / launch / update budget / delete / history** → [Manage Campaign Lifecycle](references/google-ads/manage-campaign-lifecycle.md).
 - **Performance, conversions, search terms, per-product / per-asset metrics** → [Query Campaign Performance Analytics](references/google-ads/query-campaign-analytics.md).
@@ -308,7 +308,7 @@ Creates payment links for unpaid bookings using Payment Links API. Links booking
 "Manages existing Google Ads campaigns on a Wix site: list/get, launch (first activation) vs resume (reactivate after a pause), pause a running campaign — optionally with a scheduled auto-resume date — update name/budget/targeting, change the daily budget, delete permanently, and read status history / change log. Use when the user wants to 'pause my Google ad', 'resume my campaign', 'stop the campaign', 'change my daily budget', 'rename the campaign', 'delete this campaign', 'list my Google Ads campaigns', or 'why did my campaign status change'. Requires an existing Google Ads account and campaign. REST base https://www.wixapis.com/_serverless/pa-google/v1."
 
 ### [Manage a Campaign Success Guide](references/google-ads/manage-campaign-success-guide.md)
-"Retrieves and manages the campaign success guide for an existing Wix Google Ads Performance Max Leads campaign. Offer it after creating a supported campaign, even while it is learning or has no metrics; that proactive offer requires approval before retrieval. A direct request to improve a campaign, see what to fix next, or show the guide is already approval to retrieve it. Also use when a user reports completing or wants to reopen a guide item. Treat a clear completion report as an actionable update request even when phrased as a statement. Covers campaign selection, prioritized guide retrieval, and suggestion status updates without redundant confirmation. REST base https://www.wixapis.com/pa-platform/suggestions/v1."
+"Campaign Success Guide for existing Wix Google Ads Performance Max Leads campaigns. Use after creating a supported campaign, even while it is learning or has no metrics, and whenever users ask how to improve a campaign, what to fix next, to view the guide, or to mark or reopen a recommendation. Covers campaign and site selection; prioritized actionable recommendations; deduplicated, destination-specific Editor and Google Ads navigation; offers to perform supported work after approval; Merchant Center and Business Profile connection follow-ups; and suggestion-status tracking."
 
 ### [Query Campaign Performance Analytics](references/google-ads/query-campaign-analytics.md)
 "Reads performance analytics for a Google Ads campaign on a Wix site: daily performance metrics (impressions, clicks, CTR, cost, leads, phone calls) with optional previous-period comparison and trends; conversion metrics from Wix Analytics (orders, revenue, leads, CPL, ROAS); the search terms that triggered a campaign's ads; per-product shopping performance for retail campaigns; and per-asset performance (headlines, descriptions, images) for PMAX Leads. Explains when to use campaignResourceName vs the Wix campaignId, the dateRange shape, field enums, sorting, and paging. Use when the user asks 'how is my campaign doing', 'show ad performance', 'what search terms triggered my ads', 'which products/assets perform best', 'campaign ROI/ROAS', or 'conversions from my Google ads'. REST base https://www.wixapis.com/_serverless/pa-google/v1."
@@ -425,7 +425,7 @@ Drive the Wix Site Import agent to migrate an existing store or site from anothe
 "Builds direct links to the account-level sites pages on manage.wix.com — the My Sites list (all sites in the account) and each site's own dashboard. Pairs the site list with the Query Sites read API. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
 
 ### [Upload a Website or HTML Files](references/sites/upload-static-site.md)
-Get a user's ready-made website live on Wix when they already have the site files — an index.html, a zip, or a static build exported from an AI builder or any other tool — by sending them to the Wix Headless drop page, where they upload the files and instantly get a live hosted site they can claim into their account. Use whenever the user wants to upload, publish, or host their own HTML/CSS/JS files as a NEW site. Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
+Publish a user's ready-made website — an index.html, a static build, or a zip exported from an AI builder or any other tool — as a new live Wix site. Covers both ways to get there — handing the user the Wix Headless drop page, and calling the Wix Headless instant-site REST API yourself when you can reach the files and make outbound HTTPS requests. When you also hold the user's identity, covers putting the published site straight into their Wix account and reading back its final live URL. Use whenever the user wants to upload, publish, deploy, or host their own HTML/CSS/JS as a NEW site, including files generated for them earlier in the conversation, or to update a site already published this way (iterate on the same site instead of creating another). Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
 
 ---
 

package/skills/wix-manage/references/bookings/create-and-update-booking-services.md

@@ -201,6 +201,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "Consultation",
       "type": "APPOINTMENT",
@@ -234,6 +235,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "Free Consultation",
       "type": "APPOINTMENT",
@@ -264,6 +266,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "Yoga Class",
       "type": "CLASS",
@@ -283,7 +286,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   }'
 ```
 
-After creation, use the `service.schedule.id` from the response to create class events with `bulkCreateEvents` (see Step 3).
+After creation, use `results[0].item.schedule.id` from the response to create class events with `bulkCreateEvents` (see Step 3). This requires `returnEntity: true` on the request — without it the response carries only `results[0].itemMetadata.id`, which has no `schedule.id`; and the created service is directly under `item` (there is no `item.service`).
 
 **Required Fields:**
 

package/skills/wix-manage/references/bookings/create-appointment-service.md

@@ -109,6 +109,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -142,6 +143,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -171,7 +173,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - `schedule.availabilityConstraints.sessionDurations` sets the appointment length
 - Availability is based on the assigned staff member's working hours schedule
 
-Save the `serviceId` from the response: `results[0].item.service.id`
+Save the `serviceId` from the response: `results[0].item.id` (the created service is directly under `item` — there is no `item.service`). This requires `returnEntity: true` on the request; without it the response carries only `results[0].itemMetadata.id`.
 
 ---
 

package/skills/wix-manage/references/bookings/create-class-service.md

@@ -96,6 +96,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -124,6 +125,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -149,7 +151,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - `defaultCapacity` is **required** — sets max participants per session
 - After creation, class sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
 
-**Response:** Save the service ID from `results[0].itemMetadata.id`
+**Response:** Save the service ID from `results[0].item.id` and the schedule ID for `bulkCreateEvents` from `results[0].item.schedule.id` (the created service is directly under `item`). This requires `returnEntity: true` on the request — without it the response carries only `results[0].itemMetadata.id`, which has no `schedule.id`.
 
 ---
 

package/skills/wix-manage/references/bookings/create-course-service.md

@@ -101,6 +101,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -129,6 +130,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -157,8 +159,8 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - After creation, course sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
 - If the user asked you to create the course and gave the session count/times, the job is not complete after `bulkCreateServices`; continue by creating the Calendar events, then verify the service has future events before telling the user it is ready
 
-Save the `serviceId` from the response: `results[0].item.service.id`
-Save the `service.schedule.id` from the response for the follow-up `bulkCreateEvents` request.
+Save the `serviceId` from the response: `results[0].item.id` (the created service is directly under `item` — there is no `item.service`). This requires `returnEntity: true` on the request; without it the response carries only `results[0].itemMetadata.id`.
+Save the `service.schedule.id` from the response (`results[0].item.schedule.id`) for the follow-up `bulkCreateEvents` request.
 
 ---
 

package/skills/wix-manage/references/bookings/end-to-end-booking-flow.md

@@ -1,11 +1,68 @@
 ---
 name: "End-to-End Booking Flow"
-description: Complete booking flow from service discovery to payment. Query services, check availability with Time Slots V2, create bookings, and process payment via eCommerce checkout.
+description: Books and settles appointments, classes and courses with the site owner's credentials — an operator managing bookings, or server-side code booking as the owner. Covers service discovery, availability with Time Slots V2, creating the booking, and settling it by direct confirmation or eCommerce checkout. A visitor booking for themselves needs a visitor token instead; this recipe links that path.
 ---
 
 # End-to-End Booking Flow (REST)
 
-Step-by-step flow for implementing a complete booking experience using REST APIs.
+Step-by-step flow for creating and settling bookings **with the site owner's credentials** —
+see who that covers, and where visitor-facing code goes instead, immediately below.
+
+> ## ⚠️ These are owner-side calls, not visitor-facing code
+>
+> Every call below runs with the **site owner's credentials** — an API key or the site's admin
+> token. That covers two situations, and both are this recipe:
+>
+> - an **operator managing bookings**, calling these APIs from a script, a management tool, or a
+>   back-office screen
+> - **server-side code in a site or app acting as the owner** — a backend function booking a
+>   client in, a scheduled job, a webhook handler
+>
+> Either way the booking belongs to the site, not to the person being booked.
+>
+> **Building a site or app where a visitor books for themselves? These payloads are right, the
+> identity is not.** A visitor's booking and checkout run on an **anonymous visitor token** minted
+> from the site's OAuth app client id. Using the owner's credentials for a visitor's purchase
+> produces a checkout that belongs to the site: no cart persistence, no abandoned-checkout
+> recovery, and no attribution to the customer. Read these first:
+>
+> - [Book an Appointment](https://dev.wix.com/docs/api-reference/business-solutions/bookings/skills/book-an-appointment)
+>   — the same flow from the visitor's side: visitor token, slot re-validation, booking form
+>   fields, checkout hand-off, and eight pitfalls from real conversations
+> - [Retrieve Tokens](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens)
+>   — minting and refreshing the anonymous visitor token
+> - [Allow Redirect URIs and Domains](https://dev.wix.com/docs/go-headless/authentication/setup/allow-redirect-uris-and-domains)
+>   — registering your URLs so the visitor returns to your app after the Wix-hosted checkout
+> - [Manage OAuth Apps](../sites/manage-oauth-apps.md) — creating the OAuth app, whose id is the
+>   `client_id` the frontend mints visitor tokens from
+> - [Bookings Quick Start](https://dev.wix.com/docs/go-headless/self-managed-headless/tutorials/java-script-sdk-tutorials/bookings-quick-start)
+>   — the same flow through the JavaScript SDK on a headless site
+>
+> Mixed apps are normal: the owner's credentials manage the catalog, staff, policies and coupons
+> (the recipes here), while the visitor's own token books and pays.
+
+## Contents
+
+1. [Query Available Services](#step-1-query-available-services) — `POST /bookings/v2/services/query`.
+   The three service types and how each one changes the rest of the flow, plus the four fields to
+   carry forward: `id`, `schedule.id`, `type`, `staffMemberIds`.
+2. [Check Availability](#step-2-check-availability) — `POST /_api/service-availability/v2/time-slots`.
+   Time Slots V2 replaces the deprecated Availability Calendar. Dates must be full local
+   datetimes or the call 400s; `availableResources` stays empty unless you ask for it by resource
+   type; the `location.locationType` a slot returns is **not** the value Create Booking accepts.
+   Classes come from a different endpoint and carry an `eventId`.
+3. [Create the Booking](#step-3-create-the-booking) — `POST /_api/bookings-service/v2/bookings`.
+   One payload shape per service type: appointments need every slot field spelled out, classes
+   need only the service and event ids and derive the rest, courses book a whole schedule.
+   Participants are `totalParticipants` **or** `participantsChoices`, never both. The booking
+   lands as `CREATED` and is not on the calendar until step 4.
+4. [Confirm or Process Payment](#step-4-confirm-or-process-payment) — two branches. Free and
+   pay-at-location bookings are confirmed directly with a payment status. Paid bookings go into a
+   cart that references the booking id, and whoever is paying is sent to its checkout URL; a
+   server-to-server place-order path skips the payment page entirely, which only fits an operator
+   or backend job booking someone in.
+5. [Service Type Summary](#service-type-summary) — appointment, class and course side by side:
+   which `bookedEntity` each uses, which availability API feeds it, and what makes it different.
 
 ## Prerequisites
 
@@ -256,7 +313,15 @@ Use the booking ID as `catalogItemId` with the Wix Bookings app ID. Save `cart.i
 
 Redirect the user to the returned `checkoutUrl`. After payment, the booking is automatically confirmed.
 
-**4c. Place Order (alternative, server-to-server)**
+> When the person paying is a visitor, create the cart and this URL **with their visitor token**,
+> not the owner's credentials — see the note at the top. The call succeeds either way, which is
+> what makes it easy to get wrong.
+
+**4c. Place Order — no payment page (alternative, server-to-server)**
+
+> This one only makes sense on the owner's side: it creates the order outright, with nobody
+> visiting a payment page. Right for an operator or backend job booking someone in; not a way to
+> charge a visitor, who still has to be sent to checkout.
 
 First calculate the cart to get a price-verification token:
 

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-seasonal-promotion.md

@@ -1,6 +1,6 @@
 ---
 name: "Flow: Seasonal Promotion"
-description: SEASONAL sub-flow — load [Goal: Seasonal Revenue] FIRST (it owns classification and routing); this is a sub-step, NOT a direct entry from README.
+description: "SEASONAL sub-flow — load [Goal: Seasonal Revenue] FIRST (it owns classification and routing); this is a sub-step, NOT a direct entry from README."
 ---
 # Flow: Seasonal Promotion
 

package/skills/wix-manage/references/google-ads/manage-campaign-success-guide.md

@@ -1,39 +1,45 @@
 ---
 name: "Manage a Campaign Success Guide"
-description: "Retrieves and manages the campaign success guide for an existing Wix Google Ads Performance Max Leads campaign. Offer it after creating a supported campaign, even while it is learning or has no metrics; that proactive offer requires approval before retrieval. A direct request to improve a campaign, see what to fix next, or show the guide is already approval to retrieve it. Also use when a user reports completing or wants to reopen a guide item. Treat a clear completion report as an actionable update request even when phrased as a statement. Covers campaign selection, prioritized guide retrieval, and suggestion status updates without redundant confirmation. REST base https://www.wixapis.com/pa-platform/suggestions/v1."
+description: "Campaign Success Guide for existing Wix Google Ads Performance Max Leads campaigns. Use after creating a supported campaign, even while it is learning or has no metrics, and whenever users ask how to improve a campaign, what to fix next, to view the guide, or to mark or reopen a recommendation. Covers campaign and site selection; prioritized actionable recommendations; deduplicated, destination-specific Editor and Google Ads navigation; offers to perform supported work after approval; Merchant Center and Business Profile connection follow-ups; and suggestion-status tracking."
 ---
 # RECIPE: Manage a Campaign Success Guide
 
-A campaign success guide is a prioritized list of improvements for an **existing** Google Ads `PERFORMANCE_MAX_LEADS` campaign. Offer it as a useful next step after [creating a Performance Max campaign](create-performance-max-campaign.md). Once Create Campaign returns the campaign ID, ask whether the user wants to retrieve the guide; call the API only after they approve. There is no need to wait for the campaign to leave `LEARNING` or generate performance metrics because the guide analyzes the landing page, campaign configuration, and relevant site connections rather than depending on campaign performance data.
-
-Also use this recipe for requests such as "How can I improve my campaign?", "What should I fix next?", "Show my campaign success guide", "I made the call-to-action button clearer as the success guide recommended", "Mark this recommendation complete", or "Reopen that guide item."
+A campaign success guide is a prioritized list of improvements for an **existing** Google Ads `PERFORMANCE_MAX_LEADS` campaign. Offer it as a useful next step after [creating a Performance Max campaign](create-performance-max-campaign.md). Once Create Campaign returns the campaign ID, ask whether the user wants to retrieve the guide; call the API only after they approve. The guide does not use campaign performance metrics. It evaluates landing-page content, campaign configuration, and Wix site connections, so `LEARNING` status and an empty analytics history do not block it.
 
 A direct request to improve a campaign, see what to fix next, or show its success guide is itself approval to retrieve the guide once the campaign is identified. Do not ask whether the user wants the guide after they have already made one of those requests. Separate approval is needed only when you proactively offer the guide after campaign creation.
 
-This differs from [Get AI Campaign Suggestions](get-campaign-suggestions.md), which generates keywords, budgets, locations, copy, images, and other inputs used while **building** a campaign. Do not route pre-campaign keyword, budget, creative, or targeting generation here.
+Treat a broad request such as "How can I improve my Google Ads campaign?" as a Campaign Success Guide request for an existing campaign. Route here before offering generic optimization advice, querying analytics, or generating the pre-campaign inputs covered by Get AI Campaign Suggestions. If the conversation does not identify a Wix site or campaign, explain that you will use the guide and ask one focused question that resolves the missing identity; do not probe site-scoped APIs first.
 
-Base URL: `https://www.wixapis.com/pa-platform/suggestions/v1`. `<AUTH>` is the `Authorization` header; body calls also need `Content-Type: application/json`.
+This differs from [Get AI Campaign Suggestions](get-campaign-suggestions.md), which generates keywords, budgets, locations, copy, images, and other inputs used while **building** a campaign. Do not route pre-campaign keyword, budget, creative, or targeting generation here.
 
 ## Resolve the campaign
 
-The guide endpoints require a campaign UUID, but users often provide only a campaign name or say "my campaign."
+The guide endpoints require a campaign UUID, but users often provide only a campaign name or say "my campaign." Google Ads calls operate on the current Wix site from the call context; the site is not a request-body field. Use an already-selected site context without asking the user to repeat it. If there is no unambiguous current site, ask which site to use instead of probing several sites. Follow the rest of this resolution flow only when retrieving or updating a guide. If the conversation already contains the guide recommendations and the user only wants them presented, do not block the action plan on campaign identity; resolve only the site context needed for relevant navigation.
 
-1. If the user provides a campaign UUID, use it.
-2. Otherwise follow [Manage Campaign Lifecycle](manage-campaign-lifecycle.md) and call:
+Site listing is for resolving navigation metadata only. Never use account-wide site listing to hunt for a campaign before retrieving or updating a guide. A current-site ID in the available context counts as an unambiguous selected site even when the user's prompt does not repeat its name. If no current-site ID is available, ask which site to use.
+
+1. If the campaign UUID is known, use it in the current site context.
+2. Otherwise, list campaigns once for the current site using the Campaign API's public serverless route:
 
    ```bash
-   curl -X GET 'https://www.wixapis.com/google-ads/v1/campaigns' \
+   curl -X GET 'https://www.wixapis.com/_serverless/pa-google/v1/campaigns' \
      -H 'Authorization: <AUTH>'
    ```
 
+   Use this full URL exactly once. The `/_serverless/pa-google` prefix is part of the public endpoint. Do not retry with a relative URL or another service prefix, or probe another site when the documented call returns an error.
+
    Read each campaign's `id`, `name`, `campaignType`, and `status`.
-3. Select a campaign only when one result clearly matches the user's wording. If none or multiple plausibly match, show concise choices and ask the user to choose; never guess.
+3. Select a campaign only when one result clearly matches the user's wording. If several campaigns on that site plausibly match, show concise campaign choices and ask the user to choose; never guess.
 4. Continue only for `campaignType: "PERFORMANCE_MAX_LEADS"`. If the selected campaign has another type, explain that campaign success guides currently support Google Ads Performance Max Leads campaigns only. For a supported campaign, do not gate guide retrieval on `status` or query analytics first: `LEARNING` and missing performance metrics are not reasons to wait.
 
 The common flow always sends `platformType: "GOOGLE"`; do not ask the user to provide it.
 
 ## Retrieve or create the guide
 
+Skip this call when the conversation already contains a retrieved guide or its recommendations; immediately present the supplied result using the next section instead of retrieving it again or asking for campaign identity. When the user paraphrases recommendation labels, map them to the closest unambiguous suggestion types in the translation table. Wording such as "still need to" or "still to do" means those items are `OPEN`.
+
+When the user only wants a supplied guide presented, this article already contains the response behavior. Do not read the linked action recipes until the user accepts an offer to perform that action; unnecessary recipe reads delay the answer and can prevent the navigation block from being returned.
+
 ```bash
 curl -X POST \
   'https://www.wixapis.com/pa-platform/suggestions/v1/campaign-success-guides/get-or-create' \
@@ -67,6 +73,76 @@ Present only the suggestions the API returns and preserve their order; `suggesti
 
 `OPEN` means pending action. `COMPLETED` means the user marked the item completed; it does **not** mean the API changed the site or campaign for them.
 
+## Present the guide as an actionable plan
+
+Do not return a bare list of task labels. Turn the returned suggestions into a compact action plan while preserving the API's order:
+
+Use this output structure:
+
+1. A numbered suggestion list with no navigation URLs or Markdown links inside the suggestion items.
+2. One grouped offer for the supported work the agent can perform after approval.
+3. A **Next actions** block after the complete suggestion list and offer, containing each relevant destination link exactly once.
+
+This structure is mandatory even when only one suggestion uses a destination. Never put the Editor, Google Ads, or another shared navigation link inline with a suggestion.
+
+1. Name the campaign and link `campaignSuccessGuide.url` as the analyzed landing page when present.
+2. For every returned suggestion, show its user-facing label, tracking status (`Pending` for `OPEN`, `Marked complete` for `COMPLETED`), and one concrete next step. Do not show enum values unless they help resolve an ambiguity.
+3. For each `OPEN` item, distinguish work the agent can help perform from work the user must finish in Wix. Prefer an offer to do supported work over instructions that make the user do the same operation manually.
+4. Do not offer work for `COMPLETED` items unless the user asks to reopen them.
+5. Put each unique navigation link after the suggestions as a destination-specific CTA. Do not group every URL under a generic **Open in Wix** label or reuse that label for unrelated destinations. Name the actual page or action—for example, **Go to Editor**, **Go to Google Ads**, or **Connect Google Business Profile**. Deduplicate by destination: if two or ten tasks require the Editor, include the Editor CTA **once**, at the bottom, and never repeat it beside individual tasks. Apply the same deduplication to the Google Ads dashboard or any other shared destination.
+
+The navigation block is part of the guide, including when the user supplied or paraphrased the recommendations. Before responding, resolve the destinations required by the `OPEN` items. Resolving navigation is read-only and does not require approval, including when the user says not to change anything yet. Use the selected site's `id` and `editUrl` from available site context. If the current-site ID is known but `editUrl` is absent, look up the site's navigation metadata through an available site-listing capability once; select only the result whose `id` or `metaSiteId` exactly matches that current-site ID, then read its `displayName`, `editUrl`, and `editorType`. Do not inspect other sites for campaigns. When no current-site ID is known and the lookup returns exactly one site, use it for navigation. When several sites are available and none is selected, present the action plan immediately and ask which site's CTAs to add. If an item belongs in the Editor or Google Ads, include that destination once unless the destination is genuinely unavailable; do not omit navigation merely because no API call was needed to obtain the guide.
+
+### Which action to offer
+
+| Suggestion types | Response behavior |
+| --- | --- |
+| `CLEAR_CTA_COPY`, `ABOVE_THE_FOLD_CTA`, `HEADER_MATCH`, `CONVERSION_POINT`, `GOOGLE_REVIEWS`, `TESTIMONIAL`, `CONTACT_AND_CREDIBILITY`, `FAQ_SECTION`, `MINIMIZE_FORM_FIELDS`, `SOCIAL_CHANNELS` | These change visible landing-page content. Briefly describe the edit and point to the single **Go to Editor** CTA after the suggestions. If the current environment has a site-editing capability that can safely make the specific change, offer to make it after the user approves; otherwise do not imply that marking the suggestion complete will edit the page. |
+| `MOBILE_OPTIMIZATION`, `SITE_SPEED` | Offer to inspect the problem and recommend a concrete fix first; these broad findings are not a safe one-click mutation. Include the single Editor link when the resulting work belongs there. Do not promise an improvement before identifying the actual cause. |
+| `GOOGLE_ADS_SEARCH_THEMES` | Offer to generate relevant search themes, show the proposed set, and apply the approved set to the existing campaign by following [Get AI Campaign Suggestions](get-campaign-suggestions.md) and [Manage Campaign Lifecycle](manage-campaign-lifecycle.md). Updating the campaign is a mutation, so do not apply themes merely because the guide returned this item. |
+| `GOOGLE_MERCHANT_CENTER_CONNECTION` | Offer to link the Merchant Center account using the account flow below. Reuse an already-linked Merchant Center account ID when present; otherwise ask the user for the ID. Get approval before the account update. Explain that the link begins as `PENDING` and its owner may still need to approve it in Google. |
+| `GOOGLE_BUSINESS_PROFILE_CONNECTION` | Offer to check the connection and start it by following [Connect a Wix Site to Google Business Profile](../google-business-profile/connect-google-business-profile.md). Be explicit that the agent can initiate the flow and provide its authorization URL, but the site owner must finish Google's consent in their browser. |
+
+After the tasks, make one closing offer that groups the supported actions you can take; do not append a separate approval question to every item.
+
+For a Merchant Center connection, first read the selected site's Google Ads account:
+
+```bash
+curl -X GET 'https://www.wixapis.com/_serverless/pa-google/v1/accounts/current-site' \
+  -H 'Authorization: <AUTH>'
+```
+
+Read `account.id`, `account.merchantCenterAccountId`, and `account.merchantCenterAccountLinkStatus`. If `merchantCenterAccountId` is present, use it as the existing connection context. If it is absent, ask the user for the account ID shown in Google Merchant Center; the Google Ads account API does not list candidate Merchant Center accounts. After the user confirms the ID and approves the mutation, follow [Install Google Ads and Create an Account](install-and-create-account.md) and update `merchantCenterAccountId` on `account.id`.
+
+### Build destination-specific CTAs
+
+- **Editor:** Include this only when at least one returned `OPEN` item requires landing-page or mobile editing. Use the exact `editUrl` from the selected site context or the single matching result from the site-navigation lookup described above; prefix a relative value with `https://manage.wix.com`. Never construct or guess an Editor URL, and do not substitute the public landing-page URL for an Editor link. If the site is `EDITORLESS` or has no `editUrl`, say that an Editor link is unavailable instead of inventing one. Label the CTA **Go to Editor** or name the more specific editing action; do not label it **Open in Wix**.
+- **Google Ads:** When a returned item belongs in Google Ads, use the verified route from [Google Ads Dashboard Navigation](google-ads-dashboard-navigation.md): `https://manage.wix.com/dashboard/{metaSiteId}/google-ads`. Label the CTA **Go to Google Ads** or name the specific campaign action.
+- **Other destinations:** Name the destination or action in the CTA, such as **Open Forms dashboard**, **Review site speed**, or **Connect Google Business Profile**. Never make several unrelated links look like the same generic action.
+- Include only relevant destinations and list each URL once. Authorization URLs created by a later connection flow are task-specific; return one only after the user accepts that offer and the flow creates it.
+
+Example when several tasks share the Editor:
+
+```markdown
+## Campaign success guide
+Landing page: [Request a quote](https://www.example.com/request-a-quote)
+
+1. **Clarify the main call to action — Pending**
+   Make the button describe the conversion, such as “Request a quote.”
+2. **Move a call to action above the fold — Pending**
+   Place the primary button where visitors see it without scrolling.
+3. **Configure Google Ads search themes — Pending**
+   **I can help with this:** I can propose relevant themes and apply the set you approve.
+
+I can take care of the search-theme update after you review the proposed set.
+
+### Next actions
+- [Go to Editor]({editUrl})
+- [Go to Google Ads](https://manage.wix.com/dashboard/{metaSiteId}/google-ads)
+```
+
+Each link has its own destination-specific CTA, and the Editor URL appears once even though the first two recommendations both use it.
+
 ## Translate suggestion types for the user
 
 Keep the enum value unchanged in API calls, but use these labels when explaining the guide:
@@ -95,9 +171,9 @@ The update endpoint identifies the suggestion by its **`type`**, not its suggest
 
 Before executing an update:
 
-1. Identify the campaign and a suggestion `type` currently present in its latest guide.
+1. Identify the campaign and a suggestion `type` currently present in its latest guide. Use the current-site ID directly and follow the campaign-resolution flow above; listing that site's campaigns once is valid context resolution, but account-wide site listing is not. Ask one focused site or campaign question only when the current context or campaign results leave more than one plausible target. Do not probe several sites or guess, because the same recommendation type can exist on multiple campaigns.
 2. Match the user's wording to one returned suggestion and infer the requested status only when it is clear: a statement that they completed the recommendation means `COMPLETED`; a request to reopen it means `OPEN`.
-3. Execute immediately when the campaign, suggestion, and status are unambiguous. Ask one targeted clarification only when any of them is unclear; never guess.
+3. Execute immediately when the campaign, suggestion, and status are unambiguous. The completion statement is approval for this tracking-status update; do not ask a redundant confirmation question. Ask one targeted clarification only when identity, suggestion, or intended status is unclear; never guess.
 
 Mark an item completed:
 
@@ -112,6 +188,24 @@ curl -X POST \
   }'
 ```
 
+```json
+{
+  "campaignSuccessGuide": {
+    "id": "7d4a9c2e-86f1-4b37-a2d5-9e18c6f043ab",
+    "suggestions": [
+      {
+        "type": "CLEAR_CTA_COPY",
+        "status": "COMPLETED"
+      },
+      {
+        "type": "FAQ_SECTION",
+        "status": "OPEN"
+      }
+    ]
+  }
+}
+```
+
 Reopen the same item by sending:
 
 ```json
@@ -132,7 +226,7 @@ If a mutation times out with an unknown outcome, do not retry automatically. Ret
 | `PLATFORM_NOT_SUPPORTED` | Use `GOOGLE`; do not substitute another platform value. |
 | `CAMPAIGN_TYPE_NOT_SUPPORTED` | Explain that success guides currently support Google Ads Performance Max Leads campaigns only. |
 | `SUGGESTION_NOT_FOUND` | Retrieve the latest guide and choose a `type` actually present; do not keep retrying stale data. |
-| Authentication or permission error | Stop after the first rejected campaign or guide call and explain that the current collaborator cannot access or modify it. Do not try alternate base URLs, infer that Google Ads is not installed, or probe other endpoints to bypass authorization. |
+| Authentication or permission error | Stop after the first rejected campaign or guide call and explain that the current collaborator cannot access or modify it. Do not try alternate base URLs, infer that Google Ads is not installed, or probe other sites or endpoints to bypass authorization. |
 
 ## References
 

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

@@ -1,6 +1,6 @@
 ---
 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.
+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