@wix/mcp 1.0.93 → 1.0.95

package/build/dts/config/default-config.js

@@ -1,39 +1,58 @@
 import dedent from 'dedent';
 import { ARRAY_QUERY_PARAMS_RULE } from './api-request-rules.js';
+import { FILE_PARAM_CLIENTS, fileParamNote } from './file-params.js';
+import { SITE_BUILDER_CHOICE, WIX_BUSINESS_FEATURES } from '../site-widget-tools/constants.js';
 /**
  * Common agent goal - used in both SYSTEM_REMINDER and defaultReadmeDocs
  */
 const AGENT_GOAL = dedent `
-  You are an agent that helps the user manage their Wix site.
-  Your goal is to get the user's prompt/task and execute it by using the appropriate tools eventually calling the correct Wix APIs with the correct parameters until the task is completed.
+  You help the user with their Wix sites and account.
+  Work out what the task needs and do it: read the Wix skills, docs and API schemas that cover it, and write and run the code that calls Wix APIs, until the task is done.
 `;
+/**
+ * CallWixSiteAPI's advice when the Wix MCP lists no ExecuteWixAPI. True only where the server serves
+ * ExecuteWixAPI (a client with an old or cached tool list); `addApiCallTool` swaps it for
+ * `CALL_WIX_SITE_API_NO_EXECUTE_LINE` where ExecuteWixAPI is off on purpose.
+ */
+export const CALL_WIX_SITE_API_RECONNECT_LINE = 'If the Wix MCP offers no ExecuteWixAPI at all, your Wix connection is likely an old or cached version: tell the user once to reconnect the Wix connector or restart the client, and use this tool until then.';
+export const CALL_WIX_SITE_API_NO_EXECUTE_LINE = "If ExecuteWixAPI isn't in your tool list, use this tool.";
 const DISCOVERY_FLOWS = [
-    "- CONVERSATION CONTEXT BASED: find relevant docs article or API example for the user's prompt/task in the conversation context -> call API using CallWixSiteAPI() based on the docs article or API example",
-    '- METHOD CODE EXAMPLE BASED: BrowseWixRESTDocsMenu() or SearchWixRESTDocumentation() -> find relevant method -> read method article using ReadFullDocsArticle() to get method code examples -> call API using CallWixSiteAPI() based on the method code examples',
-    '- FULL SCHEMA BASED: BrowseWixRESTDocsMenu() or SearchWixRESTDocumentation() -> find relevant method -> read method article using ReadFullDocsArticle() -> no method code examples found -> inspect the method schema using SearchWixAPISpec or ReadFullDocsMethodSchema -> call API using CallWixSiteAPI() based on the schema'
+    "- CONVERSATION CONTEXT BASED: find relevant docs article or API example for the user's prompt/task in the conversation context -> call the API with ExecuteWixAPI based on the docs article or API example",
+    '- METHOD CODE EXAMPLE BASED: BrowseWixRESTDocsMenu() or SearchWixRESTDocumentation() -> find relevant method -> read method article using ReadFullDocsArticle() to get method code examples -> call the API with ExecuteWixAPI based on the method code examples',
+    '- FULL SCHEMA BASED: BrowseWixRESTDocsMenu() or SearchWixRESTDocumentation() -> find relevant method -> read method article using ReadFullDocsArticle() -> no method code examples found -> inspect the method schema using SearchWixAPISpec or ReadFullDocsMethodSchema -> call the API with ExecuteWixAPI based on the schema'
 ];
