@wix/agent-skills 1.17.0 → 1.18.1

package/skills/wix-manage/references/forms/forms-dashboard-navigation.md

@@ -1,6 +1,6 @@
 ---
 name: "Forms Dashboard Navigation"
-description: "Builds direct links to Wix Forms dashboard pages on manage.wix.com — the forms list, the submissions table, the form builder for a specific form, standalone forms, templates, and forms settings. Pairs each main Forms entity (form, submission) with its read API so you can fetch an entity and hand back a 'view it in your dashboard' link. 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."
+description: "Builds direct links to Wix Forms dashboard pages on manage.wix.com. The paths are not guessable and appear in no API reference, so take them from here: under `https://manage.wix.com/dashboard/{metaSiteId}/`, the forms list is `wix-forms`, a form's builder is `wix-forms/form/{formId}`, and that form's submissions are `wix-forms/form/{formId}/submissions` — there is no site-wide submissions page, and nothing lives under `contacts/forms`, `forms`, `form-builder` or `wix-forms-and-payments` (the legacy app). Also standalone forms, and each Forms entity paired with its read API so you can fetch one and hand back a 'view it in your dashboard' link."
 ---
 
 # Forms Dashboard Navigation
@@ -9,36 +9,39 @@ Build direct links into the Wix Forms pages of a site's dashboard. For the gener
 
 ## Main Pages
 
+**Never goess or answer a Forms dashboard-link request from memory** because the routes below are the only correct ones.
+
 | Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
 |---|---|---|
 | Forms list | `wix-forms` | All forms on the site |
 | Form builder | `wix-forms/form/{formId}` | Edit a specific form (fields, rules, submit settings) |
+| Submissions | `wix-forms/form/{formId}/submissions` | That form's submissions table |
 | Standalone form | `wix-forms/standalone-form` | Create a standalone form (has its own shareable page, not embedded in a site page) |
-| Submissions | `wix-forms-and-payments/submissions` | Submissions table across forms |
-| Templates | `wix-forms-and-payments/templates` | Create a form from a template |
-| Forms settings | `wix-forms-and-payments/settings` | Forms-level settings |
 
-Two URL namespaces appear here because the forms management pages and the form builder are registered by two apps (`14ce1214-b278-a7e4-1373-00cebd1bef7c` and `225dd912-7dea-4738-8688-4b8c6955ffc2`); `wix-forms` also redirects to the forms list, so it's the stable entry point.
+**Every Forms page is under `wix-forms`** — the namespace **Wix Forms (New)** `225dd912-7dea-4738-8688-4b8c6955ffc2` registers, the app that owns the Form Schemas v4 API. A `wix-forms-and-payments/...` path belongs to the legacy **Wix Forms (Old)** app `14ce1214-b278-a7e4-1373-00cebd1bef7c`: don't build one, and never install or target that app (see [Create Form](./create-form.md) § Silent breakers).
+
+**Submissions are per form**, hanging off that form's builder path — there is no site-wide submissions page to link to. With no `{formId}` in hand, link the forms list and let the owner pick.
 
-Entity-specific links (`{formId}`) accept the entity's ID appended as an extra path segment. Query params can follow.
+Entity-specific links (`{formId}`) take the entity's ID as a path segment, and query params can follow. The dashboard appends its own view state to the submissions URL — `folder` (a JSON-encoded breadcrumb), `sort` (e.g. `createdDate+desc`) and `selectedColumns` (a comma-separated list of field **`target`**s) — none of which you need to construct: the bare path opens the table with the owner's defaults.
 
 ## Pairing Entities with Their Read APIs
 
-Fetch the entity via REST, then link the matching dashboard page. All calls use `https://www.wixapis.com` with an `Authorization` header. Dashboard forms use the `wix.form_app.form` namespace.
+Fetch the entity via REST, then link the matching dashboard page. All calls use `https://www.wixapis.com` with an `Authorization` header. Dashboard forms live in the **`wix.form_app.form`** namespace — every Forms call that takes a namespace, as a query parameter or inside a filter, takes that exact value.
 
 | Entity | Read API | Dashboard link |
 |---|---|---|
 | Form | `GET /form-schema-service/v4/forms` · `POST /form-schema-service/v4/forms/query` · `GET /form-schema-service/v4/forms/{formId}` | `wix-forms/form/{formId}` (edit) or `wix-forms` (list) |
