@wix/agent-skills 1.21.0 → 1.23.0

package/skills/wix-manage/references/google-ads/google-ads-dashboard-navigation.md

@@ -12,6 +12,22 @@ Build direct links into the Google Ads page of a site's dashboard. For the gener
 | Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
 |---|---|---|
 | Google Ads | `google-ads` | The Google Ads account, campaigns, and their performance |
+| Keywords manager (campaign-scoped) | `google-ads/keywords-manager?campaignId={campaignId}` | Search themes and campaign exclusions: `excludedSearchTerms` for Smart campaigns and `excludedKeywords` for Performance Max Leads campaigns |
+
+## Resolve a Campaign-Scoped Destination
+
+A campaign-scoped URL requires the campaign's Wix `campaignId`. Never substitute a campaign name in the URL or omit the query parameter.
+
+1. Reuse a `campaignId` already established in the conversation or returned by the preceding campaign operation. A Campaign Success Guide flow has already resolved its campaign, so use that ID without listing campaigns again.
+2. If only the campaign name is known, list campaigns once in the selected site's context:
+
+   ```bash
+   curl -X GET 'https://www.wixapis.com/_serverless/pa-google/v1/campaigns' \
+     -H 'Authorization: <AUTH>'
+   ```
+
+   Read `campaigns[].id` and `campaigns[].name`, and use the ID only when one campaign clearly matches the user's name.
+3. If neither the campaign ID nor name is known, or the list does not yield exactly one clear match, ask the user for the campaign ID or a more specific name. Do not guess or build the link until the campaign is unambiguous.
 
 ## Pairing Entities with Their Read APIs
 