+/** The requests that skip WixREADME and go straight to their own tool, one bullet each. */
+function directRouteLines(includeReadme, includeImageUploadGuidance) {
+    return [
+        ...(includeReadme
+            ? [
+                `- **Creating a new site.** Skip the docs too. A site is written in code and uploaded: StartDeployWebsite returns the upload guide; StartHeadlessBuild returns the headless guide, for a site that needs Wix business features (${WIX_BUSINESS_FEATURES}). Call one right away, without asking the user anything first: StartHeadlessBuild when the site needs Wix business features, otherwise StartDeployWebsite. WixSiteBuilder or SearchSiteTemplates only when the user asked for Wix's editor, the Wix Harmony Editor, a template, Wix Studio or the Classic Editor. Never create a site through ManageWixSite, CallWixSiteAPI or ExecuteWixAPI.`
+            ]
+            : []),
+        '- **Listing, showing or finding their Wix sites**: call ListWixSites directly.',
+        ...(includeImageUploadGuidance
+            ? [
+                '- **Uploading local or attached image files to a Wix site**: call UploadImageToWixSite directly, with no docs, schema or API calls. Do NOT use ExecuteWixAPI, SearchWixAPISpec, or any Media Manager REST API for image uploads.'
+            ]
+            : [])
+    ];
+}
 // README-only lines and site-creation routing are added only when includeReadme
 // is true (README-free consumers like aria don't do site creation).
 function buildSystemReminderGuidelines(includeReadme, includeImageUploadGuidance) {
-    const exception = includeReadme ? '**Exception:** ' : '';
     const lines = [];
-    if (includeReadme) {
-        lines.push('if the WixREADME tool is available to you, YOU MUST USE IT AT THE BEGINNING OF ANY CONVERSATION and then continue with calling the other tools and calling the Wix APIs until the task is completed.', '**Exception — creating a new Wix site/website:** For a normal creation request — and only then — skip WixREADME and the docs search, and route straight to the Wix site-creation tools available to you; their descriptions carry the routing rules. Everything else starts with WixREADME as usual.', "If the user explicitly asks for a headless site, Wix Classic Editor site, or manual account/API-based site creation, call CreateWixBusinessGuide right away — these don't need the site's purpose first.", "If the user — or you, earlier in this conversation — already have a finished page or site in any form (HTML/CSS/JS files, a static build, a zip, another builder's export, a design you can export to HTML) and want it live on Wix, call StartDeployWebsite right away — not a site-creation tool, not the docs.", "Never default to AI or search templates unless the user explicitly requests it. When the user named no creation method - let the user make that choice as the site-creation tools' descriptions direct. Never route normal site creation through ManageWixSite, CallWixSiteAPI, or ExecuteWixAPI.");
-    }
-    lines.push(`${exception}If the user asks to list, show, or find their Wix sites, ${includeReadme ? 'skip WixREADME and ' : ''}call ListWixSites directly.`);
-    if (includeImageUploadGuidance) {
-        lines.push(`${exception}If the user wants to upload local or attached image files to a Wix site, skip ${includeReadme ? 'WixREADME and ' : ''}all docs/schema/API flows — call UploadImageToWixSite directly. Do NOT use ExecuteWixAPI, SearchWixAPISpec, or any Media Manager REST API for image uploads.`);
-    }
-    if (includeReadme) {
-        lines.push('If the WixREADME tool is not available to you, you should use the other flows as described without using the WixREADME tool until the task is completed.');
-    }
-    lines.push(`This applies to QUESTIONS too, not only action tasks (the ${includeReadme ? 'exceptions' : 'direct-tool routes'} above still apply — question-shaped variants of those intents, e.g. "can you show my sites?", follow their ${includeReadme ? "exception's " : ''}direct tool): never answer a Wix-specific question from memory, and never reply that you lack the tools or APIs to answer, without first ${includeReadme ? 'calling the WixREADME tool (if available) and checking its recipes index, searching the docs,' : 'searching the docs'} and reading the matching docs articles — many questions (including ones that need no API call) are answered by a ${includeReadme ? 'recipe or docs article' : 'docs article'}.`, 'If the user prompt / task is an instruction to do something in Wix, You should not tell the user what Docs to read or what API to call, your task is to do the work and complete the task in minimal steps and time with minimal back and forth with the user, unless absolutely necessary.');
+    lines.push(includeReadme
+        ? 'Start every Wix task with WixREADME, questions included, then use the other tools and the Wix APIs until the task is done. If WixREADME is not available, follow the flows without it. These requests skip it and go straight to their own tool:'
+        : 'These requests go straight to their own tool, with no docs or API calls first:');
+    lines.push(...directRouteLines(includeReadme, includeImageUploadGuidance));
+    lines.push(`A question follows the same routes: one about those requests goes to its tool ("can you show my sites?" is ListWixSites). Any other Wix question is answered from ${includeReadme ? 'WixREADME, the Wix skills, ' : ''}the docs search and the matching docs articles, never from memory, and never with a reply that you lack the tools or APIs to answer. Many questions, including ones that need no API call, are answered by a ${includeReadme ? 'Wix skill or docs article' : 'docs article'}.`, "When the user asks you to do something in Wix, do it, in as few steps and questions as you can; don't tell them which docs to read or which API to call.");
     return lines.join('\n');
 }
 function buildSystemReminderFlows(includeReadme) {
     const lines = ['Wix MCP Site Management Flows'];
+    const noSkill = "no Wix skill covers the user's prompt/task -> ";
     if (includeReadme) {
-        lines.push('With WixREADME tool:', "- RECIPE BASED (PREFERRED!): WixREADME() -> find relevant recipe for the user's prompt/task -> read recipe using ReadFullDocsArticle() -> call Wix API using CallWixSiteAPI() based on the recipe", DISCOVERY_FLOWS[0], "- EXAMPLE BASED: WixREADME() -> no relevant recipe found for user's prompt/task -> BrowseWixRESTDocsMenu() or SearchWixRESTDocumentation() -> find relevant method -> read method article using ReadFullDocsArticle() to get method code examples -> call API using CallWixSiteAPI() based on the method code examples", "- SCHEMA BASED, FALLBACK: WixREADME() -> no relevant recipe found for user's prompt/task -> BrowseWixRESTDocsMenu() or SearchWixRESTDocumentation() -> find relevant method -> read method article using ReadFullDocsArticle() -> no method code examples found -> inspect the method schema using SearchWixAPISpec or ReadFullDocsMethodSchema -> call API using CallWixSiteAPI() based on the schema", 'Without WixREADME tool:');
+        lines.push('With WixREADME tool:', "- SKILL BASED (PREFERRED!): WixREADME() -> find the Wix skill for the user's prompt/task (WixREADME says how to read one) -> follow it -> call the API with ExecuteWixAPI based on it", DISCOVERY_FLOWS[0], `- EXAMPLE BASED: WixREADME() -> ${noSkill}BrowseWixRESTDocsMenu() or SearchWixRESTDocumentation() -> find relevant method -> read method article using ReadFullDocsArticle() to get method code examples -> call the API with ExecuteWixAPI based on the method code examples`, `- SCHEMA BASED, FALLBACK: WixREADME() -> ${noSkill}BrowseWixRESTDocsMenu() or SearchWixRESTDocumentation() -> find relevant method -> read method article using ReadFullDocsArticle() -> no method code examples found -> inspect the method schema using SearchWixAPISpec or ReadFullDocsMethodSchema -> call the API with ExecuteWixAPI based on the schema`, 'Without WixREADME tool:');
     }
     lines.push(...DISCOVERY_FLOWS);
     return lines.join('\n');
@@ -43,9 +62,8 @@ export function buildSystemReminder(includeReadme, includeImageUploadGuidance =
     const guidelines = buildSystemReminderGuidelines(includeReadme, includeImageUploadGuidance);
     const flows = buildSystemReminderFlows(includeReadme);
     return dedent `
-    <agent-mandatory-instructions>
-    YOU MUST READ AND FOLLOW THE AGENT-MANDATORY-INSTRUCTIONS BELOW
-    A FAILURE TO DO SO WILL RESULT IN ERRORS AND CRITICAL ISSUES.
+    <wix-usage-guide>
+    How to work with Wix through these tools. Following these steps avoids failed or incorrect API calls.
     <goal>
     ${AGENT_GOAL}
     </goal>
@@ -55,47 +73,39 @@ export function buildSystemReminder(includeReadme, includeImageUploadGuidance =
     <flow-description>
     ${flows}
     </flow-description>
-    </agent-mandatory-instructions>
+    </wix-usage-guide>
   `;
 }
 export const SYSTEM_REMINDER = buildSystemReminder(true);
+/** SearchWixHelpCenter's description and response both carry this: Help Center is for people, the developer docs for the agent's own actions. */
+export const HELP_CENTER_IS_FOR_PEOPLE = "The Help Center is written for people doing things by hand in Wix's dashboard and editors. To act on a site yourself, the Wix developer docs come first: find the method with SearchWixRESTDocumentation or BrowseWixRESTDocsMenu.";
+/**
+ * The MCP server's \`instructions\`, sent in its reply to initialize. Clients that show them
+ * (ChatGPT and Codex use the first 512 characters; Claude Code loads them at session start and
+ * cuts at 4,096) get the site-creation routing before any tool definition. Sent only to a session
+ * that has every tool it names (SERVER_INSTRUCTIONS_TOOLS).
+ * Each tool named here carries a comment pointing back to this text. A change to any of them (a
+ * name, what it is for, a new site-creation tool) updates this text and that list with it.
+ */
+export const SERVER_INSTRUCTIONS = `Wix: build and manage Wix sites. A new site is written in code and uploaded: StartDeployWebsite returns the upload guide; StartHeadlessBuild returns the headless guide, for a site that needs Wix business features (forms, a store, bookings, a CMS, members, payments). WixSiteBuilder or SearchSiteTemplates only when the user asked for Wix's editor, the Wix Harmony Editor, a template, Wix Studio or the Classic Editor. For anything else, except ListWixSites and UploadImageToWixSite, call WixREADME first.`;
+/** The tools SERVER_INSTRUCTIONS names. */
+export const SERVER_INSTRUCTIONS_TOOLS = [
+    'StartDeployWebsite',
+    'StartHeadlessBuild',
+    'WixSiteBuilder',
+    'SearchSiteTemplates',
+    'WixREADME',
+    'ListWixSites',
+    'UploadImageToWixSite'
+];
 export const SITE_CREATION_COPY = {
     templatePick: {
         nonWidget: 'After the user selects a template, call `CreateSiteFromTemplate`.',
         widget: 'The gallery creates the site when the user picks one.'
-    },
-    unstatedMethod: {
-        nonWidget: 'you MUST ask whether they want to build with AI or start from a template, and create nothing and show nothing until they answer',
-        widget: 'you MUST call `WixSiteCreation` and let them choose'
-    },
-    normalCreationRoute: {
-        nonWidget: 'route those through `WixSiteBuilder` or `SearchSiteTemplates`',
-        widget: 'route those through `WixSiteCreation`'
     }
 };
-/**
- * Carried by every tool that can start creating a site, so no route skips it.
- * `CreateWixBusinessGuide` is exempt: headless/classic/manual don't need the site's purpose.
- */
-const SITE_GUIDANCE = dedent `
-  First decide which of two different things is being asked for:
-  - The site is code the user or you control — hand-written HTML/CSS/JS, a static build, a zip, another AI builder's export, or a page or design you made earlier in this conversation — and it should go live on Wix. This is also the route whenever the user wants to keep working on the site here, with you: a Wix Headless site is a regular coded site, so you keep full control of the design and can change and redeploy it from this conversation at any time, and Wix business capabilities can be added to it as a backend when they are needed. Call StartDeployWebsite: it returns the recipe to host those exact files as a Wix Headless site (updates reuse the same site and URL; the drop page is only its fallback). Do not offer AI or templates for this and do not call any site-creation tool.
-  - Wix should create the site — generated with AI from a description, or started from a template — and the user will design and edit it in Wix rather than through you. That is what the site-creation tools do; they never take files you already have.
-
-  For a new site there are two things to settle: what the site is for, and how to build it. The how is AI generation vs. starting from a template, so naming templates, a template id or Wix Studio (Wix Studio is also the template side) already settles it.
-
-  Settle what the site is for first: its purpose, topic, business type, audience, or main visitor action. Naming a method is not a description of the site, and neither is the business or industry on its own.
-  If you can't tell yet, ask the preferred question below and nothing else — one question, no creation-method question in the same reply, and no internal tool names.
-  Once the purpose is clear, unless the user already named a method, ${SITE_CREATION_COPY.unstatedMethod.nonWidget}. A method they named is settled — never re-open it. Never default to AI or to templates, and never ask the user to choose between Harmony and Wix Studio; infer that from their words.
-  With the purpose and the method known, that's enough to begin — route and refine the specifics with the user afterward.
-
-  Preferred question when the user has given no site context at all:
-  Happy to help. To give you the right starting point, tell me a bit more about what you have in mind:
-  - What's the site for? (e.g. an online clothing store, a yoga studio that takes bookings, a restaurant)
-  - What's the vibe? (e.g. sleek and modern, cozy and rustic, bold and energetic)
-  Give me a quick summary and I'll take it from there
-
-  Tone: helpful, practical, short. Speak about the user's site — what you're making and what comes next — not the tools, payloads, or routing behind it.`;
+/** The editor tools' shared tail: when to call them, and the question for "Wix's editor" alone. */
+const EDITOR_TAIL = `When the user wants Wix's editor, or to design the site themselves, without saying how to start, ask them first: "${SITE_BUILDER_CHOICE.editorQuestion}" A new site is otherwise written in code and uploaded: call StartDeployWebsite, or StartHeadlessBuild when it needs Wix business features, right away and without asking the user anything first.`;
 /** Rewrites non-widget copy into its widget form; a no-op on text that carries no divergence. */
 export const toWidget = (text) => Object.values(SITE_CREATION_COPY).reduce((acc, { nonWidget, widget }) => acc.replaceAll(nonWidget, widget), text);
 /**
@@ -103,8 +113,13 @@ export const toWidget = (text) => Object.values(SITE_CREATION_COPY).reduce((acc,
  * `buildToolDescriptions(false)` returns the same descriptions with WixREADME
  * mentions scrubbed (used by the toolkit's `includeReadmeMentions` flag).
  */
+// The data the Wix REST API covers, product by product (from the ax-skills capability map), named
+// in the discovery tools' descriptions so a client's tool search finds them by what the user asks about.
+const WIX_API_DATA = "products, inventory, carts, checkouts, orders, bookings, services, staff, time slots, rentals, restaurant menus, online orders, reservations, events, tickets, RSVPs, blog posts, CMS collections and items, pricing plans, subscriptions, portfolios, gift cards, coupons, donations, forms, form submissions, contacts, members, loyalty points, groups, reviews, inbox messages, CRM tasks, automations, email campaigns, payments, invoices, SEO, redirects, translations, locations, analytics, media files, site properties, installed apps, and the account's sites and domains";
 const EXECUTE_WIX_API_INTRO = dedent `
-  Execute JavaScript code against the Wix REST API when code is useful for chaining related calls, pagination, loops, branching, or in-memory transformation.
+  Reads and changes the data of a Wix site or account: query, list, count, create, update and delete it with one JavaScript function over the Wix REST API.
+  One function holds the whole task: chained calls, pagination, loops, branching, and the reads that feed its writes.
+  Putting a site live or changing a headless site's files starts with StartDeployWebsite; building a new site in code with StartHeadlessBuild.
 
   CODE CONTRACT:
   - Pass an async function expression: \`async function() { ... }\` or \`async () => { ... }\`. Put every declaration, \`await\`, and \`return\` inside it, and do not invoke it yourself.
@@ -189,7 +204,7 @@ const ACCOUNT_SITE_EXECUTE_SCOPE = dedent `
   declare const files: Array<{ path: string; content: string; encoding?: "base64" }>;
   \`\`\`
 
-  FILE UPLOADS: files never go inline in \`code\`; two params feed the \`files\` global. \`attachments\` takes files attached in the chat or created in your file sandbox, of any type and size up to 10 MB per call (a zip of a whole site, HTML, images, PDFs): pass the files themselves, all in one call, and the platform resolves each into \`{ download_url, file_id, file_name?, mime_type? }\` — the bytes are fetched for you and arrive as base64 entries named by file name. The \`files\` param takes content you have as text here: text goes raw; a small binary (icon, logo, font) rides as a \`base64\`-tagged entry — large images/video are referenced by URL (\`<img src="https://...">\`), not bundled. \`wix.multipart()\` turns the whole set into one upload body (bytes, so binary is safe):
+  FILE UPLOADS: files never go inline in \`code\`; two params feed the \`files\` global. \`attachments\`: ${fileParamNote('upload from your shell if it reaches the internet')} Any type, up to 10 MB per call, all in one call: a zip of a whole site, HTML, images, PDFs; the bytes arrive as base64 entries named by file name. The \`files\` param takes content you have as text here: text goes raw; a small binary (icon, logo, font) rides as a \`base64\`-tagged entry — large images/video are referenced by URL (\`<img src="https://...">\`), not bundled. \`wix.multipart()\` turns the whole set into one upload body (bytes, so binary is safe):
   \`\`\`javascript
   // files param:
   //   === FILE: index.html ===
@@ -204,6 +219,7 @@ const ACCOUNT_SITE_EXECUTE_SCOPE = dedent `
     return res.data;
   }
   \`\`\`
+  HEADLESS SITE EDITS: \`wix.headless.files.list({siteId, prefix?, offset?, limit?})\` returns file metadata; \`read({siteId, path})\` returns UTF-8 text (up to 256 KB); \`patch({siteId, files?, deletePaths?, agent?})\` applies changed files and explicit deletions while preserving everything else. Patch defaults to the Execute \`files\` global (including resolved attachments and ZIPs). Paths are literal site-relative paths; no wrapping-folder stripping. It returns added/replaced/deleted/unchanged/missingDeletes path lists. List/read reuse one downloaded ZIP snapshot for the current site within an Execute call; switching sites discards the previous snapshot, and a new call downloads afresh. Patch downloads a fresh ZIP, then drops the full merged site and clears the read snapshot. Serialize edits to the same site; there is no atomic concurrency guarantee. For a full replacement, use the existing upload/drop path. See the upload-static-site recipe for examples and older-server fallback.
   A site zip passed through \`attachments\` is one base64 entry; unzip it and upload the entries:
   \`\`\`javascript
   // attachments: [site.zip] → files = [{ path: "site.zip", content: "<base64>", encoding: "base64" }]
@@ -327,19 +343,38 @@ export const executeWixApiDescription = dedent `
 
   ${EXECUTE_WIX_API_MULTI_SITE_EXAMPLE}
 `;
-export function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true) {
-    const reminder = buildSystemReminder(includeReadme, includeImageUploadGuidance);
-    return {
+export function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true, { usageGuideOnce = false } = {}) {
+    const usageGuide = buildSystemReminder(includeReadme, includeImageUploadGuidance);
+    // With usageGuideOnce, the usage guide is carried once, by WixREADME, the tool every flow
+    // starts from: its description has the guidelines and its response the flows. Repeated on
+    // every docs and API tool, it filled most of what an agent that loads all definitions at
+    // once gets to read. It needs WixREADME to be there.
+    const reminder = includeReadme && usageGuideOnce ? '' : usageGuide;
+    const descriptions = {
+        // Named in SERVER_INSTRUCTIONS: when this tool's name or what it is for changes, update them to match.
         WixREADME: dedent `
     # Tool: WixREADME