-| Submission | `POST /form-submission/v4/submissions/namespace/query` (filter must include the `namespace`) · `GET /form-submission/v4/submissions/{submissionId}` | `wix-forms-and-payments/submissions` |
+| Submission | `POST /form-submission-service/v4/submissions/namespace/query` (the filter must carry `"namespace": "wix.form_app.form"`) · `GET /form-submission-service/v4/submissions/{submissionId}` | `wix-forms/form/{formId}/submissions` — the `formId` comes off the submission |
 
 Example — after creating a form, hand back its links:
 
 ```
 Created "Contact Form".
 Edit it here: https://manage.wix.com/dashboard/{metaSiteId}/wix-forms/form/{formId}
-See submissions: https://manage.wix.com/dashboard/{metaSiteId}/wix-forms-and-payments/submissions
+See submissions: https://manage.wix.com/dashboard/{metaSiteId}/wix-forms/form/{formId}/submissions
 ```
 
 ## Notes
 
-- Creating forms via the [Create Form](./create-form.md) recipe (Form Schemas API) makes them appear in the forms list above.
+- Creating forms via the [Create Form](./create-form.md) recipe (Form Schemas API) makes them appear in the forms list above — **but only when the form was created under the `wix.form_app.form` namespace with Wix Forms (New) installed.** A form created under any other namespace is reachable over the API and completely absent from these pages.
+- **Before handing back a `wix-forms/form/{formId}` link, confirm the form actually renders**: `GET https://www.wixapis.com/form-schema-service/v4/forms/{formId}/summary` must return a non-empty `formSummary.fields` whose count matches every input field. An empty summary means the owner will open this link to a blank form (Create Form, STEP 3).

package/skills/wix-manage/references/forms/update-form.md