@@ -23,3 +39,14 @@ Example — after creating a campaign:
 Your Performance Max campaign is live.
 Manage it here: https://manage.wix.com/dashboard/{metaSiteId}/google-ads
 ```
+
+When a user explicitly prefers to add a campaign's search themes manually, link directly to that campaign's keywords manager. Do not substitute this manual route for an agent-supported update the user wants the agent to perform.
+
+```
+Add Search Themes: https://manage.wix.com/dashboard/{metaSiteId}/google-ads/keywords-manager?campaignId={campaignId}
+```
+
+The same campaign-scoped route manages exclusions. Name the destination after the campaign field the user is managing:
+
+- **Smart campaigns:** `excludedSearchTerms` → **Manage Excluded Search Terms**
+- **Performance Max Leads campaigns:** `excludedKeywords` → **Manage Excluded Keywords**

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

@@ -12,9 +12,43 @@ Treat a broad request such as "How can I improve my Google Ads campaign?" as a C
 
 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.
 
+## Present every guide as an actionable plan
+
+Every response that presents a retrieved or supplied guide must use the actionable structure below. Do not wait for the user to ask for links, more detail, or a richer guide.
+
+1. On the first batch, start with the campaign name when known and link `campaignSuccessGuide.url` as the analyzed landing page when present. Do not repeat that context on later batches in the same conversation.
+2. Filter to `OPEN` suggestions and preserve their API priority order. Hide `COMPLETED` suggestions and tracking-status words unless the user explicitly asks what they completed.
+3. Show at most three not-yet-shown `OPEN` suggestions in a single-column numbered list under **Start here**, with a user-facing label and one concrete next step each.
+4. When at least one suggestion in the visible batch has supported agent work, add one **I can help** block that groups what the agent can perform after approval.
+5. When at least one suggestion in the visible batch has a navigation destination that should be shown now, finish with a **Next actions** block containing each destination exactly once. Use an absolute Markdown link when its exact URL is available. When an Editor URL cannot be resolved through the single attempt described below, write **Go to the Editor** once as plain guidance instead of omitting the destination or guessing a URL.
+6. If unshown `OPEN` suggestions remain, close by saying this batch contains the highest-priority remaining tasks and invite the user to see the next batch. A request for more is approval to show the next three; do not ask another confirmation question first.
+
+### Fast path when the guide is already supplied
+
+When the user supplies or paraphrases the guide recommendations, build the response from that information before doing any other discovery:
+
+1. Treat “still need to” and equivalent wording as `OPEN`, and anything the user says is marked complete as `COMPLETED`.
+2. Hide completed items, select the first three open items in the supplied order, and note only whether more open items remain. Do not name a later-batch item in the invitation.
+3. Do not resolve the campaign, list campaigns, retrieve or create the guide, query analytics, inspect action APIs, or read linked action recipes. Those calls cannot improve a guide the user already supplied. The only exception is the campaign identity resolution required by [Google Ads Dashboard Navigation](google-ads-dashboard-navigation.md) after the user explicitly chooses to manage Search Themes manually.
+4. Resolve only navigation needed by the visible batch, using existing site context or the single site-metadata attempt below, then return the actionable plan immediately.
+
+Track which suggestion types have been shown during the current conversation so later batches continue instead of repeating. When a refreshed guide contains a newly opened suggestion, place it among the unshown items by the API's current priority order. When a suggestion changes from `COMPLETED` back to `OPEN`, treat it as unshown so the reopened task appears again.
+
+Omit **I can help** or **Next actions** when that section would be empty.
+
+Use Markdown that reads top to bottom. Never use a table, grid, columns, or side-by-side layout for suggestions. Suggestion labels and next steps are content, not controls: do not turn them into links or conversational actions. A manual task stays plain text and points to the shared destination in **Next actions**.
+
+Keep navigation and delegated work distinct:
+
+- Navigation opens a destination and uses an absolute Markdown link such as `[Go to Editor](https://...)` when the exact URL is known. The plain **Go to the Editor** fallback is destination guidance, not a link or a suggested follow-up message.
+- Delegated work asks the agent to do something it actually supports. Group these offers in prose. If suggesting a conversational follow-up, include at most one for the highest-priority supported `OPEN` item and phrase it as an explicit request, such as **Draft FAQ content for me** or **Inspect my site speed**, never as the bare task label **Add an FAQ section**.
+- Only suggestions in the visible `OPEN` batch create navigation or offers. Do not offer work or add a destination for a hidden later-batch or `COMPLETED` suggestion.
+
+If there are no `OPEN` suggestions, say that nothing currently needs attention without listing completed items, and omit **I can help** and **Next actions**. If all open suggestions have already been shown in this conversation, say that every currently open task has been covered.
+
 ## Resolve the 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.
+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. When the user explicitly chooses manual Search Themes management, resolve its campaign-scoped destination through [Google Ads Dashboard Navigation](google-ads-dashboard-navigation.md), not this guide-retrieval flow.
 
 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.
 
@@ -69,41 +103,49 @@ curl -X POST \
 
 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.
+Present only the suggestions the API returns. `suggestions` is already in priority order: preserve the relative order of the visible `OPEN` batch. An empty array means no currently detected items need attention, not an API failure.
 
 `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:
+## Resolve supported work and navigation
 
-Use this output structure:
+The navigation block is part of each batch, including when the user supplied or paraphrased the recommendations. Before responding, resolve only the destinations required by the visible batch and appropriate at that point in the flow. Resolving navigation is read-only and does not require approval, including when the user says not to change anything yet.
 
-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.
+Use the selected site's `id` and `editUrl` from available site context first. If the current-site ID is known but `editUrl` is absent and a read-only site-listing capability is available, make at most one lookup using [Query Sites](../sites/query-sites.md). Query that exact ID with the verified REST filter below:
 
-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.
+```bash
+curl -X POST 'https://www.wixapis.com/site-list/v2/sites/query' \
+  -H 'Authorization: <ACCOUNT_AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": {
+      "filter": {
+        "id": {
+          "$in": ["<metaSiteId>"]
+        }
+      },
+      "cursorPaging": {
+        "limit": 1
+      }
+    }
+  }'
+```
 
-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 `id` filter requires the Wix Query Language operator object shown above. Do not send primitive equality such as `"id": "<metaSiteId>"`; the endpoint rejects that shape as a malformed filter. Read `editUrl` and `editorType` only from the returned site whose `id` exactly matches the current-site ID. This is the only navigation lookup: do not count or paginate sites, search by name, inspect other sites for campaigns, read alternative navigation docs, or try another endpoint. If the lookup is unavailable, returns no exact site, or returns no usable Editor URL, continue with plain **Go to the Editor** guidance instead of doing more discovery.
 
-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.
+When no current-site ID is known, present the tasks that do not require navigation immediately and ask which site's CTA to add. Do not enumerate an account to guess the site.
 
 ### 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. |
+| `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. When the agent can safely prepare useful material such as FAQ content, CTA copy, or a heading, offer to draft it after approval and explain that the user applies the final change in the Editor. 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, then explain that the user applies the resulting site change. These broad findings are not safe one-click mutations. Include the single Editor destination when the resulting work belongs there. Do not promise an improvement before identifying the actual cause. |
+| `GOOGLE_ADS_SEARCH_THEMES` | Offer first 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 wait for approval of the proposed set. Do not show a navigation link while this agent-performed offer is pending. If the user explicitly prefers to add the themes manually, provide the campaign-scoped **Add Search Themes** link described below instead. |
 | `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.
+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 or turn every suggestion into a follow-up action.
 
 For a Merchant Center connection, first read the selected site's Google Ads account:
 
@@ -116,32 +158,36 @@ Read `account.id`, `account.merchantCenterAccountId`, and `account.merchantCente
 
 ### 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.