-    **Directive:** \`WixREADME\` is the **MANDATORY FIRST STEP** for all Wix-related tasks. Its output (including relevant linked documents) provides foundational context for all other Wix tools. Adherence to this protocol is **NON-NEGOTIABLE**.
-
-    **Mid-conversation site switching:** If the user references a different site by name or ID after WixREADME has already been called, use \`GetSiteContext\` directly — no need to call WixREADME again.
-    ${reminder}
+    The context every other Wix tool assumes. Call it first, once per conversation, for any Wix task or question; for another site later in the conversation, call \`GetSiteContext\` instead of calling this again.
+    A Wix task includes reading or changing a site's or account's data: ${WIX_API_DATA}.
+    These requests skip it and go straight to their own tool:
+    ${directRouteLines(includeReadme, includeImageUploadGuidance).join('\n')}
+    A question about one of those goes to the same tool ("can you show my sites?" is ListWixSites). Any other Wix question is answered from a Wix skill or the docs, never from memory, and never with a reply that you lack the tools to answer.
+    It returns, in full:
+    - **Source of truth**: nothing Wix-specific from memory. Every URL, ID, setting location, product fact, request shape and field name comes from the docs tools, a Wix skill, an earlier tool result in the conversation, or the user.
+    - **The site**: the account's sites with their properties and installed apps. The \`siteId\` comes from there (ask when several fit); a business solution's API works only on a site with its app installed, and an app's version changes its endpoints.
+    - **Find the method**: an earlier tool result, else a Wix skill's recipe (wix-manage to manage a site, wix-headless-kit to build a headless one), else the docs: SearchWixRESTDocumentation or BrowseWixRESTDocsMenu, then ReadFullDocsArticle; the SDK, CLI, headless and apps docs for code.
+    - **The exact shape**: model a call only on an example that matches the case; fill the rest with SearchWixAPISpec on the method's docs URL (request and response schemas, \`method.publicUrl\` for REST, \`method.sdk\` for the JavaScript SDK). A query's filter and sort fields and operators are a closed list per method.
+    - **The call, or the code**: ExecuteWixAPI runs one async function holding every step code can resolve, the reads and the writes they feed together, \`hasMutations: true\` when anything writes. Code the user keeps (an app, a headless site, a script over REST or the JavaScript SDK) is written from the same shapes; the headless skills are a shortcut on that path.
+    - **When a call fails**: the error says what was wrong and carries a Wix request id; fix that, never resend unchanged or guess.
+    - **Wix skills**, what each is for and how to read one: from disk when installed (the Wix plugin, or \`npx skills add wix/skills\`, \`--skill <name>\` for one, \`-g\` for the user's home, into \`.agents/skills/<skill>/\` or a similar folder the client reads, such as \`.claude/skills/<skill>/\`), else online with ReadFullDocsArticle at \`https://www.wix.com/skills/<skill>/<path>\`.
+      - **wix-manage**: REST recipes for managing a site's business solutions, one per task; follow the recipe and make its calls with ExecuteWixAPI, its docs URL in \`sourceDocUrls\`. Its list of recipes is \`SKILL.md\` in the installed skill, or online https://dev.wix.com/docs/api-reference/articles/ai-tools/wix-mcp/skills/wix-management-recipes-index.md, and each API area has its own \`<API section>/skills.md\` (for example https://dev.wix.com/docs/api-reference/business-solutions/bookings/skills.md).
+      - **wix-headless-kit**: builds a Wix Headless site on shipped, verified code from wix-headless-templates, a \`@wix/sdk\` React core or the same data layer as plain REST calls: scaffold with the CLI, deploy, seed, design on the shipped hooks, release. https://www.wix.com/skills/headless-kit/SKILL.md
+      - **wix-headless-templates**: the code wix-headless-kit builds from, one folder per Wix Business Solution. https://www.wix.com/skills/headless-templates/
+    When the user asks you to do something in Wix, do it yourself, in as few steps and questions as you can; don't tell them which docs to read or which API to call.
   `,
         SearchWixRESTDocumentation: dedent `
     **Searches the official Wix REST API documentation — the starting point for any Wix REST API task.** Unless you already have the exact method \`docsUrl\` in context, begin the task here; this is how you discover the right endpoint. Reach for it before \`SearchWixAPISpec\`, and avoid writing code that scans or filters \`lightIndex\` to find an endpoint (e.g. \`lightIndex.filter(...)\`, \`lightIndex.flatMap(...)\`, or substring-matching on \`docsUrl\`/\`name\`/\`summary\`) — that has no relevance ranking and silently misses composite and method-level operations. This is the ranked semantic-search discovery tool over the Wix REST API docs: describe your intent in natural language and it returns the matching REST endpoints/methods (with their \`docsUrl\`) ranked by relevance. It is the first step whenever you need to do something on a Wix site via HTTP and don't already have the exact \`docsUrl\` in context — for creating, reading, updating, or deleting any kind of Wix entity, across every business domain.
-    It covers all Wix REST domains equally — Stores, eCommerce/orders, Bookings, CRM/contacts, Members, CMS/data collections, Events, Blog, Forms, Marketing, Media, site settings, SEO, and the rest. Just describe the resource, action, or goal in plain words (e.g. 'add a catalog item with inventory', 'book a service', 'update a data collection item', 'create a discount', 'list contacts', 'get site details endpoint', 'REST authentication'); the ranking handles matching your wording to the right API regardless of domain.
+    It covers all Wix REST domains equally, every product's data: ${WIX_API_DATA}, and the rest. Just describe the resource, action, or goal in plain words (e.g. 'add a catalog item with inventory', 'book a service', 'update a data collection item', 'create a discount', 'list contacts', 'get site details endpoint', 'REST authentication'); the ranking handles matching your wording to the right API regardless of domain.
     **Next step after this tool:** take the \`docsUrl\` it returns and inspect that method's exact request/response schema with \`SearchWixAPISpec\` (\`getResourceSchemaByUrl(docsUrl)\`), then execute. \`SearchWixAPISpec\` is only for INSPECTING a \`docsUrl\` you already have — it is NOT a discovery tool. Skipping this step to hand-search \`lightIndex\` yourself is a mistake: raw index filtering has no relevance ranking and misses operations this ranked search finds. Discover here first, every time.
     If you can't find what you need, rephrase your search term or use a bigger maxResults value.
     ${reminder}
@@ -347,7 +382,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
         ReadFullDocsArticle: dedent `
     Fetches the full Wix docs article or method article with code examples for using the method.
     Docs articles looks like this: https://dev.wix.com/docs/... and they can either be general docs articles or method articles.
-    Also reads Wix skills pages — https://www.wix.com/skills/<skill>, https://dev.wix.com/docs/skills/<skill>, and the files they link (e.g. .../<skill>/references/<file>.md) — exactly as served.
+    Also reads Wix skills pages — https://www.wix.com/skills/<skill>, https://dev.wix.com/docs/skills/<skill>, and the files they link (e.g. .../<skill>/references/<file>.md) — and Wix Headless agent pages under https://www.wix.com/headless/ (e.g. https://www.wix.com/headless/skill.md), exactly as served.
     Take the URL from the user's message or an earlier tool result. To reach an article you have no URL for, search or browse the docs first.
     For REST docs, use the URL as-is. For SDK docs, the URL SHOULD include ?apiView=SDK.
     ${reminder}
@@ -361,6 +396,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
   `,
         CallWixSiteAPI: dedent `
     Call Wix apis on a business or site. Use this to create, read, update, and delete data and other Wix entities in your Wix site.
+    ExecuteWixAPI is the preferred tool for Wix API calls: one function holds every call of the task, the reads and the writes they feed together, where this tool makes one call per invocation. If your client loads tools on demand (tool search, deferred tools), load ExecuteWixAPI before using this tool. ${CALL_WIX_SITE_API_RECONNECT_LINE}
     Site-level: this tool reads and writes inside the single site named by the required \`siteId\`.
     **Prefer using the "ListWixSites" tool when the user asks to list or show their sites.** Only use this tool for site listing if the user needs advanced filtering or specific site details beyond what ListWixSites provides.
     For POST/PATCH/PUT requests, pass the request body as a JSON object or array in the "body" parameter with all the required fields and values as described in the API schema, code examples, or docs you retrieved (e.g. body: {"name": "value", "nested": {"key": "value"}} or body: [{"key": "value"}]).
@@ -375,6 +411,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     Docs urls like https://dev.wix.com/docs/... are not api urls, if you want to read the docs, use the "ReadFullDocsArticle" tool
     ${reminder}
   `,
+        // Named in SERVER_INSTRUCTIONS: when this tool's name or what it is for changes, update them to match.
         ListWixSites: dedent `
     **Use this tool whenever the user asks to list, show, get, or find their Wix sites.** This is the dedicated tool for listing Wix sites for the current user. By default it returns all sites, but you can filter by name.${includeReadme ? '\n\n**Do NOT use WixREADME before this tool.** When the user asks to list their sites, call this tool directly — no need to read documentation first.' : ''}
 
@@ -395,13 +432,14 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     ${reminder}
   `,
         ManageWixSite: dedent `
-    Use account level API in order to create a site and update a site.
+    Use account level API in order to update a site.
     Account-level only: this tool acts on the account itself, or on sites as objects within it, and sends no site context. Anything that reads or writes inside a site is site-level and does not belong here — use a site-level tool with that site's \`siteId\`.
     For POST/PATCH/PUT requests, pass the request body as a JSON object or array in the "body" parameter with all the required fields and values as described in the API schema, code examples, or docs you retrieved (e.g. body: {"name": "value", "nested": {"key": "value"}} or body: [{"key": "value"}]).
     The API endpoint url param MUST ALWAYS be taken from the conversation context.
     By conversation context we mean the endpoint url was given in the user prompt or got into the conversation context ${includeReadme ? 'by the "WixREADME" tool or ' : ''}by the "SearchWixRESTDocumentation" tool or by the "BrowseWixRESTDocsMenu" tool or by the "ReadFullDocsArticle" tool.
     ${reminder}
   `,