@@ -0,0 +1,122 @@
+---
+name: "Update Form"
+description: "Changes a Wix form that already exists, with Form Schemas v4 `PATCH` — add a field to my form, add a dropdown, make a field required or optional, rename a label, reorder or retire a question. Covers reading the form back for its `revision` (and the required `namespace` query parameter), the whole-form body that a `PATCH` needs, the wholesale `formFields` replace that silently soft-deletes anything you omit, changing a field's component type in place, retiring a field that already has submissions, and the read-back that proves what was stored. Use whenever the form exists and the request changes what it collects; use Create Form when there is no form yet."
+---
+# RECIPE: Update a Wix Form
+
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`. Send `wix-site-id: <SITE_ID>` when the token is account-scoped.
+
+Change what a form collects — **add a field, relabel one, tighten a rule, reorder, retire one** — on a form that already exists. **Composing the field itself is not here**: [About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields) owns the `identifier` / `inputType` / `componentType` table and the options/enum shapes, and [Create Form](./create-form.md) § Silent breakers apply to an added field exactly as to a created one.
+
+**A `PATCH`, never a delete-and-recreate.** An update keeps the `formId` everything downstream already holds — a frontend binding, an automation, a saved dashboard view — and spends no slot against the site's form cap.
+
+---
+
+## The call
+
+```bash
+# 1 · read the form back: you need its current revision, and every field you intend to keep
+curl -X GET \
+  'https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&formIds={formId}' \
+  -H 'Authorization: <AUTH>'
+
+# 2 · send that form back with your change applied
+curl -X PATCH \
+  'https://www.wixapis.com/form-schema-service/v4/forms/{formId}' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{ "form": {
+      "id": "{formId}",
+      "revision": "<the revision you just read>",
+      "name": "<the form name>",
+      "namespace": "wix.form_app.form",
+      "formFields": [ ...every field, with your change applied... ],
+      "steps": [ ...every step, with the layout item for a new field... ]
+  } }'
+```
+
+- **⚠️ `namespace` is a REQUIRED query parameter on the read, and this is what a revise run trips over.** Without it the read returns `400 namespace has size 0, expected 10 or more, namespace must not be empty` — a violation naming a *field*, so it reads like a body problem. Fix the call, don't reshape the payload. (The filter on `POST .../v4/forms/query` needs it too.)
+- **The read-back is the body.** Apply your change to what the `GET` returned and send that as `form`. `namespace` is **immutable** and travels along; **there is no `fieldMask`**, and no `revision` outside `form` — inventing either is a silent partial write.
+- **⚠️ Append to `formFields`; never rebuild the entries you read.** `[...form.formFields, newField]` works. Mapping the array to "clean up" each field — dropping `fieldType`, re-shaping an options block — fails with `fieldType cannot be provided with any these fields: input_options, display_options` on **every** field at once. The read-back's field objects are already a valid write shape: pass them through untouched and touch only the one field you are changing.
+- **`formFields` is replaced wholesale.** Wix: *"Any field that's missing from the array you send is moved to `deletedFormFields`, so resend every field you want to keep."* Same for `steps[].layout` — miss an item and that field goes unplaced, which renders empty. Drops are recoverable from `deletedFormFields`, but nothing announces them.
+- **A stale `revision` is rejected** — re-`GET` and re-apply; never guess or increment it.
+- **Plan caps apply to an added field.** `Field count reached its limit of N` on a `PATCH` is the site's premium cap: reduce or upgrade, with the choice put to the user ([Create Form](./create-form.md) § Plan caps). Never split the form across schemas to dodge it.
+
+---
+
+## Adding a field
+
+**Start by reading [About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields) § Field types and § Choice fields** for the field kind you're adding: it gives the `identifier` / `inputType` / `componentType` triple — take all three from one row, and note that a dropdown or radio is `inputType: "STRING"` — plus the options/enum shape and the GUID every option needs. [Create Form](./create-form.md) § Choice fields carries a complete dropdown body to copy. Composing a field from memory is what turns one `PATCH` into eight.
+
+Then four things are yours to generate:
+
+- **`id`** — a fresh lowercase GUID (`uuidgen | tr 'A-Z' 'a-z'`), unique in the form.
+- **`target`** — the immutable submission key, unique across the form: snake_case plus a short random suffix (`job_industry_7f2b`). **A duplicate `target` is accepted and silently stores nothing** for every field but one.
+- **one GUID per choice option** — `options[]` each need their own, exactly like the field's; a readable slug is rejected ([Create Form](./create-form.md) § Choice fields). Generate them with `uuidgen`, never by hand.
+- **the choices, declared twice** — every option needs `id` + `value` + `label`, and `validation.enum` must list every one of those `value`s. **An empty `validation` is a free-text field, not a dropdown**; the general "always include `validation`, even as `{}`" rule does not apply here, and getting it wrong is accepted with a `200`.
+- **the layout item** — append to `steps[<n>].layout.large.items`, mirroring into `medium` / `small` if the form has them:
+
+```json
+{ "fieldId": "<the new field's id>", "row": <next row>, "column": 0, "width": 12, "height": 1 }
+```
+
+A field missing from the layout isn't dropped, but it sorts last and has no defined position in the owner's builder. To place it mid-form, insert at that `row` and bump every item at or after it — `row` restarts at 0 in each step.
+
+**A choice field's `identifier` is its kind** — `DROPDOWN`, `RADIO_GROUP`, `CHECKBOX_GROUP`, `TAGS` — never `TEXT_INPUT`, which is accepted and stored as a plain text input ([Create Form](./create-form.md) § Choice fields).
+
+---
+
+## The other changes
+
+| Change | How |
+|---|---|
+| Label, placeholder, options, validation, order | Patch them and stop — nothing downstream needs updating |
+| A field's component type, in place | Send that field with the **choice `identifier`** and only the new options block; leaving `textInputOptions` beside `dropdownOptions` reads back as the text-input fallback |
+| Retire a field the form has submissions for | Set `hidden: true` — "hidden from submitters": the field stops rendering, and the submissions already collected under it keep their meaning. Dropping it from the array soft-deletes it instead |
+| Remove a field added by mistake this run | Drop it from `formFields`; it lands on `deletedFormFields` |
+| Rename a `target` | **Never.** It is the storage key, so a rename orphans every submission already collected under the old one. Change the *label* instead |
+
+---
+
+## Verify — an update regresses a form exactly as a create can
+
+**A `200` on the `PATCH` proves the body parsed, nothing about what was stored.** Read the form back, every time:
+
+```
+GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&formIds={formId}
+GET https://www.wixapis.com/form-schema-service/v4/forms/{formId}/summary
+```
+
+Assert on that read-back, not on the `PATCH` response:
+
+- the changed field is there, carrying the `identifier` and `componentType` you sent — **a choice field with a non-empty `options[]`**, which is where a dropdown that degraded to a text input shows up;
+- every field you meant to keep is still present, and every `inputOptions.required` still reads back as sent;
+- `formSummary.fields` still holds one entry per input field — that is what the owner's dashboard renders.
+
+Then hand back the dashboard links ([Forms Dashboard Navigation](./forms-dashboard-navigation.md)): the form builder at `wix-forms/form/{formId}`, and that form's submissions at `wix-forms/form/{formId}/submissions`. New submissions carry the new field; past ones don't.
+
+---
+
+## Troubleshooting
+
+| Error / symptom | Cause | Fix |
+|---|---|---|
+| `400 namespace has size 0, expected 10 or more` / `namespace must not be empty` on a read | The `namespace` **query parameter** was omitted — it is required on every listing read, and the violation naming a field makes it look like a body problem | Add `?namespace=wix.form_app.form` to the read; leave the payload alone |
+| `fieldType cannot be provided with any these fields: input_options, display_options` — on every field | The read-back's `formFields` were re-mapped or "cleaned" before sending | Send the fields exactly as read and append the new one: `[...form.formFields, newField]` |
+| `inputType enum must be in [UNKNOWN_INPUT_TYPE, STRING, NUMBER, …]` | An invented `inputType` such as `ENUM` (with an `enumOptions` block) for a choice field | A dropdown or radio is `inputType: "STRING"` with `stringOptions.componentType`; multi choice is `ARRAY` |
+| The `PATCH` is rejected for a `revision` mismatch | Someone (or an earlier call) updated the form since your read | Re-`GET` and re-apply the change; never increment the revision yourself |
+| Fields that were on the form are gone after the update | `formFields` was sent partial — the omitted fields moved to `deletedFormFields` | Re-send them in a further `PATCH`, from `deletedFormFields` in the read-back; always send the whole array |
+| Surviving fields render empty for the owner | `steps[].layout` was sent without their items | Re-send every layout item, including `SUBMIT_BUTTON`'s; re-verify with `/summary` |
+| The added dropdown/radio reads back as a text input with `textInputOptions` | `identifier` was `TEXT_INPUT` rather than the choice kind — `componentType` alone doesn't route the renderer | Set `identifier` to the choice kind and re-send. Deleting and re-adding the field with the same `identifier` reproduces it ([Create Form](./create-form.md) § Choice fields) |
+| The update lands but the field never appears in submissions | The new field shares a `target` with an existing one — the server keeps one and the rest store nothing | Give it a unique `target` and `PATCH` again |
+| `Field count reached its limit of N` | The site's premium field cap, counting `INPUT` fields | Reduce, or put the upgrade choice to the user ([Create Form](./create-form.md) § Plan caps) |
+
+---
+
+## Related Documentation
+
+- [Create Form](./create-form.md) — composing fields, the identifier table, choice fields, the layout rules, plan caps
+- [Forms Dashboard Navigation](./forms-dashboard-navigation.md) — the builder and submissions links to hand back
+- [Update Form](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/update-form) — the `PATCH` contract and its replace semantics
+- [Form object](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-object) — `revision`, `hidden`, `deletedFormFields`, `steps[].layout`
+- [About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields) — every field-level rule

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

@@ -0,0 +1,141 @@
+---
+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."
+---
+# 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 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.
+
+Base URL: `https://www.wixapis.com/pa-platform/suggestions/v1`. `<AUTH>` is the `Authorization` header; body calls also need `Content-Type: application/json`.
+
+## Resolve the campaign
+
+The guide endpoints require a campaign UUID, but users often provide only a campaign name or say "my campaign."
+
+1. If the user provides a campaign UUID, use it.
+2. Otherwise follow [Manage Campaign Lifecycle](manage-campaign-lifecycle.md) and call:
+
+   ```bash
+   curl -X GET 'https://www.wixapis.com/google-ads/v1/campaigns' \
+     -H 'Authorization: <AUTH>'
+   ```
+
+   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.
+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
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/pa-platform/suggestions/v1/campaign-success-guides/get-or-create' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "campaignId": "7d4a9c2e-86f1-4b37-a2d5-9e18c6f043ab",
+    "platformType": "GOOGLE"
+  }'
+```
+
+```json
+{
+  "campaignSuccessGuide": {
+    "id": "7d4a9c2e-86f1-4b37-a2d5-9e18c6f043ab",
+    "url": "https://www.example.com/request-a-quote",
+    "suggestions": [
+      {
+        "id": "131b82f1-44f5-4f32-8cf1-f783a5f35222",
+        "type": "CLEAR_CTA_COPY",
+        "status": "OPEN"
+      }
+    ]
+  }
+}
+```
+
+The first call may analyze the landing page, campaign configuration, and relevant site connections and can take up to **120 seconds**. Later calls normally return the saved guide unless campaign changes require another analysis. Wait for the request; do not retry prematurely. If execution times out with an unknown outcome, report the uncertainty and retrieve the guide later instead of immediately triggering another analysis.
+
+Present only the suggestions the API returns and preserve their order; `suggestions` is already in priority order. An empty array means no currently detected items need attention, not an API failure. Show `campaignSuccessGuide.url` when it helps identify the analyzed landing page.
+
+`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.
+
+## Translate suggestion types for the user
+
+Keep the enum value unchanged in API calls, but use these labels when explaining the guide:
+
+| Enum | User-facing meaning |
+| --- | --- |
+| `CLEAR_CTA_COPY` | Clarify the primary call-to-action button's conversion intent. |
+| `ABOVE_THE_FOLD_CTA` | Put a call-to-action where visitors can see it without scrolling. |
+| `HEADER_MATCH` | Align the landing-page heading with the campaign's ad headlines. |
+| `CONVERSION_POINT` | Add a visible lead form or booking action. |
+| `GOOGLE_REVIEWS` | Display Google reviews or ratings. |
+| `TESTIMONIAL` | Add customer testimonials attributed to named people. |
+| `CONTACT_AND_CREDIBILITY` | Display a phone number and email address. |
+| `FAQ_SECTION` | Add a visible FAQ section. |
+| `MINIMIZE_FORM_FIELDS` | Limit the lead form to four visible fields. |
+| `SOCIAL_CHANNELS` | Add a visible social profile link. |
+| `GOOGLE_MERCHANT_CENTER_CONNECTION` | Connect Google Merchant Center. |
+| `GOOGLE_BUSINESS_PROFILE_CONNECTION` | Connect a Google Business Profile. |
+| `GOOGLE_ADS_SEARCH_THEMES` | Configure Google Ads search themes. |
+| `MOBILE_OPTIMIZATION` | Improve mobile optimization. |
+| `SITE_SPEED` | Improve site speed. |
+
+## Mark an item completed or reopen it
+
+The update endpoint identifies the suggestion by its **`type`**, not its suggestion `id`. A clear statement that the user completed a specific guide recommendation—for example, "I made the call-to-action button clearer as the success guide recommended"—is an actionable request to mark that item `COMPLETED`, not merely an FYI. Do not require the user to turn it into a question or ask for redundant confirmation.
+
+Before executing an update:
+
+1. Identify the campaign and a suggestion `type` currently present in its latest guide.
+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.
+
+Mark an item completed:
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/pa-platform/suggestions/v1/campaign-success-guides/7d4a9c2e-86f1-4b37-a2d5-9e18c6f043ab/update-suggestion-status' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "type": "CLEAR_CTA_COPY",
+    "status": "COMPLETED"
+  }'
+```
+
+Reopen the same item by sending:
+
+```json
+{
+  "type": "CLEAR_CTA_COPY",
+  "status": "OPEN"
+}
+```
+
+The response wraps the updated guide as `{ "campaignSuccessGuide": { ... } }`. Treat that returned guide as the new source of truth: report the changed tracking status and summarize remaining `OPEN` suggestions in priority order. Do not claim the underlying recommendation was implemented. Do not update multiple items unless the user's wording clearly identifies all of them.
+
+If a mutation times out with an unknown outcome, do not retry automatically. Retrieve the guide later to determine the current status first.
+
+## Errors
+
+| Error | Response behavior |
+| --- | --- |
+| `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. |
+
+## References
+
+- [Suggestions API introduction](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/platform/suggestion-v1/introduction)
+- [Get or Create Campaign Success Guide](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/platform/suggestion-v1/get-or-create-campaign-success-guide)
+- [Update Campaign Success Guide Suggestion Status](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/platform/suggestion-v1/update-campaign-success-guide-suggestion-status)