+- **Editor:** Include this only when at least one suggestion in the visible batch 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, substitute the public landing-page URL, or attach a loosely related Help Center article. If the single lookup is unavailable, returns no exact match, or returns `EDITORLESS` or no `editUrl`, write **Go to the Editor** once as plain text in **Next actions**. Do not say that the link is unavailable, retry, or keep searching. Label a resolved link **Go to Editor** or name the more specific editing action; do not label it **Open in Wix**.
+- **Search Themes:** Do not add a Google Ads link merely because `GOOGLE_ADS_SEARCH_THEMES` is open. Offer the agent-performed update first. Only after the user explicitly chooses the manual path, follow [Google Ads Dashboard Navigation](google-ads-dashboard-navigation.md) to resolve and link the campaign's Keywords Manager. Reuse the campaign ID already established in the Success Guide conversation. Label the link **Add Search Themes**. If the user states that manual preference in the initial request, include the link in that batch; if they choose it later, return the link then.
+- **Other destinations:** Include a destination only when an `OPEN` item has a verified existing URL. Name the page or action precisely, such as **Open Forms dashboard** or **Review site speed**. Never make unrelated links look like the same generic action.
+- **Connection flows:** Google Business Profile and Merchant Center recommendations create an offer in **I can help**, not an initial navigation link. Return a task-specific authorization URL only after the user accepts the offer and the connection flow creates it.
+- Include only destinations appropriate for suggestions in the visible batch and list each URL once.
 
-Example when several tasks share the Editor:
+Example with several Editor tasks, supported connection work, and a completed campaign task:
 
 ```markdown
-## Campaign success guide
+## Campaign success guide — Request a Quote campaign
 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.
+### Start here
+1. **Add contact details**
+   Show a phone number and email address where visitors can easily find them.
+2. **Add an FAQ section**
+   Answer the questions prospective customers ask before contacting you.
+3. **Connect Google Business Profile**
+   Link the profile so campaign and business signals stay connected.
 
-I can take care of the search-theme update after you review the proposed set.
+### I can help
+I can draft the FAQ content and check and start the Business Profile connection after you approve. You will need to finish Google's consent in your browser. I can start with the FAQ draft.
 
 ### Next actions
-- [Go to Editor]({editUrl})
-- [Go to Google Ads](https://manage.wix.com/dashboard/{metaSiteId}/google-ads)
+- [Go to Editor]({absoluteEditUrl})
+
+These are the highest-priority open tasks. Would you like to see the next batch?
 ```
 