+        // Named in SERVER_INSTRUCTIONS: when this tool's name or what it is for changes, update them to match.
         UploadImageToWixSite: dedent `
     Upload one or more images to a Wix site's Media Manager. Returns wixstatic.com URL and media ID.
     Do NOT use ExecuteWixAPI or code execution for image uploads — use this tool directly.
@@ -411,34 +449,39 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     NEVER call this tool with a missing, empty, or guessed siteId — ask first instead.
 
     Parameters — provide image input via image and/or imageUrls, OR imageBase64:
-    • image (array): chat file ATTACHMENTS — files the user attached, or files you created in your own file sandbox. Each item is an object with download_url and file_id (both required), plus optional file_name and mime_type. Pass ALL attachments in one call.
+    • image (array): ${fileParamNote('send the image as imageBase64 (the whole file, one per call) or as a public URL in imageUrls')} Pass ALL of them in one call.
     • imageUrls (array): plain public image URLs the user pasted or other tools produced (no file_id). Pass ALL URLs in one call. Can be combined with image.
     • imageBase64 (string): base64-encoded image + mimeType. One image at a time. Do NOT combine with image/imageUrls.
 
     Delivering the bytes — this is where uploads most often fail:
-    • Pass a file as a file, in image: the platform resolves it into download_url and file_id before it reaches this tool — this includes files you created in your sandbox. This server does not share your filesystem, so a bare path string (e.g. /mnt/..., /home/user/..., /Users/...) is not a file. Without a file to pass, use a public http(s) URL (imageUrls) or the complete base64 (imageBase64).
+    • This server does not share your filesystem: outside image's clients, a file you can only reach by path (e.g. /mnt/..., /home/user/..., /Users/...) goes as imageBase64 (the whole file, one per call) or, if it is public, as imageUrls.
     • imageBase64 must be the WHOLE file, not truncated. For large images prefer imageUrls, since long base64 is easily cut off and will be rejected as unreadable.
   `,
-        SupportAndFeedback: dedent `
-    Send the user's feedback about the experience of building with Wix — the Wix MCP tools, APIs, docs, and tooling — to Wix, attributed to the authenticated user.
-    This is meta-feedback about building with Wix; it is NOT a support channel and not for the user's own site content.
+        // Registered for Claude clients only, beside UploadImageToWixSite.
+        PickImagesForWixMedia: dedent `
+    Shows a file picker where the user selects images from their device; they upload to the site's Media Manager and the result (each image's media ID and wixstatic URL) comes back in the conversation.
+    Use it only when you can't deliver the image yourself with UploadImageToWixSite: the image is on the user's device and not in your files, or it is a file in your sandbox that you can't pass as a file, a public URL or base64. When UploadImageToWixSite can take it, use that.
+  `,
+        ReportIssueToWix: dedent `
+    Report one specific problem with Wix's tools, APIs or docs to the Wix team, attributed to the authenticated user: an API error or a confusing API, wrong or missing docs, a Wix MCP tool or auth dead end. It is NOT a support channel and not for the user's own site content.
 
     When to offer it (user-approved only — NEVER auto-send):
-    - The user explicitly asks to send feedback / report something to Wix ("tell Wix that...", "report this", "send feedback"). Then just confirm the wording and send.
-    - The user complains, is frustrated, or reports a Wix bug in the course of the work ("this API is broken", "the docs are wrong", "why is this so hard"). Acknowledge, then offer to pass it on.
-    - The session hit substantial friction — repeated API failures, wrong/missing docs, a tooling dead end, or a workaround you had to invent. When you notice the pattern, offer: "This tripped us up a few times — want me to send it to Wix as feedback?"
-
-    When you offer, invite the user to add anything in their own words — whatever they give you goes into the message verbatim.
-
-    What to send — a summary of the whole run, not just the last error. Structure it in four layers:
-    1. Provenance — agent/model; Wix tooling used; platform/hosting; Wix areas/APIs touched; Wix products; project type/frontend; site id; relevant links (dashboard, docs pages, live site, repos); skill areas/recipes involved; other ids created this run.
-    2. Narrative — user intent and run summary (what they set out to build, what worked vs. what fought back); a condensed play-by-play of the session (key exchanges, tool calls, decisions, course-corrections).
-    3. Friction points — for each friction point: the step/endpoint, HTTP status and error message, the gap, the workaround you had to invent, and what you expected instead. Include ones you recovered from silently — a retry that eventually worked is exactly the signal Wix wants.
-    4. Attribution — per friction point, where the fault likely lives: API behavior / API schema / API reference docs / docs articles or examples / Wix tooling / other/unsure. Don't force a tag; "unsure" beats a wrong route.
-    End with a bottom line: one or two sentences on the single most important problem and its impact — a plain engineering assessment, not softened or hedged.
-
-    **IMPORTANT**: This tool actually sends the message to Wix. Confirm the final wording with the user and call it only after an explicit yes.
-    Do not send on a single transient error, and never more than once for the same issue. Feedback cannot be replied to or tracked by the user.
+    - The user asks to report something to Wix ("tell Wix that...", "report this", "send feedback"). Then confirm the wording and send.
+    - The user complains or reports a Wix bug in the course of the work ("this API is broken", "the docs are wrong"). Acknowledge, then offer to pass it on.
+    - A Wix API, tool or doc kept failing, or you had to invent a workaround for it. Offer: "This tripped us up — want me to report it to Wix?"
+
+    When you offer, invite the user to add anything in their own words — whatever they give you goes into the report verbatim.
+
+    What to send — that one issue, not the session:
+    - What was being attempted, in a sentence.
+    - Where it failed: the tool or endpoint, the HTTP status and error message, and the request id if there is one (pass it as requestId).
+    - What you expected instead, and the workaround if you found one.
+    - Where the fault likely lives: API behavior / API schema / API reference docs / docs articles or examples / Wix tooling / unsure.
+    - Only the context needed to reproduce it: agent/model, site id, the Wix area or API.
+    No session summary or play-by-play, and nothing unrelated to the issue. Several distinct issues are separate reports, each approved by the user.
+
+    **IMPORTANT**: This tool actually sends the report to Wix. Confirm the final wording with the user and call it only after an explicit yes.
+    Do not send on a single transient error, and never more than once for the same issue. Reports cannot be replied to or tracked by the user.
   `,
         BrowseWixRESTDocsMenu: dedent `
     Browse the Wix REST API documentation menu hierarchy.
@@ -460,28 +503,11 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     ${reminder}
   `,
         WixSiteCreation: dedent `
-    ${SITE_GUIDANCE}
-
-    Opens the in-chat Wix site creation chooser as an interactive widget where the user chooses between "Build with AI" and "Pick a template."
-
-    **Once you can tell what the site is for, call this tool directly** — no ${includeReadme ? 'WixREADME, skill,' : 'skill'} or docs search first.${includeReadme ? ' Any other Wix request still starts with WixREADME as usual.' : ''}
-
-    Call this for normal new Wix site creation requests when the user's site intent is clear, but they have not chosen AI, templates, or Wix Studio.
-    Do not guess, and never default to AI — even after the user answers a clarifying question about the site's purpose or features.
-    This chooser is how the builder choice gets made — never ask in chat whether they want AI or a template; that choice is made in the widget.
-    The widget also does the creating: once the user picks, it runs that path itself and the site is created there, so never call \`WixSiteBuilder\`, \`SearchSiteTemplates\`, or \`CreateSiteFromTemplate\` yourself after opening it.
-    After calling, reply with the message it returns, which presents both options and the next steps.
-
-    Do not call this if the user explicitly asks to build with AI; call \`WixSiteBuilder\` instead.
-    Do not call this if the user asks for templates or Wix Studio; call \`SearchSiteTemplates\` instead.
-
-    When calling this tool, infer \`customActions\` from the user's request so the reply can be tailored — 2-3 concrete, industry-specific setup actions for the site (see the input's guidance).
-
-    After calling, you MUST speak the message provided in the tool result to the user as your reply — do not stay silent and do not replace it with a one-line pointer to the widget. Write out ALL of it, word for word: its opening line (the "Ready to set up your … site?" question INCLUDING "Choose your path in the widget above:"), BOTH of its option bullets, and its "Next up:" line, each on its own line and in that order. Do not summarize, shorten, drop any line, invent your own opener, rename the options, or add an intro or outro.
+    A new Wix site is written in code and uploaded: call StartDeployWebsite for the upload guide, or StartHeadlessBuild when the site needs Wix business features. WixSiteBuilder or SearchSiteTemplates only when the user asked for the Wix Harmony Editor, a template, Wix Studio or the Classic Editor.
   `,
         'import-claude-design-from-url': dedent `
-    Import a design created in Claude's design tool into Wix. Takes the signed claudeusercontent.com URL Claude Design produces for its self-contained HTML bundle (all images, fonts, and styles inlined); any other host is rejected. Creates a live Wix-hosted site and returns its URL.
-    NOT for a page or site that exists in any other form (the user's own HTML/CSS/JS, a static build, a zip, another builder's export, a page you made in this conversation) — for those call StartDeployWebsite instead; it returns the recipe to publish the files yourself.
+    Import a design created in Claude's design tool into Wix. Only for the signed \`claudeusercontent.com\` bundle URL Claude Design's "Send to Wix" produces (a self-contained HTML bundle with all images, fonts, and styles inlined). Creates a live Wix-hosted site and returns its URL.
+    NOT for claude.ai share or artifact links, GitHub, Drive, chatgpt.com or any other URL, and not for files: those go to StartDeployWebsite, which returns the recipe to publish the files yourself.
   `,
         RunWixCliCommand: dedent `
     Executes Wix CLI commands for Wix app development and management.
@@ -507,6 +533,13 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
   `,
         SearchWixWDSDocumentation: dedent `
     Searches the Wix Design System (WDS) documentation.
+  `,
+        SearchWixHelpCenter: dedent `
+    Searches the Wix Help Center (support.wix.com): how site owners do things in the Wix dashboard and editors, such as connecting a domain, managing a Premium plan, setting up a store or bookings, and fixing account or site issues.
+    ${HELP_CENTER_IS_FOR_PEOPLE}
+    Use it for "how do I ... in Wix" questions about the product, or to give the user click-by-click steps for something no API covers.
+    Not for building with code: for Wix APIs, SDK, CLI, apps, or Headless, use the matching developer documentation search.
+    Results are excerpts; read a full article by passing its support.wix.com link to \`ReadFullDocsArticle\`.
   `,
         SearchWixSDKDocumentation: dedent `
     Searches the Wix JavaScript SDK documentation.
@@ -517,7 +550,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
   `,
         SearchDevelopmentDocumentation: dedent `
     Broad Wix development documentation (platform concepts, developer guides, getting started). **Last resort — development tasks only.**
-    Skip it entirely for general, business, support, or Wix-editor questions.
+    Skip it entirely for general, business, support, or Wix-editor questions; for those, use \`SearchWixHelpCenter\`.
     Call it only after the specific search for your task returned nothing useful: \`SearchWixRESTDocumentation\` (REST), \`SearchWixSDKDocumentation\` (JS SDK), \`SearchWixCLIDocumentation\` (CLI), \`SearchBuildAppsDocumentation\` (apps), \`SearchWixHeadlessDocumentation\` (Headless), \`SearchWixWDSDocumentation\` (WDS). Never use it as a first search.
   `,
         SearchWixHeadlessDocumentation: dedent `
@@ -529,7 +562,8 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
         // `sdk` is simply absent on methods the SDK docs don't list.
         SearchWixAPISpec: dedent `
     Inspect the Wix REST API spec, and the JavaScript SDK call for each method, by writing JavaScript code that runs in a sandboxed read-only environment.