package/skills/wix-manage/references/google-business-profile/connect-google-business-profile.md

@@ -0,0 +1,134 @@
+---
+name: "Connect a Wix Site to Google Business Profile"
+description: Connect the authenticated Wix site to a Google Business Profile account, check whether an existing connection is still usable, recover a connection whose stored credentials are gone, switch to a different Google account, or disconnect. The site owner authorizes in their own browser through a single-use connect URL; the agent never completes the Google authorization itself. Warns before any reconnect that permanently removes the site's imported locations.
+---
+
+# Connect a Wix Site to Google Business Profile
+
+Use the public **Google Business Profile Connection API** to link the
+authenticated Wix site to a Google Business Profile account. The REST requests
+do not contain a site ID — the site comes from the caller's authorization
+context. Use the site the environment already supplies; if no site is selected,
+list the user's sites once and auto-select the only one, or ask the user to
+choose by site name when several are available. Never invent a site ID or ask
+the user to type one. A connection is the prerequisite for Google-backed work in the Google
+Business Profile Locations API — establish it before importing or managing
+locations.
+
+> **Bounded connect path — read first.** Read the connection once. For
+> `NEVER_CONNECTED`, request one connect URL and hand it to the owner; for
+> `VALID`, stop unless the user asked for other Google-backed work. A `403`,
+> `PERMISSION_DENIED`, or other terminal recovery-rule error ends the flow:
+> the **next action is the final response** explaining the blocker. Make no
+> further tool call: no API probe, documentation search, alternate request
+> shape, or call against another site. Only the explicitly
+> retryable `CONNECTING_USER_LOOKUP_UNAVAILABLE` error permits another connect-URL
+> attempt.
+
+Wix stores the Google credentials server-side. The API never returns tokens or
+any Google identity — only whether a connection exists and its dates.
+
+## Direct calls for this flow
+
+These are the complete request shapes needed for a fresh connection. Use them
+directly; do not search the API reference before calling them.
+
+| Method | Call |
+|---|---|
+| **Get Connection** | `GET https://www.wixapis.com/gbp/v1/connection` — no body or parameters |
+| **Get Connect URL** | `GET https://www.wixapis.com/gbp/v1/connect-url` — no body or parameters |
+
+For the common `NEVER_CONNECTED` path the only API calls are one **Get
+Connection**, then one **Get Connect URL**. If either returns `403` or
+`PERMISSION_DENIED`, stop immediately and explain it; do not look for another
+method or request shape.
+
+## Check the status first
+
+Always start with **Get Connection** and branch on `status`:
+
+| `status` | Meaning | What to do |
+|---|---|---|
+| `VALID` | Wix holds a credential for this site | Proceed with Google-backed work |
+| `NEVER_CONNECTED` | The site has never been connected | Run the connect flow — this is a setup step, not an error |
+| `NEEDS_RECONNECT` | The connection record exists but the stored credentials are gone | Warn the owner (see below), then run the connect flow |
+
+`VALID` is not a live health check: **Get Connection** deliberately does not
+call Google, so a connection can report `VALID` and still be refused by
+Google — for example after the owner revoked Wix's access in their Google
+account settings. Treat a Google-side authorization failure on a Locations
+call as the authoritative signal and re-run the connect flow when one appears.
+
+## Run the connect flow
+
+1. Call **Get Connect URL** once and read `connectUrl`.
+2. Present `connectUrl` to the site owner as a link to open in their own
+   browser, where they sign in to Google and grant access. Never fetch or open
+   the URL yourself — it is for a human, single-use, and expires after
+   15 minutes.
+3. Explain that completion is asynchronous: Google redirects the owner's
+   browser back to Wix, which finishes the OAuth exchange and stores the
+   credentials server-side.
+4. When the owner reports they have finished (or while waiting, on a modest
+   interval of a few seconds), call **Get Connection** and confirm `status` is
+   `VALID`. The `status` field is the only source of truth — a returned
+   connect URL alone proves nothing.
+5. If the 15-minute window elapses with `status` unchanged, request a fresh
+   URL and let the owner try again.
+
+**Get Connect URL is not idempotent, despite its GET route.** Every successful
+call creates a distinct live authorization attempt. Never retry it
+automatically after a timeout or ambiguous response — re-check
+**Get Connection** first and let the owner explicitly start another attempt.
+
+## Warn before a reconnect that replaces the connection
+
+Two flows permanently remove every Business Profile location imported into the
+site — the locations created through Wix as well as the imported ones. For
+locations migrated from an earlier Wix integration this cannot be reversed by
+re-importing. Get the owner's explicit confirmation **before** handing them
+the connect URL; there is no confirmation step later:
+
+- **Switching to a different Google account.** No Disconnect is needed — the
+  new account simply replaces the connection when its authorization completes.
+- **Reconnecting from `NEEDS_RECONNECT`, even with the same Google account.**
+  The stored credentials are gone, so there is nothing to match the incoming
+  account against and the reconnect is always treated as a replacement.
+
+While credentials are still present (`VALID`), authorizing again with the
+**same** Google account heals the connection in place and removes nothing.
+
+Also tell the owner that replacing or disconnecting changes nothing inside
+Google Business Profile itself — locations, reviews, and photos stay exactly
+as they are on Google — and does not revoke Wix's access inside their old
+Google account; they remove that from their Google account settings.
+
+## Disconnect
+
+Call **Disconnect** only after the owner confirms. It deletes the credentials
+Wix stores; it does not touch the Google Business Profile and does not revoke
+Wix's grant inside the Google account.
+
+## Recovery rules
+
+- **`CONNECTING_USER_LOOKUP_UNAVAILABLE`:** the site-owner lookup failed
+  temporarily, before any authorization attempt was created. This is the one
+  failure of **Get Connect URL** that is safe to retry.
+- **`CONNECTING_USER_NOT_RESOLVABLE`:** Wix could not identify a user to own
+  the credential. Stop — this is not retryable until the caller identity or
+  site ownership is corrected. Explain the blocker instead of trying other
+  request shapes.
+- **Timeout or ambiguous response from Get Connect URL:** do not retry. Call
+  **Get Connection** to learn the actual state, then let the owner decide.
+- **`MULTIPLE_CONNECTIONS_NOT_REPRESENTABLE`:** the site holds more than one
+  connection and the API will not guess which one is meant. Not a caller error
+  and not retryable — report it and direct the user to contact Wix support.
+- **Permission denied:** stop after the first `403` or `PERMISSION_DENIED`.
+  Do not retry with another request shape or site, and do not search for an
+  alternate API or method. Explain that the current Wix identity is not
+  authorized to manage the site's Google connection.
+
+The direct calls above are self-contained for the normal connect path. Consult a
+specific public method reference only for an edge case not covered here, and
+only before making a call. Once a status or typed error selects a branch above,
+do not search or browse for an alternate API, method, or request shape.