-Each link has its own destination-specific CTA, and the Editor URL appears once even though the first two recommendations both use it.
+The Editor URL appears once even though several recommendations use it. If the exact URL cannot be resolved in one attempt, replace that linked line with plain **Go to the Editor** guidance. Merchant Center is deferred to the next batch, the completed Search Themes item is hidden, and the Business Profile recommendation creates an agent offer rather than an unverified navigation link.
 
 ## Translate suggestion types for the user
 
@@ -215,7 +261,7 @@ Reopen the same item by sending:
 }
 ```
 
-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.
+The response wraps the updated guide as `{ "campaignSuccessGuide": { ... } }`. Treat that returned guide as the new source of truth: confirm the changed tracking status in plain language, hide completed items from the task list, and present up to the next three not-yet-shown `OPEN` suggestions in priority order. Treat a reopened item as unshown so it can appear again. 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.
 

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

@@ -1,6 +1,6 @@
 ---
 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, or to import from CSV/TSV export files with no source site. 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.
+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 — as a brand-new site or into the user's existing one — or to import from CSV/TSV export files with no source site. 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
@@ -24,8 +24,7 @@ and report the final result.
 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 use account-level
-scope on the signed-in Wix user's account. A full import typically takes
+Base URL: `https://www.wixapis.com/site-import`. A full import typically takes
 15–60 minutes.
 
 ## Calling the API
@@ -46,11 +45,12 @@ nothing useful.
 page, or any client-side code — those fail with CORS. The entire experience
 is plain chat — API calls plus short messages.
 
-Use the Wix account-level REST API tool available in your environment with
-the **full URL**. Start, Send-a-message, and Cancel are mutating (POST);
-Poll is read-only (GET).
+Use the Wix REST API tool available in your environment with the **full
+URL** (account-level, or site-scoped with a target `siteId` — see Start
+below for when each applies). Start, Send-a-message, and Cancel are mutating
+(POST); Poll is read-only (GET).
 
-Example — Start:
+Example — Start, account-level (creates a new site):
 
 ```
 POST https://www.wixapis.com/site-import/v1/imports
@@ -60,6 +60,19 @@ Body: {
 }
 ```
 