-    **Precondition:** you already have a method \`docsUrl\` — from \`SearchWixRESTDocumentation\`, \`SearchWixSDKDocumentation\` (its \`?apiView=SDK\` URLs work here as-is), \`BrowseWixRESTDocsMenu\`, \`ReadFullDocsArticle\`, ${includeReadme ? 'a `WixREADME` recipe, ' : ''}or a prior tool result / the user's message in this conversation. If you don't have one yet, call \`SearchWixRESTDocumentation\` (or \`SearchWixSDKDocumentation\` when writing SDK code) FIRST to discover it; do not use this tool to search for or choose an endpoint.
+    The spec covers every Wix product's methods and their data: ${WIX_API_DATA}.
+    **Precondition:** you already have a method \`docsUrl\` — from \`SearchWixRESTDocumentation\`, \`SearchWixSDKDocumentation\` (its \`?apiView=SDK\` URLs work here as-is), \`BrowseWixRESTDocsMenu\`, \`ReadFullDocsArticle\`, ${includeReadme ? 'a Wix skill, ' : ''}or a prior tool result / the user's message in this conversation. If you don't have one yet, call \`SearchWixRESTDocumentation\` (or \`SearchWixSDKDocumentation\` when writing SDK code) FIRST to discover it; do not use this tool to search for or choose an endpoint.
     **Never pass a \`docsUrl\` you produced from memory.** If the exact URL you are about to pass to \`getResourceSchemaByUrl\` did not appear verbatim in an earlier tool result (or the user's message), it is a guess — call \`SearchWixRESTDocumentation\` first and use a URL from its ranked results. A guessed URL that merely looks plausible routinely resolves to the WRONG sibling method (e.g. \`.../products-v3/create-product\` when the task needs \`.../products-v3/create-product-with-inventory\`), sending the whole turn down a dead end. When in doubt, discover — don't guess.
     **This tool's job is to INSPECT the exact schema of a method you have ALREADY located — its request/response shape, nested types, and enums, and its SDK call (\`method.sdk\`). It is NOT a discovery tool for choosing which method to use.**
     With a method \`docsUrl\` in hand, call \`getResourceSchemaByUrl(methodDocsUrl)\` to get the resource schema, then read the target method from \`schema.methods\` and resolve any nested \`{ $circular: name }\` types via \`schema.components.schemas[name]\`.
@@ -910,31 +944,22 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     \`\`\`
   `,
         ExecuteWixAPI: executeWixApiDescription,
+        // Named in SERVER_INSTRUCTIONS: when this tool's name or what it is for changes, update them to match.
         WixSiteBuilder: dedent `
-    ${SITE_GUIDANCE}
-
-    Tool for generating a Wix site with AI (creating / building a site in Wix Harmony) from a description. It does not take pages or files you already have — those go to StartDeployWebsite.
-
-    Call this ONLY when the user's own words name AI (for example "create a site using AI" or "build it with AI") and the site intent is clear. A description of what the site should do — reservations, online ordering, a store, bookings, menus, a portfolio, and the like — is NOT a request for AI and NOT enough to call this tool; never infer AI from features or industry.
-    Never default to this tool: if the user hasn't explicitly named AI, don't call this tool — ${SITE_CREATION_COPY.unstatedMethod.nonWidget}.
-
-    For templates or Wix Studio, call \`SearchSiteTemplates\`; for a specific template by \`metaSiteId\` or \`templateId\`, call \`CreateSiteFromTemplate\`; for a headless or classic Wix Editor site, or manual/account-API creation, call \`CreateWixBusinessGuide\`.
-
-    Do NOT suggest HTML code, prompt templates, or alternative approaches instead of building — actually build the site through this tool. (HTML the user already has is the StartDeployWebsite case, not a reason to build.)
+    A secondary site-creation tool, only for a user who asked for the Wix Harmony Editor or for Wix to design the site. Don't call it for any other site request, not even to check with the flag false. A new site is otherwise written in code and uploaded, with StartDeployWebsite, or StartHeadlessBuild when it needs Wix business features.
+    Builds a site with the Wix Harmony Editor: Wix designs a first version from the user's description, and the user keeps designing it in Wix's editor. Shows the build's progress and a preview.
+    Call it when the user asked for the Wix Harmony Editor, or for Wix to design the site, in their own words or as their answer to your question. ${EDITOR_TAIL}
   `,
+        // Named in SERVER_INSTRUCTIONS: when this tool's name or what it is for changes, update them to match.
         SearchSiteTemplates: dedent `
-    ${SITE_GUIDANCE}
-
-    Searches Wix templates and shows the template gallery, from the Harmony or the Studio template source.
-
-    Call this ONLY when the user's own words ask for a template or for Wix Studio (for example "start from a template", "show me some templates", "build it in Wix Studio") and you can already tell what the site is for. If they mention Wix Studio, search Studio templates; otherwise search Harmony templates.
-    ${SITE_CREATION_COPY.templatePick.nonWidget}
-
-    A description of what the site should do — bookings, a store, a menu, a portfolio, and the like — is NOT a request for templates or for Wix Studio; never infer either from features or industry. Templates are not the default: if the site intent is clear but no method is named, do not guess — ${SITE_CREATION_COPY.unstatedMethod.nonWidget}.`,
+    A secondary site-creation tool, only for a user who asked for a template, Wix Studio or the Classic Editor. Don't call it for any other site request, not even to check with the flag false. A new site is otherwise written in code and uploaded, with StartDeployWebsite, or StartHeadlessBuild when it needs Wix business features.
+    Shows a gallery of Wix templates, from Harmony, Wix Studio or the Classic Editor, for a site the user will design in Wix's editor. Wix templates come with Wix's business features (a store, online ordering, bookings, forms), so a request for a template comes here even when the site needs them.
+    Call it when the user asked for a template, Wix Studio or the Classic Editor, in their own words or as their answer to your question. ${EDITOR_TAIL} ${SITE_CREATION_COPY.templatePick.nonWidget}
+  `,
         CreateSiteFromTemplate: dedent `
     Creates a Wix site from a specific template (by \`metaSiteId\` or \`templateId\`), publishes it when possible, and shows a live preview with links to the editor and the published site.
 
-    Call this when the user provides a specific template by \`metaSiteId\` or \`templateId\`. Use this only when the user gives a valid \`metaSiteId\` or \`templateId\` directly. To browse or choose a template first, call \`SearchSiteTemplates\`.
+    Call this when the user provides a specific template by \`metaSiteId\` or \`templateId\`. Use this only when the user gives a valid \`metaSiteId\` or \`templateId\` directly. To browse or choose a template first, call \`SearchSiteTemplates\` (\`builder: classic\` for a Classic Editor site).
 
   `,
         SearchWixGraphQLOperations: dedent `
@@ -963,103 +988,194 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     Results: each root field fails independently — \`errors[].path\` names the failing field and \`errors[].extensions.message\` the cause (e.g. PERMISSION_DENIED); \`data\` still holds the fields that succeeded. Mutations return the created/updated entity — read the IDs from it and do not re-query to verify. Large results are truncated: narrow the selection or page size instead of re-running.
     Set \`hasMutations: true\` for any document containing a mutation root field.
   `,
+        UploadHeadlessWebsiteFiles: dedent `
+    The upload step of the StartDeployWebsite and StartHeadlessBuild guides, and nothing else: puts a finished website's files — a static site (index.html plus its CSS/JS/images, a static build, or a zip of the site) or a Wix Astro build — onto an existing Wix Headless site by its metaSiteId. Call it ONLY after one of them has returned its guide in this conversation and the site exists: for a new site, first run the recipe's provision call and pass the metaSiteId it returns; for a site deployed earlier, pass its metaSiteId. It does not create sites. Every upload replaces the whole file set and the URL stays. Returns the live URL and the dashboard link, and points back to the recipe for what comes next.
+    Pass the files themselves: in ${FILE_PARAM_CLIENTS} as \`attachments\` (any type, a zip is unpacked), elsewhere as the \`files\` text bundle (\`=== FILE: <path> ===\` sections, \`base64\` tag for small binaries). A static site must contain index.html at its root. A Wix Astro build with no file handle, from a shell that reaches the internet, goes in two calls: zip the build, call with \`prepare: true\` and the zip's \`size\` in bytes, PUT the zips it names with the \`curl\` commands it returns (the build, and the project source when the site's repository accepts it), then call again with the \`uploadKey\` it returned; that releases the build. The two calls, literally: {siteId, prepare: true, size} then {siteId, uploadKey, sourceUploadId?, expectedHeadRevisionId?, releaseNotes?}. A sandbox whose network is limited to a few hosts cannot upload to those URLs. A static site does not use the two calls. A Wix Astro build (the project's .wix/ and dist/ after \`astro build\` with the Wix hosting adapter, zipped from the project root) needs no index.html: it is released to the site's Wix hosting instead, server-rendered pages, the same site and URL. The project's source is stored with the release when the upload holds the project and the site's repository accepts it.
+    NOT a site-creation tool: a request to create, build, design or generate a site — with or without a description — never comes here first. Unless the user asked for Wix's editor or a template (WixSiteBuilder, SearchSiteTemplates), call StartDeployWebsite right away, without asking the user anything: it also takes files the user brought, uploaded first even when the site needs business features. StartHeadlessBuild instead for a new site with no files that needs Wix business features. Also NOT for media uploads to an existing site (UploadImageToWixSite) or any other API call (ExecuteWixAPI).
+  `,
+        // Named in SERVER_INSTRUCTIONS: when this tool's name or what it is for changes, update them to match.
         StartDeployWebsite: dedent `
-    The user — or you, earlier in this conversation — ALREADY HAVE a finished page or site, in any form, and it should be live on Wix — or an already-deployed Wix Headless site whose files should be replaced. The site can be HTML/CSS/JS files, a static build (dist/, out/), a zip, another AI builder's export, or a page/design you created in this conversation (export it to HTML first — a finished design IS a finished page). Call this when the user says deploy, host, publish, put online, make it live, get a URL, update my site, or upload my site / index.html.
-    Updates keep the same site and URL. Also for implementing a backend on such a site as a Wix Headless project — same site, same URL. Works with or without a Wix login (anonymous deploy with a save link), through the Wix MCP alone or from a shell.
-    Missing real functionality — a fake checkout, a form that goes nowhere, bookings — is NOT a reason to rebuild the site with a site-creation tool: deploy the page as is, then add the backend afterwards (the recipe covers it).
-    Returns the full recipe; follow it and run the flow yourself. The drop page is only the fallback when you can't.
-    NOT for: a screenshot, mockup or reference image of a site the user WANTS (nothing exists to deploy yet — that is site creation: WixSiteBuilder / templates); a Claude Design share URL (import-claude-design-from-url); migrating a live site by URL or CSV exports; adding HTML or code into an existing Wix site; uploading images or documents to a site's media (UploadImageToWixSite).
+    Creates a website on Wix and puts it live, or replaces the files of one deployed earlier. You write the site's code, or take the files the user brought (HTML/CSS/JS, a static build, a zip, another builder's export), and this returns the guide to create the site and upload them. Updates keep the same site and URL. Works with or without a Wix login (anonymous deploy with a save link), through the Wix MCP alone or from a shell. Call it right away, without asking the user anything first.
+    When a new site needs Wix business features (${WIX_BUSINESS_FEATURES}), call StartHeadlessBuild instead. When the user brought files and the site needs those features, upload the files here first; the upload's result then points to StartHeadlessBuild to connect them.
+    Returns the guide; follow it and do the work yourself. Upload with UploadHeadlessWebsiteFiles once the site exists; the drop page is only the fallback.
+    NOT for: a user who asked for Wix's editor, the Wix Harmony Editor, a template, Wix Studio or the Classic Editor (WixSiteBuilder, SearchSiteTemplates); a Claude Design bundle URL (import-claude-design-from-url); migrating a live site by URL or CSV exports; adding HTML or code into an existing Wix editor site; uploading images or documents to a site's media (UploadImageToWixSite).
   `,
-        CreateWixBusinessGuide: dedent `
-    Provides comprehensive documentation for creating a new Wix business (site, app, etc.).
-    Call this ONLY when the user explicitly asks for a headless site, a Wix Classic Editor site, or manual/advanced account/API-based site creation — these don't need the site's purpose first. For normal site-creation ${SITE_CREATION_COPY.normalCreationRoute.nonWidget}; for a specific template id, call \`CreateSiteFromTemplate\`.
-    Exception, even when the user says "headless": if a finished page or site already exists in any form (their own HTML/CSS/JS, a static build, a zip, an AI-builder export, a page you made in this conversation) and they want it hosted, don't call this tool — call StartDeployWebsite, which returns the recipe to publish the files yourself. This guide's CLI flow is for BUILDING a headless frontend, not for hosting ready-made files.
-
-    ## What This Tool Contains
-
-    This tool provides complete documentation including:
-    - Template selection (empty sites or designed templates)
-    - Wix Editor vs Wix Studio options
-    - Regular vs Headless site creation (CLI-based; returns setup instructions)
-    - API endpoint details and parameters
-    - Post-creation steps (OAuth for headless, publishing for regular sites)
-    - App installation instructions
-
-    ## After Reading This Documentation
-
-    **After reading this documentation:**
-    1. Use ManageWixSite for account-level site creation API calls
-    2. Use CallWixSiteAPI / ExecuteWixAPI for site-level follow-up API calls (like install apps if needed)`
+        // Named in SERVER_INSTRUCTIONS: when this tool's name or what it is for changes, update them to match.
+        StartHeadlessBuild: dedent `
+    Returns Wix's headless guide, for a site that needs Wix business features (${WIX_BUSINESS_FEATURES}), run by Wix as a Wix Headless site. You write the site; the guide creates it, connects the features, and uploads it. Also to add those features to an existing Wix Headless site (one deployed from files is one), from a project download link, or to move a Wix site to code.
+    Call it right away: it only returns the guide, and the site's details are not needed first.
+    NOT for: a site that needs no Wix business feature, or files the user brought that are not live yet (StartDeployWebsite: upload them first, then come back here for the features); a user who asked for Wix's editor, the Wix Harmony Editor, a template, Wix Studio or the Classic Editor, even when the site needs business features (WixSiteBuilder, SearchSiteTemplates); a Claude Design URL (import-claude-design-from-url).
+  `
     };
+    // The tool's former name, kept for importers that read it by that key.
+    descriptions.SupportAndFeedback = descriptions.ReportIssueToWix;
+    return descriptions;
 }
 /**
  * Canonical (README-inclusive) tool descriptions used by the live MCP server and
  * all existing importers.
  */
-export const defaultToolDescriptions = buildToolDescriptions(true);
+export const defaultToolDescriptions = buildToolDescriptions(true, true, { usageGuideOnce: true });
 export const executeCodeModeToolDescriptions = {
     ExecuteWixAPI: executeWixApiDescription
 };
+// Hand-maintained list of the skills in the Wix skills registry
+// (https://www.wix.com/skills, generated from github.com/wix/skills). When a
+// skill is added or renamed there, update this section.
+export const WIX_SKILLS_README_SECTION = dedent `
+  ## Wix skills
+
+  Wix publishes agent skills: folders of instructions, scripts and shipped code for building on Wix, each with a \`SKILL.md\` at its root that says what the skill does and which of its files to read when. The source is https://github.com/wix/skills. Three of them matter here:
+
+  - **wix-headless-kit**: builds a Wix Headless site on shipped, verified code. In the Wix plugin. Its contents are below.
+  - **wix-headless-templates**: the code wix-headless-kit builds from, one folder per Wix Business Solution. In the Wix plugin for Codex and Cursor. Its contents are below.
+  - **wix-manage**: REST recipes to configure and manage a site's business solutions. In the Wix plugin. Its \`SKILL.md\` is the index of every recipe by area, with what it does and a link to read it.
+
+  On a site built in code (one deployed through StartDeployWebsite, started through StartHeadlessBuild, or any Wix Headless project), wix-headless-kit carries the work, with wix-headless-templates as its code, and it names the wix-manage recipes it uses as steps.
+
+  ### How to read a skill
+
+  A skill is a folder, and every file in it has a path inside that folder (\`SKILL.md\`, \`guides/api-run.md\`). The same path finds the file on disk and online, so the paths below work either way.
+
+  1. **From disk, when it is already there.** This is the preferred way: the files are complete and need no network. The Wix plugin loads its skills into the client; \`npx skills add\` puts them under \`.agents/skills/<skill>/\` in the project, or in the user's home with \`-g\`; an earlier install may have left them wherever the client keeps skills (for example \`.claude/skills/\` or the plugin's folder). Open \`<skill folder>/SKILL.md\` and the files it names. An installed copy can be an older snapshot. A file whose byte size differs from the one in the skill's manifest (below) is out of date, so read it online; a matching size makes a file likely current, not certain, so when a file decides the work, read it online too.
+  2. **Install them, with a shell that reaches the internet.** \`npx skills add wix/skills\` installs every skill; \`npx skills add wix/skills --skill wix-headless-kit\` installs one. Then read them from disk. To keep them across projects, the user can install the Wix plugin instead (in Claude Code: \`/plugin marketplace add wix/skills\`, then \`/plugin install wix@wix\`).
+  3. **Read them online, with ReadFullDocsArticle**, when neither works: no shell, or a sandbox without internet. Call ReadFullDocsArticle with the URL as \`articleUrl\`; it returns the file whole, where a client's own web tool often cannot reach www.wix.com or summarizes what it fetches. The skills registry mirrors every skill from the main branch of wix/skills:
+     - **A file**: \`https://www.wix.com/skills/<skill>/<path>\`, with \`<path>\` its path inside the skill folder. Start with \`<path>\` = \`SKILL.md\`, then read the files it names.
+     - **A folder**: \`https://www.wix.com/skills/<skill>/<folder>\` returns the full URL of every file under it, at any depth. \`https://www.wix.com/skills/<skill>/<folder>/_content\` returns those files' contents in one response, each under a heading with its URL, Markdown first; binary files and lockfiles are left out, and past 150K characters the rest are named by URL, to read one by one.
+     - **The skill's file list**: \`https://www.wix.com/skills/<skill>/\`, with the trailing slash, returns the full URL of every file in the skill; without the slash it returns the SKILL.md.
+     - **Every file in the skill**: \`https://www.wix.com/skills/<skill>.manifest.json\` lists each path with its size, under a \`base\` URL.
+     - **Names and hosts**: \`<skill>\` is the folder name with or without its \`wix-\` prefix (\`wix-headless-kit\` or \`headless-kit\`), and \`dev.wix.com\` works in place of \`www.wix.com\`.
+     - **What comes back**: a Markdown file comes with a short note on top (it is mirrored from the main branch of wix/skills; the skill's manifest, folder listings, \`_content\`, and ReadFullDocsArticle) and its relative links turned into full URLs; code, scripts and JSON come as they are.
+     - **A wrong path**: the answer names the files with that name elsewhere in the skill and the manifest URL, so one more call reaches the right file. ReadFullDocsArticle shows that answer as an error.
+     - **Not served**: a whole skill as one page (\`<skill>-full\`) returns 404; read the skill's files instead.
+
+     The wix-manage recipes are also published in the Wix docs, as articles at \`…/skills/<recipe>\` under each API's section. Find the one that matches the task in the skill's recipe index (\`SKILL.md\`) or with SearchWixRESTDocumentation, and read it with ReadFullDocsArticle. Only wix-manage is in the docs. For example, one recipe in all three places:
+       - on disk: \`<wix-manage folder>/references/sites/upload-static-site.md\`;
+       - in the registry: https://www.wix.com/skills/manage/references/sites/upload-static-site.md;
+       - in the docs: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.
+
+  ### wix-manage
+
+  REST recipes for managing a site's business solutions: one recipe per task (installing apps, products, booking services, CMS items, SEO, domains and more), each with the exact endpoints, request bodies and order of steps. Open the recipe for a task before calling its APIs.
+
+  Ways to find and read a recipe, in this order:
+  1. **On disk**: the Wix plugin's wix-manage folder, or \`.agents/skills/wix-manage/\` after \`npx skills add wix/skills --skill wix-manage\`. \`SKILL.md\` lists every recipe by area with what it does; the recipe itself is under \`references/<area>/\` (ecommerce nests one more folder, such as \`references/ecommerce/shipping/\`), so open the path \`SKILL.md\` gives rather than building it. An installed copy can be an older snapshot: when a recipe decides the work, read it online too.
+  2. **Online**: the list of every recipe by area, each a link to its docs article, is https://dev.wix.com/docs/api-reference/articles/ai-tools/wix-mcp/skills/wix-management-recipes-index.md. Read it with ReadFullDocsArticle, or with \`curl\` from a shell, then read the recipe for the task the same way. It is public: no sign-in or token.
+
+  Using a recipe: follow its steps, and make its calls with ExecuteWixAPI, passing the recipe's docs URL in \`sourceDocUrls\`. When a recipe's example doesn't fit a call, read that method's schema with SearchWixAPISpec first. When no recipe matches the task, find the method with SearchWixRESTDocumentation or BrowseWixRESTDocsMenu, read it with ReadFullDocsArticle, and call it the same way.
+     Each API area also has a page that lists only its own recipes: the area's docs section with \`/skills.md\` appended. These are the ones today, but it is not a closed list: areas are added, so look a task up in the full list first, and for an API not named here try its section URL with \`/skills.md\` appended.
+     - Accessibility: https://dev.wix.com/docs/api-reference/site/accessibility/skills.md
+     - Analytics: https://dev.wix.com/docs/api-reference/business-management/analytics/skills.md
+     - App Installation: https://dev.wix.com/docs/api-reference/business-management/app-installation/skills.md
+     - App tools: https://dev.wix.com/docs/api-reference/app-management/app-tools/skills.md
+     - Automations: https://dev.wix.com/docs/api-reference/business-management/automations/skills.md
+     - Blog: https://dev.wix.com/docs/api-reference/business-solutions/blog/skills.md
+     - Bookings: https://dev.wix.com/docs/api-reference/business-solutions/bookings/skills.md
+     - Calendar: https://dev.wix.com/docs/api-reference/business-management/calendar/skills.md
+     - CMS: https://dev.wix.com/docs/api-reference/business-solutions/cms/skills.md
+     - Contacts: https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/skills.md
+     - Domains: https://dev.wix.com/docs/api-reference/account-level/domains/skills.md
+     - eCommerce: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills.md
+     - Events: https://dev.wix.com/docs/api-reference/business-solutions/events/skills.md
+     - Forms: https://dev.wix.com/docs/api-reference/crm/forms/skills.md
+     - Get Paid: https://dev.wix.com/docs/api-reference/business-management/get-paid/skills.md
+     - Google Ads: https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/skills.md
+     - Google Business Profile: https://dev.wix.com/docs/api-reference/business-management/google-business-profile/skills.md
+     - Google Search Console: https://dev.wix.com/docs/api-reference/business-management/seo/google-search-console/skills.md
+     - Headless: https://dev.wix.com/docs/api-reference/business-management/headless/skills.md
+     - Marketing: https://dev.wix.com/docs/api-reference/business-management/marketing/skills.md
+     - Media: https://dev.wix.com/docs/api-reference/assets/media/skills.md
+     - Pricing Plans: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/skills.md
+     - Restaurants: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/skills.md
+     - Rich Content: https://dev.wix.com/docs/api-reference/assets/rich-content/skills.md
+     - SEO: https://dev.wix.com/docs/api-reference/business-management/seo/skills.md
+     - SEO redirects: https://dev.wix.com/docs/api-reference/business-management/seo/redirects/skills.md
+     - Site Properties: https://dev.wix.com/docs/api-reference/business-management/site-properties/skills.md
+     - Sites: https://dev.wix.com/docs/api-reference/account-level/sites/skills.md
+     - Stores: https://dev.wix.com/docs/api-reference/business-solutions/stores/skills.md
+     - Wix MCP: https://dev.wix.com/docs/api-reference/articles/ai-tools/wix-mcp/skills.md
+
+  ### wix-headless-kit
+
+  Builds a Wix Headless site on shipped, verified code instead of writing the integration: each Wix Business Solution comes with a typed data layer, hooks, components, pages and a seed script that are already correct. The data layer ships twice, on \`@wix/sdk\` for the React core and as plain REST calls for a stack that cannot run it (\`guides/reference-mode.md\`), and the agent's work narrows to brand, layout, copy and wiring. It runs as a CLI flow from a shell that reaches Wix, and as Wix API calls through this MCP when it cannot.
+
+  Paths are inside the skill folder; online, each is \`https://www.wix.com/skills/headless-kit/<path>\`.
+  - Before the skill: the cold start installs it, signs in and hands off. It is another skill's file, https://www.wix.com/skills/headless-cold-start/headless-kit.md, and StartHeadlessBuild returns it.
+  - \`SKILL.md\`: the steps of a build and the table of Business Solutions the kit ships.
+  - \`guides/api-run.md\`: the whole run as Wix API calls through this MCP, for an agent whose shell cannot reach Wix or that has no shell.
+  - \`guides/capabilities.md\`: which Wix product owns which feature, and what the kit ships for it.
+  - \`guides/existing-site.md\`: a new frontend for a Wix site that already has its content.
+  - \`guides/migration.md\`: a site moving to code after "Go Headless" in its dashboard.
+  - \`guides/reference-mode.md\`: a stack that cannot run the shipped React code (a static site, a server-rendered app in another language).
+  - \`guides/feedback.md\`: sending the user's building-with-Wix feedback to Wix.
+  - \`install/\`: the bootstrap, setup, deploy and templates scripts, and \`install/pins.json\` with the pinned CLI and templates versions.
+
+  ### wix-headless-templates
+
+  The code wix-headless-kit builds from, one folder per Wix Business Solution: \`storefront\`, \`bookings\`, \`rentals\`, \`blog\`, \`cms\`, \`forms\`, \`members\`, \`events\`, \`restaurants\`, \`donations\`, \`pricing-plans\`, \`portfolio\`, \`faq\`. It holds no flow of its own; wix-headless-kit fetches it and copies, deploys and seeds from it.
+
+  Paths are inside the skill folder; online, each is \`https://www.wix.com/skills/headless-templates/<path>\`. Every Business Solution folder has the same parts, with \`<solution>\` one of the names above:
+  - \`<solution>/INSTRUCTIONS.md\`: the playbook, covering what ships, what you build, and each page's contract.
+  - \`<solution>/app/\`: the typed React core: the data layer under \`wix/<solution>/\`, hooks and components.
+  - \`<solution>/app-astro/\`: the Astro page skeletons for Wix-managed Astro sites (every solution but \`forms\`).
+  - \`<solution>/project/\`: the whole runnable project for that solution.
+  - \`<solution>/rest/\`: the same data layer as plain REST calls, for stacks that cannot run the React core.
+  - \`<solution>/seed/SEED.md\`: how to seed that solution's content, with the script that creates it in the right order.
+
+  Shared by every solution:
+  - \`shared/DESIGN.md\`: the design floor when the brief gives no design direction.
+  - \`shared/CONTENT.md\`: the copy floor for every page written.
+  - \`shared/SUPPLIED-CONTENT.md\`: content the user brings (a CSV, a menu, a folder of photos) as the seed plan.
+  - \`shared/CUSTOM_OPERATIONS.md\`: operations beyond what the shipped code covers.
+  - \`shared/rest/client.ts\`: the REST client the \`rest/\` layers use.
+
+  Online, a solution's folder lists everything it ships: https://www.wix.com/skills/headless-templates/storefront returns the URLs of the store's files, and \`…/storefront/app\` those of its React core. A part is often small enough to read whole in one call: https://www.wix.com/skills/headless-templates/storefront/seed/_content returns the store's seeding guide and scripts together. A whole solution passes the 150K cap, so read it part by part.
+`;
 const recipesIndexDoc = {
     url: 'https://dev.wix.com/docs/api-reference/articles/ai-tools/wix-mcp/skills/wix-management-recipes-index',
     action: 'include'
 };
 const README_INTRO = dedent `
-  <agent-mandatory-instructions>
+  # How to work with Wix through these tools
 
-  YOU MUST READ AND FOLLOW THE AGENT-MANDATORY-INSTRUCTIONS BELOW:
+  ## Source of truth
 
-  <source-of-truth>
-  Do not answer from memory about anything Wix-specific — this covers every part of your answer, not only API calls: any URL, link, ID, setting location, or product fact you give the user must come from the docs tools, the recipes below, a previous tool result in this conversation, or the user's own message (identifiers and URLs the user supplies are fine to use as given). If a recipe in the index below matches what the user asked for, read it before answering. For APIs, use the search, browse, read-docs, and schema tools as the source of truth for the exact URL, HTTP method, request body shape, response shape, field names, required fields, and enum values before calling an API.
-  </source-of-truth>
+  Do not answer from memory about anything Wix-specific — this covers every part of your answer, not only API calls: any URL, link, ID, setting location, or product fact you give the user must come from the docs tools, a Wix skill (installed, or read online as the Wix skills section below explains), a previous tool result in this conversation, or the user's own message (identifiers and URLs the user supplies are fine to use as given). When a Wix skill covers what the user asked for, read it before answering. For APIs, use the search, browse, read-docs, and schema tools as the source of truth for the exact URL, HTTP method, request body shape, response shape, field names, required fields, and enum values before calling an API.
 
-  <management-flow>
-  <goal>
+  ## Goal
 `;