+Example — Start, site-scoped (imports into the user's existing site — same
+body, plus a `wix-site-id` header naming the destination site; see the
+Destination note under Start below):
+
+```
+POST https://www.wixapis.com/site-import/v1/imports
+Headers: { "wix-site-id": "<destination siteId>" }
+Body: {
+  "request": "Import https://example-store.com into my site",
+  "source_url": "https://example-store.com"
+}
+```
+
 Example — Start from exported files (no source site, FILE run):
 
 ```
@@ -96,11 +109,10 @@ API. Never fall back to other site-building tools (site-builder/template/AI
 site-generation tools) 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.
-A failed import ends with a clear failure report and a full stop; the user
+**Status comes ONLY from this API's Poll endpoint.** Never call another
+site-building or site-creation capability to "check on the build" — some
+such tools start a new site build on every call, even when asked only for
+status. 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 makes sense, propose it AFTER reporting the failure
 and act only on the user's explicit yes.
@@ -112,6 +124,17 @@ calling **Start**, confirm:
 - The source URL and platform are correct — or, for a file-only import, the
   export file URL(s) are correct
 - The user understands it runs for up to ~60 minutes and may ask questions mid-way
+- Which destination they want: a brand-new site, or their existing site by id
+  (site-scoped) — this can't be changed once Start is called. Importing into
+  an existing site writes into it directly and can add or overwrite its
+  current pages and content, so make sure they understand that before you
+  proceed — it isn't a safe side-by-side preview.
+  **If they want their existing site but haven't given a `siteId`, resolve
+  it yourself first** — from the account/site context already available to
+  you, or by querying the account's sites (see the Query Sites skill) — and
+  ask the user to pick when more than one candidate matches what they
+  described. Never guess a `siteId` or silently default to an account-level
+  call just because none was supplied.
 
 Also confirm before calling **Cancel** — it's irreversible.
 
@@ -183,14 +206,34 @@ You are the user experience; the API is plumbing. Keep the protocol invisible:
      `request`, and no `fileUrls`, is rejected with `SITE_UNIDENTIFIED`.
    Returns: `importId`, `sourcePlatform`, `sourceConfidence`, `destinationSiteId`.
    `sourcePlatform` comes back as `CSV` for a FILE run (no site was probed, so
-   `sourceConfidence` is meaningless there). `destinationSiteId` is the id of
-   the Wix site being imported into — returned as soon as Start succeeds,
-   even before a source is confirmed.
-   **One import per store at a time, keyed on `source_url`** (or the file set
-   when there's no `source_url`): re-starting with the same identity continues
-   the SAME migration (server returns the existing `importId`, no new import
-   created). A different identity always starts an independent migration, even
-   for the same user. If a different user on the account already owns an
+   `sourceConfidence` is meaningless there).
+   **Destination (new site vs. an existing site) is decided by call scope, not
+   a body field:** account-level (no site context) always creates a brand-new
+   site — the default when the user has none yet or wants a fresh one;
+   site-scoped (adding a `wix-site-id: <siteId>` header, same body — see the
+   examples above) writes into that existing site instead. Ask the user which
+   they want before calling Start — it can't change afterward. Get this
+   wrong at Start and you'll silently create an unwanted second site instead
+   of writing into the one they meant. Once Start has scoped the import,
+   keep sending that same `wix-site-id` header on every later call for that
+   `importId` (Poll, Send-a-message, Cancel included) — it won't create
+   another site at this point, but omitting it will fail authorization
+   against the site-scoped import. `destinationSiteId` in the
+   response echoes this (empty = new site, set = that existing site), returned
+   as soon as Start succeeds, even before a source is confirmed.
+   **One import per store at a time, keyed on `source_url` (or the file set
+   when there's no `source_url`) together with call scope** — account-level
+   and a given `wix-site-id` are different keys even for the identical
+   `source_url`/file set: re-starting with the same identity (same source
+   AND same scope) continues the SAME migration (server returns the
+   existing `importId`, no new import created). A different identity —
+   a different source, a different file set, or the same source at a
+   *different* call scope — always starts an independent migration, even
+   for the same user. This is why getting the scope wrong at Start matters
+   (see above): re-calling Start with the corrected scope does not fix the
+   original import, it starts a second, independent one. To redo a
+   mis-scoped import, **Cancel it first**, then Start again with the
+   correct scope. If a different user on the account already owns an
    import for that identity, Start returns
    `409 { "code": "IMPORT_IN_PROGRESS" }` — tell the user and stop.
 
@@ -238,7 +281,9 @@ You are the user experience; the API is plumbing. Keep the protocol invisible:
   - `FAILED` — terminal. Relay `message` in plain words.
   - `AUTH_EXPIRED` — recoverable, NOT success, nothing is live (golden rule 1).
     Tell the user the connection to their account expired and you're restarting,
-    then call Start again with the same request — work so far is preserved.
+    then call Start again with the same request, using the same call scope
+    (account-level, or the same `wix-site-id`) as the original Start — work so
+    far is preserved.
   - `CANCELLED` — terminal.
 - **Anything the user says mid-import goes straight to Send-a-message** — no
   need to wait for `NEEDS_INPUT`.
@@ -269,26 +314,45 @@ the user has no way to open a file.
 - Never invent a `deployUrl` — only report the one returned with `DEPLOYED`.
 - Treat `NEEDS_INPUT` and `AUTH_EXPIRED` as normal conversation turns, not
   errors.
-- **Site Import is in limited rollout, with no self-service enablement path.**
-  If Start returns `404` or `403` with `"code": "NOT_ENABLED"`, tell the user
-  plainly that site import isn't available on their account yet — then stop.
+- **Site Import is in closed beta, with no self-service enablement path.**
+  A `"code": "NOT_ENABLED"` on a `401`, `403`, or `404` from Start always means this
+  account isn't in the beta — whether the call was account-level or
+  site-scoped. The code isn't always present on an **account-level** call:
+  a not-yet-enrolled account's Start has been observed to come back as a
+  plain `401`/`403` (`{"message": "The caller is not permitted to perform this
+  action."}`, no code) as well as a plain `404` — treat any of those shapes there
+  as the beta-lockout case too. Don't probe other endpoints to diagnose it,
+  don't retry, and **don't create a site through any other site-building
+  capability to compensate — creating a site through a different path is
+  not a workaround here, it's the specific mistake this rule exists to
+  prevent.** Tell the user plainly and warmly that Site Import is
+  currently in a closed beta, that you'd be happy to help once they're
+  in, and that they can request access by filling out this short form:
+  https://forms.gle/RfZqVRtGCsPv7U7M6 — the team will follow up. Then
+  stop, having created nothing.
   **Do not tell them to "contact Wix support"**: this API is unlisted and
   ALPHA, Wix Support has no visibility into it or way to grant access, and the
   public "importing a site created outside of Wix" help-center article is an
   unrelated, long-stalled feature-request page — sending a user to either is a
-  dead end. If a Wix feedback tool is available in your environment, you may
-  offer to send feedback noting their interest; that is the only channel that
-  reaches the team. Do not retry or fall back to another site-creation tool.
-- Any other `403` on Start means the caller is not authorized — tell the user
-  and stop. Do not probe other endpoints to diagnose this. A `400` means a
-  required field is missing (`request`/`message` must be 1–20000 chars),
-  `source_url` exceeds 2048 chars, or `fileUrls` has more than 20 entries or
-  one over 2048 chars. A request with no identifiable site (no `source_url`
-  and no URL in `request`) and no `fileUrls` is rejected with
-  `SITE_UNIDENTIFIED` — ask the user for the store URL or export file(s) and
-  retry. A `fileUrls` entry that isn't a reachable http/https URL rejects the
-  whole call with `INVALID_FILE_URL` — tell the user which link failed and ask
-  for a working one.
+  dead end. The form above is the only channel that reaches the team.
+  **A `401`, `403`, or `404` on a site-scoped call *without* `"code": "NOT_ENABLED"`
+  is different** — it means the caller isn't authorized for that `siteId`
+  (wrong id, wrong account, no access), not a beta-enrollment issue. Tell
+  the user the destination site isn't accessible with their current
+  connection and stop; don't send them to the beta form for this.
+- For any other unrecognized error or exception on Start — a transient server
+  error, a timeout, a rate limit, or anything that isn't the closed-beta case
+  above or one of the specific cases below — don't guess that it's a
+  beta-enrollment issue and don't retry silently. Tell the user the import
+  couldn't be started, share what went wrong in plain language, and stop.
+- A `400` on Start means a required field is missing (`request`/`message`
+  must be 1–20000 chars), `source_url` exceeds 2048 chars, or `fileUrls` has
+  more than 20 entries or one over 2048 chars. A request with no identifiable
+  site (no `source_url` and no URL in `request`) and no `fileUrls` is rejected
+  with `SITE_UNIDENTIFIED` — ask the user for the store URL or export file(s)
+  and retry. A `fileUrls` entry that isn't a reachable http/https URL rejects
+  the whole call with `INVALID_FILE_URL` — tell the user which link failed and
+  ask for a working one.
 - Requesting an unknown id in `artifactIds` is silently ignored — not an error.
   A document simply may not exist yet on an earlier turn.
 - **The user cannot open files.** If a message mentions a document by filename,