-const README_FLOWS_HEADING = dedent `
-  </goal>
+const README_FLOWS_HEADING = '## Wix MCP Flows';
+const README_FLOWS_SITE = dedent `
+      ### The site
 
-  ## Wix MCP Site Management Flows
+      The site context below lists the account's sites with their installed apps. Take the \`siteId\` from there; when more than one site fits and the user's words don't pick one, ask which before any read or write. A business solution's API (Stores, Bookings, CMS and the rest) works only on a site with that app installed, and some apps have versions with different endpoints (Wix Stores V1 vs V3): check the site's apps first, and when the app is missing, install it (a Wix skill has the steps) before using its API.
 `;
-const README_BODY = dedent `
-      ### Discovery & Call Flow
+const README_FIND_SOURCES = dedent `
+  ### Find the method
 
-      Common paths (use the highest you can satisfy for each method you'll call):
-      - Already have what you need from previous tool results in this conversation (not from memory) → ExecuteWixAPI
-      - Pick a matching article from the Recipes index below → ReadFullDocsArticle (find relevant code examples) → (probe SearchWixAPISpec for response shapes if needed) → ExecuteWixAPI
-      - SearchWixRESTDocumentation or BrowseWixRESTDocsMenu → ReadFullDocsArticle (find relevant code examples) → (probe SearchWixAPISpec for response shapes if needed) → ExecuteWixAPI
-      - SearchWixRESTDocumentation or BrowseWixRESTDocsMenu → ReadFullDocsArticle (no usable example) → SearchWixAPISpec for request schemas → ExecuteWixAPI
+  A task may need several API methods. For each, take the first source that gives it:
+  - A previous tool result in this conversation (not memory) already shows its request: go straight to the call.
+  - A Wix skill that covers the task (the Wix skills section below says what each is for): follow it, from disk or online. When its example for a call matches your case, that is the source: pass its docs URL in \`sourceDocUrls\` instead of searching for the method pages (when it has no docs URL, one SearchWixRESTDocumentation call on its title finds the article).
+  - The docs: SearchWixRESTDocumentation (semantic search) or BrowseWixRESTDocsMenu (menu hierarchy), then ReadFullDocsArticle on the method's article for its code examples. For SDK code, the CLI, a headless site or an app, start from those docs instead: SearchWixSDKDocumentation, SearchWixCLIDocumentation, SearchWixHeadlessDocumentation, SearchBuildAppsDocumentation.
 
-      Fallbacks: use ReadFullDocsMethodSchema in place of SearchWixAPISpec when SearchWixAPISpec is unavailable or didn't return enough detail; use CallWixSiteAPI in place of ExecuteWixAPI when a single REST call is enough and code adds no value.
+  Keep each method's docs URL even when no source gives a usable example: the shape comes from its schema, as the next section says.
+`;
+const README_FLOWS_BODY = dedent `
+      ### The exact shape
 
-      Tools (relevant for the management flow):
-      - SearchWixRESTDocumentation — semantic search over the Wix REST docs by keywords or natural-language queries.
-      - BrowseWixRESTDocsMenu — navigate the Wix REST docs by menu hierarchy; alternative to keyword search.
-      - ReadFullDocsArticle — fetch a full docs article by its docs URL; returns prose, fields, and code examples.
-      - SearchWixAPISpec — JS-sandboxed query over the REST API spec; returns request schema, response schema, and the executable \`method.publicUrl\`.
-      - ExecuteWixAPI — runs an async JS function in a sandbox with \`wix.request()\`; a single invocation can chain multiple API calls, paginate, loop, transform, and branch.
+      A code example is the model for your call only when it matches your case, with every field your case needs. Fill the rest from the method's schema: SearchWixAPISpec on its docs URL (REST or SDK) returns the request and response schemas, \`method.publicUrl\` and \`method.sdk\`; ReadFullDocsMethodSchema when SearchWixAPISpec isn't available. A query's filter and sort fields and operators are a closed list per method: use only what its schema declares.
 
-      Steps:
+      None of this comes from memory.
 
-      1. A single user task may need one or more API methods. For each method you'll call, find a code example that fits the user's intent — you'll model the API call (URL, method, body) on it. An example only "fits" if it is **complete** (not truncated) AND matches your exact case — same operation and same variant/shape (e.g. the same \`productType\`), with every field your case needs actually shown. **If the closest example is truncated (it shows a \`... N more lines ...\` marker), do NOT call the API off it; continue discovery first: \`ReadFullDocsArticle\` for the complete example, or \`SearchWixAPISpec\` for the exact request schema.** Never fill in required fields from memory. Skip this step for any method you already have from a previous tool result in this conversation (not from memory):
-         a. First try the WixREADME Recipes index below (pre-curated guides for common tasks). If a recipe matches, ReadFullDocsArticle on its docs URL to find relevant code examples; many recipes cover multi-step flows and supply code examples for several methods in one article.
-         b. If no recipe matches the user's intent, or the matched recipe didn't yield the code examples you need, discover each missing method's docs URL via SearchWixRESTDocumentation (semantic search) or BrowseWixRESTDocsMenu (menu hierarchy), then ReadFullDocsArticle on each to find relevant code examples.
-         c. If neither path turns up a usable code example for some method, continue without one for that method — step 2 will derive its request directly from the schema. Make sure you've still captured the docs URL of each method.
+      ### The call, or the code that makes it
 
-      2. Before calling, fill any remaining gaps with SearchWixAPISpec on each method's docs URL. It returns both request and response schemas. For each method, check:
-         - **Request** (URL, HTTP method, body fields) — skip the probe if a code example already shows them; otherwise SearchWixAPISpec returns publicUrl + exact request shape.
-         - **Response shape** (field paths your code will read) — only relevant if your code reads response fields; skip the probe if the article(s) already made it clear; otherwise probe SearchWixAPISpec for the response schema.
-         - **Filter and sort** (query/search methods only) — an example proves only the fields and operators it uses. Each method declares which fields it can filter and sort by, and with which operators; that list is closed for fields and their operators and covers that method only — \`$and\`/\`$or\`/\`$not\` are filter syntax and never appear in it. Anything else errors or silently returns the wrong rows. A listed operator is valid on its own, since a field takes a single operator; to combine conditions, use the logical operators instead — \`$and\` and \`$or\` take an array of expressions, \`$not\` takes one, and they can nest.
-         - Never guess any of this from memory.
+      **Call it with ExecuteWixAPI**: one async JS function with \`wix.request()\`, holding every step of the task that code can resolve. The reads that fetch an ID, check whether a record exists or list items to choose from go in the same function as the writes they feed; step numbers in a guide or skill give logical order, not separate calls. Set \`hasMutations: true\` when any step writes. Return the write's response as is and report from it; don't read again to confirm. A new invocation only for what code can't resolve: the user's answer, or a job that finishes later. One function chains calls, paginates, lists all, loops, transforms and branches. Without ExecuteWixAPI, make each call with CallWixSiteAPI (a site's APIs) or ManageWixSite (the account's), from the same exact shape.
 
-      3. Before calling: collapse ALL planned steps — preliminary reads AND mutations — into a single async function. Step numbers in any guide or skill doc describe logical order for human comprehension — they do NOT define invocation boundaries. Steps that feed into each other belong in a single invocation: read, use the result, write, and return. A read that fetches IDs or checks existence before a create/update is part of that mutation's invocation, not a separate preceding call. This includes any read whose result feeds directly into a subsequent write — fetching a required ID, checking whether a record already exists, listing items to choose one — all belong in the same invocation as the write that follows. Set hasMutations: true whenever any step in the function writes. Return the mutation response directly — do not follow up with a read to confirm what was just created or updated; trust the response. Only split into multiple invocations when a later step genuinely depends on information you cannot resolve in code (e.g. a user decision or an out-of-band event). A single invocation can chain several related calls, paginate, "list all", loop, transform, and branch on responses.
+      **Write the code** when the task is code the user keeps: an app (built and run with the Wix CLI), a headless site, or a script that calls the REST API or the JavaScript SDK. The path is the same: find the method, learn its exact shape, then write the call from \`method.publicUrl\` (REST) or \`method.sdk\` (the JavaScript SDK), never from memory. Every way of building against Wix in code is this path; the headless skills are a shortcut on it, not a different one. wix-headless-kit builds a Wix Headless site from shipped, verified code (wix-headless-templates holds it, one folder per business solution: a \`@wix/sdk\` React core, and the same data layer as plain REST calls for a stack that cannot run it): scaffold with the CLI, deploy, seed, design the presentation on the shipped code, release. What no shipped solution covers is written from the docs, as above. A new site is written in code and uploaded: StartDeployWebsite returns the upload guide (create the site, upload its files, change them later); StartHeadlessBuild returns the headless guide, for a site that needs Wix business features: you write the site, and the guide creates it, connects the features and uploads it, through the cold start that hands off to the kit (or the same run as API calls when there is no shell).
 
-      </management-flow>
+      ### When a call fails
 
-      <other-uses>
-      Beyond managing user sites, the Wix MCP tools can be used for any other purpose they support — for example, reading Wix SDK docs to write code against the SDK, using the Wix CLI to create apps, answering documentation questions, and so on.
-      </other-uses>
-      </agent-mandatory-instructions>
+      The error carries the failed call's status and message and a Wix request id. Read it: it says what was wrong, and that is what to fix before calling again, whether the request (from the schema), the site and what is installed on it, or what the account is allowed to do. Never resend the same request unchanged, and never guess a fix. When you report the failure to the user, include the request id.
 `;
 /**
  * Default readme docs - content for WixREADME tool response.
@@ -1068,19 +1184,29 @@ const README_BODY = dedent `
  * Joined rather than interpolated into one `dedent` — `dedent` reads indentation from the literal
  * parts only, so a multi-line interpolation gets flattened.
  */
-export const defaultReadmeDocs = [
-    {
-        action: 'text',
-        content: [
-            README_INTRO,
-            AGENT_GOAL,
-            README_FLOWS_HEADING,
-            '',
-            README_BODY
-        ].join('\n')
-    },
-    recipesIndexDoc
-];
+export function buildReadmeDocs({ recipesIndex = true } = {}) {
+    return [
+        {
+            action: 'text',
+            content: [
+                README_INTRO,
+                '',
+                AGENT_GOAL,
+                '',
+                README_FLOWS_HEADING,
+                '',
+                README_FLOWS_SITE,
+                '',
+                README_FIND_SOURCES,
+                '',
+                README_FLOWS_BODY
+            ].join('\n')
+        },
+        { action: 'text', content: WIX_SKILLS_README_SECTION },
+        ...(recipesIndex ? [recipesIndexDoc] : [])
+    ];
+}
+export const defaultReadmeDocs = buildReadmeDocs();
 /**
  * Merge base config with overrides
  * @param base - Base configuration
@@ -1127,6 +1253,22 @@ export const defaultConfig = {
     usePlatformizedSearch: true,
     skillsPrOverrideEnabled: true
 };
+let guideOnEveryTool;
+/**
+ * For a session without WixREADME (mode=code, getToKnowWixEnabled off, WixREADME disabled): the
+ * usage guide WixREADME carries goes back onto every tool, as it was before usageGuideOnce.
+ * Custom tool descriptions are kept.
+ */
+export function withUsageGuideOnEveryTool(config) {
+    const every = (guideOnEveryTool ??= buildToolDescriptions(true, true));
+    return {
+        ...config,
+        toolDescriptions: Object.fromEntries(Object.entries(config.toolDescriptions ?? {}).map(([tool, text]) => [
+            tool,
+            text === defaultToolDescriptions[tool] ? (every[tool] ?? text) : text
+        ]))
+    };
+}
 /**
  * Delta for clients that declared the MCP-Apps UI extension. Merged over the mode config at
  * request time, since the mode override and the widget variant have to compose.
@@ -1136,8 +1278,7 @@ export const widgetSiteCreationConfig = {
         'WixSiteBuilder',
         'WixSiteCreation',
         'SearchSiteTemplates',
-        'CreateSiteFromTemplate',
-        'CreateWixBusinessGuide'
+        'CreateSiteFromTemplate'
     ].map((tool) => [tool, toWidget(defaultToolDescriptions[tool])]))
 };
 //# sourceMappingURL=default-config.js.map