@wix/mcp 1.0.92 → 1.0.94

package/build/cjs/toolkit.cjs

@@ -16289,9 +16289,12 @@ var runSemanticSearch = async (toolName, toolParams, maxResults = 20, rerank = f
   );
   return data?.results;
 };
-var runPlatformizedSemanticSearch = async (toolName, searchTerm, maxResults = 20, linesInEachResult) => {
+var runPlatformizedSemanticSearch = async (toolName, searchTerm, maxResults = 20, linesInEachResult, extraDocumentTypes) => {
   const startTime = Date.now();
-  logger.log(`[SemanticSearch/v2] Tool: ${toolName}, Query: "${searchTerm}"`);
+  const documentTypes = extraDocumentTypes?.length ? [toolName, ...extraDocumentTypes] : void 0;
+  logger.log(
+    `[SemanticSearch/v2] Tool: ${documentTypes ? documentTypes.join("+") : toolName}, Query: "${searchTerm}"`
+  );
   const response = await fetch(
     "https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown",
     {
@@ -16302,7 +16305,7 @@ var runPlatformizedSemanticSearch = async (toolName, searchTerm, maxResults = 20
       },
       body: JSON.stringify({
         search_term: searchTerm,
-        document_type: toolName,
+        ...documentTypes ? { document_types: documentTypes } : { document_type: toolName },
         maximum_results: maxResults,
         lines_in_each_result: linesInEachResult
       })
@@ -16331,14 +16334,16 @@ var runSemanticSearchAndFormat = async ({
   maxResults = DEFAULT_MAX_RESULTS,
   rerank,
   linesInEachResult,
-  usePlatformizedSearch = true
+  usePlatformizedSearch = true,
+  extraDocumentTypes
 }) => {
   if (usePlatformizedSearch) {
     return runPlatformizedSemanticSearch(
       toolName,
       toolParams.searchTerm,
       maxResults,
-      linesInEachResult
+      linesInEachResult,
+      extraDocumentTypes
     );
   } else {
     const results = await runSemanticSearch(
@@ -17275,7 +17280,7 @@ async function fetchArticle(articleUrl) {
 }
 var DOCS_URL_PREFIX = "https://dev.wix.com/docs/";
 var SKILLS_REGISTRY_URL = new RegExp(
-  "^https://(?:dev\\.wix\\.com(?:/docs)?|www\\.wix\\.com(?:/velo/reference)?)/skills(?:[/.?#]|$)"
+  "^https://(?:dev\\.wix\\.com(?:/docs)?|www\\.wix\\.com(?:/velo/reference)?)/skills(?:[/.?#]|$)|^https://www\\.wix\\.com/headless/"
 );
 function isSkillsRegistryUrl(url) {
   return SKILLS_REGISTRY_URL.test(url.trim());
@@ -17700,10 +17705,8 @@ function buildSystemReminderGuidelines(includeReadme, includeImageUploadGuidance
   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 \u2014 creating a new Wix site/website:** For a normal creation request \u2014 and only then \u2014 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 \u2014 these don't need the site's purpose first.",
-      "If the user \u2014 or you, earlier in this conversation \u2014 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 \u2014 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."
+      "**Creating a new Wix site \u2014 and only then \u2014 skip WixREADME and the docs.** First settle one thing: will the user keep working on this site with you, in code, or design it themselves in Wix's editor? In code \u2014 you or the user have code, the two of you designed it here, they asked you to build it, they asked for a headless site, or it is an app: StartDeployWebsite if the code exists in any form, StartHeadlessBuild if not, called right away (it only returns the guide; the site's purpose is not needed first). In Wix's editor: the site-creation tools; their descriptions carry the rules. Everything else starts with WixREADME as usual.",
+      "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 site creation through ManageWixSite, CallWixSiteAPI, or ExecuteWixAPI."
     );
   }
   lines.push(
@@ -17751,9 +17754,8 @@ function buildSystemReminder(includeReadme, includeImageUploadGuidance = true) {
   );
   const flows = buildSystemReminderFlows(includeReadme);
   return dedent_default`
-    <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>
@@ -17763,7 +17765,7 @@ function buildSystemReminder(includeReadme, includeImageUploadGuidance = true) {
     <flow-description>
     ${flows}
     </flow-description>
-    </agent-mandatory-instructions>
+    </wix-usage-guide>
   `;
 }
 var SYSTEM_REMINDER = buildSystemReminder(true);
@@ -17775,18 +17777,14 @@ var SITE_CREATION_COPY = {
   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`"
   }
 };
 var SITE_GUIDANCE = dedent_default`
-  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.
+  First decide who keeps building the site:
+  - **You, in code**: a Wix Headless site, with full control of the design, changed and redeployed from this conversation, Wix business features added as a backend. This is the case when you or the user have code (hand-written files, a static build, a zip, another builder's export, a page you made here): call StartDeployWebsite. It is also the case when nothing is coded yet but the user asked you to build it or asked for a headless site, the two of you worked out its design in this conversation, or it is an app (a game, a dashboard, a tool): call StartHeadlessBuild right away, before asking what the site is for. Do not offer AI or templates for either.
+  - **The user, in Wix's editor**: Wix generates it with AI or starts it from a template, and the user designs it in Wix. 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.
+  For a new site in Wix's editor 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.
@@ -17806,6 +17804,7 @@ var toWidget = (text) => Object.values(SITE_CREATION_COPY).reduce(
 );
 var EXECUTE_WIX_API_INTRO = dedent_default`
   Execute JavaScript code against the Wix REST API when code is useful for chaining related calls, pagination, loops, branching, or in-memory transformation.
+  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.
@@ -17883,13 +17882,14 @@ var ACCOUNT_SITE_EXECUTE_SCOPE = dedent_default`
     unzip(input: string | Uint8Array): Promise<Array<{ path: string; bytes: Uint8Array; text(): string }>>;
   };
   declare const siteId: string | undefined;
-  // Files from the ExecuteWixAPI \`files\` param. Text entries have \`content\`;
-  // an entry tagged \`=== FILE: <path> base64 ===\` has encoding:'base64' and
-  // base64 \`content\` (a binary file — image, font).
+  // Files from the ExecuteWixAPI \`files\` param, followed by the resolved
+  // \`attachments\`. Text entries have \`content\`; an entry tagged
+  // \`=== FILE: <path> base64 ===\` — and every attachment, path = its file name —
+  // has encoding:'base64' and base64 \`content\`.
   declare const files: Array<{ path: string; content: string; encoding?: "base64" }>;
   \`\`\`
 
-  FILE UPLOADS: put every file in the \`files\` param (never inline in \`code\`). 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\` works in ChatGPT only: pass files attached in the chat or created in your sandbox (any type, up to 10 MB per call: a zip of a whole site, HTML, images, PDFs) as you have them, by file id or /mnt/data path, all in one call. ChatGPT swaps each for \`{ download_url, file_id, file_name?, mime_type? }\` before the call reaches Wix, and the bytes arrive as base64 entries named by file name. Other clients send the value unchanged and the call fails before running; there, leave \`attachments\` out, or upload from your shell if it reaches the internet. 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 ===
@@ -17904,6 +17904,12 @@ var ACCOUNT_SITE_EXECUTE_SCOPE = dedent_default`
     return res.data;
   }
   \`\`\`
+  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" }]
+  const entries = await wix.unzip(files[0].content); // [{ path, bytes, text() }]
+  const mp = wix.multipart(entries);
+  \`\`\`
   DOWNLOAD + EDIT + RE-UPLOAD: fetch the zip as base64, \`wix.unzip()\` it, edit text via \`entry.text()\`, keep binary as bytes, and hand the entries back to \`wix.multipart()\`:
   \`\`\`javascript
   const r = await wix.request({ scope: "account", method: "GET", responseType: "base64", url: zipUrl });
@@ -18044,7 +18050,7 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
     ReadFullDocsArticle: dedent_default`
     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}
@@ -18092,7 +18098,7 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
     ${reminder}
   `,
     ManageWixSite: dedent_default`
-    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.
@@ -18108,12 +18114,12 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
     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. 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): 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.
     • 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:
-    • NEVER pass a local or sandbox file path (e.g. /mnt/..., /home/user/..., /Users/...) in any field — the server cannot reach your filesystem. Use a public http(s) URL (imageUrls) or the complete base64 (imageBase64).
+    • 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).
     • 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_default`
@@ -18171,14 +18177,15 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
 
     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.
+    Not for a site the user wants you to build in code, a design you worked out together, or an app: call \`StartHeadlessBuild\`.
 
     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.
   `,
     "import-claude-design-from-url": dedent_default`
-    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_default`
     Executes Wix CLI commands for Wix app development and management.
@@ -18615,23 +18622,23 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
     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\`.
+    For templates or Wix Studio, call \`SearchSiteTemplates\` (\`builder: classic\` for the Classic Editor); for a template id, \`CreateSiteFromTemplate\`. A site the user wants you to build in code, or an app: \`StartHeadlessBuild\`.
 
     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.)
   `,
     SearchSiteTemplates: dedent_default`
     ${SITE_GUIDANCE}
 
-    Searches Wix templates and shows the template gallery, from the Harmony or the Studio template source.
+    Searches Wix templates and shows the template gallery, from the Harmony, the Studio or the Classic Editor 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.
+    Call this ONLY when the user's own words ask for a template, for Wix Studio or for the Classic Editor (for example "start from a template", "show me some templates", "build it in Wix Studio", "the old Wix editor") and you can already tell what the site is for. If they mention Wix Studio, search Studio templates; if they ask for the Classic Editor (the Wix Editor), search \`classic\`; 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}.`,
     CreateSiteFromTemplate: dedent_default`
     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_default`
@@ -18659,34 +18666,24 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
     Compose: put independent reads in one document as several root fields, and use related-entity fields (e.g. \`inventoryItems\`, \`collections\`, \`fulfillments\`) instead of extra round-trips. Select only the fields you need; every object field needs a selection set. Variables: use them for \`JSON\` scalars (filter, sort) and plain scalars (String, Int, ID), declared in the document (e.g. \`query Q($f: JSON) { ... filter: $f ... }\`). Write mutation inputs and any object that contains an enum INLINE as GraphQL literals with enum values unquoted (e.g. \`input: { product: { name: "Mug", productType: PHYSICAL } }\`) — this endpoint fails with 503 when an enum value arrives inside an object-typed variable. For lists page with \`cursorPaging\` or \`paging\` exactly as the input type declares (never the other one), and request \`pageInfo { hasNext total }\`; \`total\` is only populated with offset \`paging\`, so for a cursor-paged list count by walking pages or use a count operation.
     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_default`
+    The upload step of the StartDeployWebsite and StartHeadlessBuild guides, and nothing else: puts a finished static website's files — index.html plus its CSS/JS/images, a static build, or a zip of the site — 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 ChatGPT as \`attachments\` (any type, a zip is unpacked), elsewhere as the \`files\` text bundle (\`=== FILE: <path> ===\` sections, \`base64\` tag for small binaries). The site must contain index.html at its root.
+    NOT a site-creation tool: a request to create, build, design or generate a site — with or without a description — never comes here (those are the site-creation tools, after their own questions). Also NOT for media uploads to an existing site (UploadImageToWixSite) or any other API call (ExecuteWixAPI).
   `,
     StartDeployWebsite: dedent_default`
-    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.
+    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, put online, make it live, get a URL, upload my site / index.html, or wants to update or redeploy the files of a site you or the user deployed as code.
     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).
+    Returns the full recipe; follow it and run the flow yourself. When the UploadHeadlessWebsiteFiles tool is available, use it for the recipe's upload step — after the site exists (the recipe's provision call, or a metaSiteId from an earlier deploy) — instead of building the multipart body in code; never before this tool. The drop page is only the fallback when you can't.
+    NOT for: a screenshot or reference of a site the user wants Wix to generate (the site-creation tools); a site described in words with no code yet (StartHeadlessBuild); a Wix editor site's content or settings (WixSiteBuilder's edit mode, or WixREADME); 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 site; uploading images or documents to a site's media (UploadImageToWixSite).
   `,
-    CreateWixBusinessGuide: dedent_default`
-    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)`
+    StartHeadlessBuild: dedent_default`
+    The user wants a site or web app that you build and keep changing in code, here with them, and no code exists yet. Wix runs its business side (store, bookings, CMS, forms, members, payments) as a Wix Headless site. Call this when the user asks you to build it yourself rather than Wix's AI or a template; when the two of you worked out a design in this conversation and nothing is coded yet; when it is an app (a game, a dashboard, a tool); when the user asks for a headless site; when a prompt links \`wix.com/headless/skill.md\` or a project's \`download.zip\`; or to move a Wix site to code.
+    Call it right away: it only returns the guide, and the site's purpose is not needed first (pass "not stated yet" for what you don't know). Returns the full guide; follow it and do the work yourself, choosing its route by what you can reach (a shell that reaches Wix, or this MCP alone).
+    NOT for: files, a build, a zip or a page that already exist (StartDeployWebsite); a site the user will design in Wix's editor (the site-creation tools); a Claude Design URL (import-claude-design-from-url).
+  `
   };
 }
 var defaultToolDescriptions = buildToolDescriptions(true);
@@ -18698,9 +18695,9 @@ var recipesIndexDoc = {
   action: "include"
 };
 var README_INTRO = dedent_default`
-  <agent-mandatory-instructions>
+  <wix-usage-guide>
 
-  YOU MUST READ AND FOLLOW THE AGENT-MANDATORY-INSTRUCTIONS BELOW:
+  How to work with Wix through these tools:
 
   <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.
@@ -18752,7 +18749,7 @@ var README_BODY = dedent_default`
       <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>
+      </wix-usage-guide>
 `;
 var defaultReadmeDocs = [
   {
@@ -18808,8 +18805,7 @@ var widgetSiteCreationConfig = {
       "WixSiteBuilder",
       "WixSiteCreation",
       "SearchSiteTemplates",
-      "CreateSiteFromTemplate",
-      "CreateWixBusinessGuide"
+      "CreateSiteFromTemplate"
     ].map((tool) => [tool, toWidget(defaultToolDescriptions[tool])])
   )
 };
@@ -19365,7 +19361,7 @@ var paramDescriptions = {
   },
   SearchWixRESTDocumentation: {
     searchTerm: `The search term to look up in the Wix REST API Documentation \u2014 a natural-language description of the endpoint, resource, or action you need across any Wix domain (Stores, eCommerce, Bookings, CRM, Members, CMS, Events, Blog, Forms, Media, site settings, etc.), e.g. "create a catalog item with inventory", "book a service", "update data collection items". Match the wording to how many entities you will act on: a plural term ("update products") surfaces the resource's bulk methods, which a singular term ("update a product") ranks lower or leaves out. Results are ranked by relevance, so describe the goal rather than guessing an exact API name.`,
-    maxResults: "The maximum number of results to return, default is 10, max is 15",
+    maxResults: "The maximum number of results to return (1\u201317, default 17). Results mix REST API documentation with matching recipes and skills.",
     reason: "One sentence describing the original user request and the task you are trying to accomplish with this search."
   },
   WixBusinessFlowsDocumentation: {
@@ -19386,7 +19382,7 @@ var paramDescriptions = {
   },
   SearchWixHeadlessDocumentation: {
     searchTerm: "The search term to search for in the Headless Documentation",
-    maxResults: "The maximum number of results to return, default is 10, max is 15"
+    maxResults: "The maximum number of results to return (1\u201317, default 17). Results mix Headless documentation with matching recipes and skills."
   },
   SearchWixVeloDocumentation: {
     searchTerm: "The search term to search for in the Velo Documentation",
@@ -19398,7 +19394,7 @@ var paramDescriptions = {
     reason: "One sentence describing the original user request and the task you are trying to accomplish with this search."
   },
   ReadFullDocsArticle: {
-    articleUrl: "The URL of the docs article or method article to fetch. Should be something like https://dev.wix.com/docs/.../... For REST docs, use the URL as-is. For SDK docs, the URL SHOULD include the query param ?apiView=SDK (e.g. https://dev.wix.com/docs/...?apiView=SDK). Wix skills pages (https://www.wix.com/skills/..., https://dev.wix.com/docs/skills/...) are read as-is, including their referenced files."
+    articleUrl: "The URL of the docs article or method article to fetch. Should be something like https://dev.wix.com/docs/.../... For REST docs, use the URL as-is. For SDK docs, the URL SHOULD include the query param ?apiView=SDK (e.g. https://dev.wix.com/docs/...?apiView=SDK). Wix skills pages (https://www.wix.com/skills/..., https://dev.wix.com/docs/skills/...) and Wix Headless agent pages (https://www.wix.com/headless/..., e.g. https://www.wix.com/headless/skill.md) are read as-is, including their referenced files."
   },
   ReadFullDocsMethodSchema: {
     articleUrl: "The URL of the documentation to fetch. Should be something like https://dev.wix.com/docs/.../... For REST docs, use the URL as-is. For SDK docs, the URL SHOULD include the query param ?apiView=SDK (e.g. https://dev.wix.com/docs/...?apiView=SDK).",
@@ -19414,7 +19410,7 @@ var paramDescriptions = {
   },
   UploadImageToWixSite: {
     siteId: "The ID (UUID) of the Wix site to upload to. REQUIRED. If the user has not clearly specified which site, ASK them which site to upload to (or use ListWixSites to help them pick) BEFORE calling this tool. NEVER call this tool with a missing, empty, placeholder, or guessed siteId \u2014 ask first instead.",
-    image: "Array of file ATTACHMENTS the user uploaded in the chat. Each item requires download_url and file_id, and may optionally include file_name and mime_type \u2014 attached files are automatically resolved to these fields by the platform, so just include them here. For plain image URLs the user pasted, use imageUrls instead. ALWAYS pass ALL attachments together in a single call \u2014 NEVER call this tool once per image. Do NOT use together with imageBase64.",
+    image: "Array of file ATTACHMENTS: files the user uploaded in the chat, or files you created in your own file sandbox. Each item requires download_url and file_id, and may optionally include file_name and mime_type \u2014 the platform resolves a file passed here into these fields automatically, so just include the files. For plain image URLs the user pasted, use imageUrls instead. ALWAYS pass ALL attachments together in a single call \u2014 NEVER call this tool once per image. Do NOT use together with imageBase64.",
     imageUrls: "Array of publicly accessible image URLs (e.g. links the user pasted or URLs produced by other tools). Use this for plain URLs that are NOT chat attachments \u2014 no file_id is needed. ALWAYS pass ALL URLs together in a single call. Can be combined with image; do NOT use together with imageBase64.",
     imageBase64: 'Base64-encoded image data. Use when the client can read a file and encode it as base64. May include a data URL prefix (e.g. "data:image/jpeg;base64,...") or be raw base64. Do NOT use together with image.',
     mimeType: 'MIME type of the image (e.g. "image/jpeg", "image/png", "image/webp"). Required when imageBase64 does not include a data URL prefix.',
@@ -19438,7 +19434,7 @@ var paramDescriptions = {
     operationName: "Operation to run when the document defines more than one named operation.",
     siteId: "The Wix site to run against. Required for site-level operations (anything reading or writing inside a site \u2014 products, orders, contacts, bookings, CMS, blog, members ...). Resolve it with GetSiteContext or ListWixSites; never pass a guessed value.",
     scope: '"site" (default when siteId is given) runs with a site-scoped credential; "account" runs account-level operations (sites, account settings) and ignores siteId.',
-    hasMutations: "Whether this document creates, updates, deletes or otherwise mutates Wix data. True for any mutation root field (in any operation of the document) even when the intent is inspection; false only for pure queries. This flag alone decides whether a transient server error may be retried, so never mark a document that writes as false.",
+    hasMutations: "True if the document contains a mutation root field in any of its operations; false if it contains only queries. A transient server error is retried only when this is false.",
     reason: "One sentence explaining the original user request and why you are running this GraphQL operation to complete it."
   },
   RunWixCliCommand: {
@@ -19702,121 +19698,6 @@ ${skillsContent}`
   );
 }
 
-// src/docs/create-site-guide.ts
-function isHeadlessRequest(prompt) {
-  return !!prompt && /headless/i.test(prompt);
-}
-var HEADLESS_NON_CLI_INSTRUCTIONS = `# Creating a Wix Headless Site
-
-Wix Headless sites require the **Wix CLI** and cannot be created from the Wix dashboard or via REST API alone. Let the user know they need to set up a local development environment with the Wix CLI before proceeding.
-
-## Prerequisites
-- Node.js 18+
-- A terminal / command-line environment
-
-## Steps to Get Started
-
-1. **Install and authenticate the Wix CLI:**
-   \`\`\`
-   npx @wix/cli login
-   \`\`\`
-2. **Follow the quick-start guide:** https://dev.wix.com/docs/go-headless
-3. **For a complete orchestrated setup** (commerce, CMS, bookings, identity), use the Wix Headless skill: https://www.wix-headless.dev/skill.md`;
-var HEADLESS_CLI_INSTRUCTIONS = `# Creating a Wix Headless Site (CLI Flow)
-
-Follow these steps using the \`RunWixCliCommand\` tool to scaffold and configure a Wix Headless site.
-
-## Before You Start
-Ask the user:
-1. What is the brand/site name?
-2. Which local directory should the project be created in?
-
-## Steps
-
-### Step 1 \u2014 Authenticate (if not already done)
-Run: \`npx @wix/cli login\`
-Skip if the user is already authenticated.
-
-### Step 2 \u2014 Scaffold the project
-Use a Wix headless starter template. Ask the user which starter they prefer, or use the default Next.js starter. Follow the scaffolding instructions at: https://dev.wix.com/docs/go-headless
-
-### Step 3 \u2014 Install dependencies
-Run: \`npm install\` in the project directory.
-
-### Step 4 \u2014 Pull environment variables
-Run: \`npx @wix/cli env pull\`
-This writes the \`.env.local\` file with the site's environment variables.
-
-### Step 5 \u2014 Build and verify
-Run: \`npx @wix/cli build\`
-
-### Step 6 \u2014 Release (optional)
-Run: \`npx @wix/cli release\` to deploy.
-
-## Full Orchestration
-For a complete multi-wave headless setup (commerce, CMS, bookings, design system, content seeding), refer to the Wix Headless skill: https://www.wix-headless.dev/skill.md
-
-Use \`RunWixCliCommand\` for each CLI step above.`;
-var CREATE_SITE_DOCS = [
-  {
-    url: "https://dev.wix.com/docs/kb-only/MCP_REST_RECIPES_KB_ID/TRAIN_create_a_new_site_from_template",
-    title: "How to Create a New Wix Site",
-    nextSteps: "\n\n**Next Steps:** Use the ManageWixSite tool to make the API call for creating the Wix site."
-  },
-  {
-    url: "https://dev.wix.com/docs/kb-only/MCP_REST_RECIPES_KB_ID/TRAIN_wix.devcenter.apps.installer.v1.AppsInstallerService.InstallApp",
-    title: "How to Install App on a Wix Site",
-    nextSteps: "\n\n**Next Steps:** Use the CallWixSiteAPI tool to make the API call for installing apps on the Wix site."
-  }
-];
-async function addCreateWixBusinessGuideTools(server, disableTools = [], toolDescriptions, cliEnabled = false) {
-  if (disableTools.includes("CreateWixBusinessGuide")) {
-    return;
-  }
-  server.tool(
-    "CreateWixBusinessGuide",
-    toolDescriptions?.["CreateWixBusinessGuide"] ?? defaultToolDescriptions.CreateWixBusinessGuide,
-    {
-      userPrompt: external_exports.string().optional().describe("The user prompt that triggered this tool")
-    },
-    { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
-    async (args, { httpClient }) => {
-      if (isHeadlessRequest(args.userPrompt)) {
-        const isCli = typeof cliEnabled === "function" ? cliEnabled() : cliEnabled;
-        const text = isCli ? HEADLESS_CLI_INSTRUCTIONS : HEADLESS_NON_CLI_INSTRUCTIONS;
-        return { content: [{ type: "text", text }] };
-      }
-      try {
-        const contents = await Promise.all(
-          CREATE_SITE_DOCS.map(async ({ url, title, nextSteps }) => {
-            const articleContent = await fetchArticleContent(
-              httpClient,
-              url,
-              "article",
-              true
-            );
-            const fullContent = `# ${title}
-
-${articleContent}${nextSteps}`;
-            return { type: "text", text: fullContent };
-          })
-        );
-        return { content: contents };
-      } catch (error) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text",
-              text: `Error fetching create site documentation: ${error.message}`
-            }
-          ]
-        };
-      }
-    }
-  );
-}
-
 // src/docs/start-deploy-website.ts
 var START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS = {
   userRequest: "The user's request that led here, quoted if short, otherwise summarized in a sentence.",
@@ -19888,6 +19769,87 @@ function addStartDeployWebsiteTool(server, disableTools = [], toolDescriptions,
   );
 }
 
+// src/docs/start-headless-build.ts
+var START_HEADLESS_BUILD_TOOL_NAME = "StartHeadlessBuild";
+var HEADLESS_GUIDE_URL = "https://www.wix.com/skills/headless-cold-start/headless-kit.md";
+var START_HEADLESS_BUILD_STARTING_POINTS = [
+  "nothing yet",
+  "a design worked out in this conversation",
+  "an existing Wix Headless site",
+  "a project download link",
+  "a Wix site to move to code"
+];
+var START_HEADLESS_BUILD_PARAM_DESCRIPTIONS = {
+  userRequest: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.userRequest,
+  siteDescription: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.siteDescription,
+  startingPoint: "What the build starts from: nothing yet; a design worked out in this conversation; an existing Wix Headless site; a project download link (a download.zip from Wix); or a Wix site to move to code.",
+  siteFunctionality: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.siteFunctionality,
+  agentIdentity: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.agentIdentity,
+  wixAccess: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.wixAccess
+};
+var PREFIX2 = "The following is Wix's headless guide. Follow it end to end and do the work yourself. If you find the user already has the site's code, call StartDeployWebsite instead.";
+var MOVE_TO_CODE_LINE = `Moving a Wix site to code starts from the site's dashboard (Headless settings, "Go Headless"), which hands the owner a prompt with the project's download link. Ask the user for that prompt, then follow the guide with it.`;
+function startHeadlessBuildResponse(guide, startingPoint) {
+  const lines = [];
+  if (startingPoint === "a Wix site to move to code") {
+    lines.push(MOVE_TO_CODE_LINE);
+  }
+  if (guide && guide.trim()) {
+    lines.push(PREFIX2, "---", guide.trim());
+  } else {
+    lines.push(
+      `Wix's headless guide could not be loaded here. It is at ${HEADLESS_GUIDE_URL}: read it whole with ReadFullDocsArticle if you have that tool, otherwise fetch it with curl or your web tool, then follow it end to end and do the work yourself. If you find the user already has the site's code, call StartDeployWebsite instead.`
+    );
+  }
+  return lines.join("\n\n");
+}
+function addStartHeadlessBuildTool(server, disableTools = [], toolDescriptions, fetchOptions = {}) {
+  if (disableTools.includes(START_HEADLESS_BUILD_TOOL_NAME)) {
+    return;
+  }
+  const d = START_HEADLESS_BUILD_PARAM_DESCRIPTIONS;
+  server.tool(
+    START_HEADLESS_BUILD_TOOL_NAME,
+    toolDescriptions?.[START_HEADLESS_BUILD_TOOL_NAME] ?? defaultToolDescriptions[START_HEADLESS_BUILD_TOOL_NAME],
+    {
+      userRequest: external_exports.string().min(1).describe(d.userRequest),
+      siteDescription: external_exports.string().min(1).describe(d.siteDescription),
+      startingPoint: external_exports.enum(START_HEADLESS_BUILD_STARTING_POINTS).describe(d.startingPoint),
+      siteFunctionality: external_exports.string().min(1).describe(d.siteFunctionality),
+      agentIdentity: external_exports.string().min(1).describe(d.agentIdentity),
+      wixAccess: external_exports.string().min(1).describe(d.wixAccess)
+    },
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    async (args, { httpClient }) => {
+      let guide;
+      try {
+        guide = await fetchArticleContent(
+          httpClient,
+          HEADLESS_GUIDE_URL,
+          "article",
+          true,
+          fetchOptions.skillsPortalUrl,
+          fetchOptions.repo,
+          fetchOptions.commitHash
+        );
+      } catch (error) {
+        console.warn(
+          "[StartHeadlessBuild] guide fetch failed, returning the pointer:",
+          error instanceof Error ? error.message : error
+        );
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: startHeadlessBuildResponse(guide, args.startingPoint)
+          }
+        ]
+      };
+    }
+  );
+}
+
 // src/docs/docs.ts
 var REST_SEARCH_API_GROUNDING_REMINDER = dedent_default`
   # Before calling a Wix API
@@ -19935,8 +19897,8 @@ var addDocsTools = (server, allowedTools = [
 ], options = {}) => {
   const {
     getToKnowWixEnabled = false,
-    createWixBusinessGuideEnabled = true,
     startDeployWebsiteEnabled = true,
+    startHeadlessBuildEnabled = true,
     disableTools,
     toolDescriptions,
     readmeDocs,
@@ -19948,7 +19910,6 @@ var addDocsTools = (server, allowedTools = [
     commitHash,
     skillsTags,
     dynamicContextEnabled,
-    cliEnabled = false,
     usePlatformizedSearch = true,
     usePlatformizedBrowse = true
   } = options;
@@ -19994,14 +19955,6 @@ var addDocsTools = (server, allowedTools = [
       skillsTags
     });
   }
-  if (createWixBusinessGuideEnabled && !disableTools?.includes("CreateWixBusinessGuide")) {
-    addCreateWixBusinessGuideTools(
-      server,
-      disableTools || [],
-      toolDescriptions,
-      cliEnabled
-    );
-  }
   if (startDeployWebsiteEnabled) {
     addStartDeployWebsiteTool(server, disableTools || [], toolDescriptions, {
       skillsPortalUrl,
@@ -20009,6 +19962,13 @@ var addDocsTools = (server, allowedTools = [
       commitHash: effectiveCommitHash
     });
   }
+  if (startHeadlessBuildEnabled) {
+    addStartHeadlessBuildTool(server, disableTools || [], toolDescriptions, {
+      skillsPortalUrl,
+      repo: effectiveRepo,
+      commitHash: effectiveCommitHash
+    });
+  }
   if (allowedTools.includes("WDS") && !disableTools?.includes("SearchWixWDSDocumentation")) {
     server.tool(
       "SearchWixWDSDocumentation",
@@ -20073,7 +20033,7 @@ var addDocsTools = (server, allowedTools = [
         const d = desc("SearchWixRESTDocumentation");
         return {
           searchTerm: external_exports.string().describe(d.searchTerm),
-          maxResults: external_exports.number().describe(d.maxResults).min(1).max(15).optional().default(15),
+          maxResults: external_exports.number().describe(d.maxResults).min(1).max(17).optional().default(17),
           reason: external_exports.string().describe(d.reason)
         };
       })(),
@@ -20088,9 +20048,12 @@ var addDocsTools = (server, allowedTools = [
             toolParams: {
               searchTerm
             },
-            maxResults: Math.max(1, Math.min(maxResults ?? 15, 15)),
+            maxResults: Math.max(1, Math.min(maxResults ?? 17, 17)),
             linesInEachResult: 30,
-            usePlatformizedSearch
+            usePlatformizedSearch,
+            // Merge recipes/skills into the REST ranking — they live in a
+            // separate corpus the REST document_type doesn't cover on its own.
+            extraDocumentTypes: ["SKILLS"]
           });
           const grounding = result.includes(QUERY_CAPABILITY_MARKER) ? [
             REST_SEARCH_API_GROUNDING_REMINDER,
@@ -20353,7 +20316,7 @@ var addDocsTools = (server, allowedTools = [
         const d = desc("SearchWixHeadlessDocumentation");
         return {
           searchTerm: external_exports.string().describe(d.searchTerm),
-          maxResults: external_exports.number().describe(d.maxResults).min(1).max(15).optional().default(15)
+          maxResults: external_exports.number().describe(d.maxResults).min(1).max(17).optional().default(17)
         };
       })(),
       { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
@@ -20365,8 +20328,11 @@ var addDocsTools = (server, allowedTools = [
             toolParams: {
               searchTerm
             },
-            maxResults: Math.max(1, Math.min(maxResults ?? 15, 15)),
-            usePlatformizedSearch
+            maxResults: Math.max(1, Math.min(maxResults ?? 17, 17)),
+            usePlatformizedSearch,
+            // Merge recipes/skills into the headless ranking — same separate
+            // corpus the WIX_HEADLESS document_type doesn't cover on its own.
+            extraDocumentTypes: ["SKILLS"]
           });
           return {
             content: [
@@ -20532,7 +20498,7 @@ var addDocsTools = (server, allowedTools = [
             content: [
               {
                 type: "text",
-                text: `Invalid article URL: must start with https://dev.wix.com/docs/, or be a Wix skills page (https://www.wix.com/skills/...). Got: "${articleUrl}"`
+                text: `Invalid article URL: must start with https://dev.wix.com/docs/, or be a Wix skills page (https://www.wix.com/skills/..., https://www.wix.com/headless/...). Got: "${articleUrl}"`
               }
             ]
           };
@@ -21257,10 +21223,12 @@ function addApiCallTool(server, strategy, allowedTools = ["CallWixSiteAPI", "Lis
           sourceDocUrl: external_exports.string().describe(d.sourceDocUrl)
         };
       })(),
+      // openWorldHint true: a free-form URL into the whole Wix REST surface is an
+      // open-ended target, even though auth is bounded to the user's account.
       getHints("CallWixSiteAPI", {
         readOnlyHint: false,
         destructiveHint: true,
-        openWorldHint: false
+        openWorldHint: true
       }),
       async ({ url, body, method, siteId, reason, sourceDocUrl }, { httpClient, setToolBiParams }) => {
         logger.log(
@@ -21437,7 +21405,7 @@ function addApiCallTool(server, strategy, allowedTools = ["CallWixSiteAPI", "Lis
       getHints("ManageWixSite", {
         readOnlyHint: false,
         destructiveHint: true,
-        openWorldHint: false
+        openWorldHint: true
       }),
       async ({ url, body, method, reason }, { httpClient, setToolBiParams }) => {
         logger.log(
@@ -22193,7 +22161,8 @@ function addExecuteGraphqlTool(server, description, authStrategy, options) {
       hasMutations: external_exports.boolean().describe(d.hasMutations),
       reason: external_exports.string().describe(d.reason)
     },
-    { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    // openWorldHint true: any operation in the Wix GraphQL schema, chosen at call time.
+    { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     async ({ query, variables, operationName, siteId, scope, hasMutations, reason }, extra) => {
       const effectiveScope = scope ?? (siteId ? "site" : "account");
       logger.log(
@@ -22286,6 +22255,189 @@ ${text.slice(0, 2e3)}`
   );
 }
 
+// src/code-mode/attachments.ts
+var MAX_ATTACHMENTS_BYTES = 10 * 1024 * 1024;
+var MAX_REDIRECTS = 4;
+var OAI_USERCONTENT_HOST = /^[a-z0-9-]+\.oaiusercontent\.com$/;
+var OAI_BLOB_ACCOUNTS = new Set(
+  [
+    "australiaeast",
+    "brazilsouth",
+    "cacentral",
+    "centralindia",
+    "centralus",
+    "centralusdr",
+    "denmarkeast",
+    "eastus",
+    "eastus2",
+    "indiasocentral",
+    "italynorth",
+    "japaneast",
+    "koreacentral",
+    "northcentralus",
+    "northeu",
+    "nznorth",
+    "polandcentral",
+    "seasia",
+    "southcentralus",
+    "southeastus3",
+    "ukwest",
+    "westcentralus",
+    "westus",
+    "westus2",
+    "westus3"
+  ].map((region) => `oaisdmntpr${region}.blob.core.windows.net`)
+);
+function isAllowedAttachmentHost(hostname) {
+  const h = hostname.toLowerCase();
+  return OAI_USERCONTENT_HOST.test(h) || OAI_BLOB_ACCOUNTS.has(h);
+}
+function checkAttachmentUrl(url) {
+  if (url.protocol !== "https:") return "is not an https URL";
+  if (url.port) return "uses a non-default port";
+  if (!isAllowedAttachmentHost(url.hostname)) {
+    return `host "${url.hostname}" is not a ChatGPT file host`;
+  }
+  return void 0;
+}
+var AttachmentError = class extends Error {
+};
+function attachmentPath(a, url) {
+  let fromUrl = "";
+  try {
+    fromUrl = decodeURIComponent(
+      url.pathname.split("/").filter(Boolean).pop() ?? ""
+    );
+  } catch {
+    fromUrl = "";
+  }
+  const raw = (a.file_name?.trim() || fromUrl || a.file_id).replace(/\\/g, "/");
+  const segments = raw.split("/").filter((s) => s && s !== "." && s !== "..");
+  return segments.join("/") || a.file_id;
+}
+function toBase64(bytes) {
+  let binary = "";
+  const chunk = 32768;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+async function fetchAllowed(start, fetchImpl, label) {
+  let url = start;
+  for (let hop = 0; ; hop++) {
+    const res = await fetchImpl(url.toString(), { redirect: "manual" });
+    const location = res.headers.get("location");
+    const isRedirect = res.status >= 300 && res.status < 400 && location;
+    if (!isRedirect) return res;
+    await res.body?.cancel().catch(() => void 0);
+    if (hop >= MAX_REDIRECTS) {
+      throw new AttachmentError(`${label}: too many redirects.`);
+    }
+    let next;
+    try {
+      next = new URL(location, url);
+    } catch {
+      throw new AttachmentError(`${label}: redirect to an invalid URL.`);
+    }
+    const problem = checkAttachmentUrl(next);
+    if (problem) {
+      throw new AttachmentError(
+        `${label}: the download redirected to a URL that ${problem}; refused.`
+      );
+    }
+    url = next;
+  }
+}
+async function readWithin(res, budget, overBudget) {
+  const declared = Number(res.headers.get("content-length") ?? 0);
+  if (declared > budget) throw overBudget();
+  if (!res.body) {
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (bytes.byteLength > budget) throw overBudget();
+    return bytes;
+  }
+  const reader = res.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > budget) {
+      await reader.cancel().catch(() => void 0);
+      throw overBudget();
+    }
+    chunks.push(value);
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+async function resolveAttachments(attachments, fetchImpl = fetch) {
+  if (!Array.isArray(attachments) || attachments.length === 0) return [];
+  const items = [];
+  attachments.forEach((raw, i) => {
+    const a = typeof raw === "object" && raw;
+    const downloadUrl = a && typeof a.download_url === "string" ? a.download_url : "";
+    let url;
+    try {
+      url = /^https?:\/\//i.test(downloadUrl) ? new URL(downloadUrl) : void 0;
+    } catch {
+      url = void 0;
+    }
+    if (!a || !url) {
+      throw new AttachmentError(
+        `attachments[${i}] was not resolved to a download URL (got ${JSON.stringify(
+          typeof raw === "string" ? raw : (a && a.download_url) ?? raw
+        )}). \`attachments\` works only in ChatGPT, which swaps each file for a download URL before the call reaches Wix. Here it arrived as written, and Wix cannot read a path on your machine, so retrying the same value fails the same way. Upload another way. With a shell that reaches the internet, send the file from there (for a site, the StartDeployWebsite recipe's curl drop). Otherwise leave \`attachments\` out and put the files in \`files\`: text as is, and a binary as a \`=== FILE: <path> base64 ===\` entry only when it is a few KB (an icon, a logo), since a larger base64 payload does not survive your own output. A larger image goes in by public URL or through the user (the Media Manager).`
+      );
+    }
+    const problem = checkAttachmentUrl(url);
+    if (problem) {
+      throw new AttachmentError(
+        `attachments[${i}].download_url ${problem}. Only platform-resolved attachments are accepted here; for any other URL fetch it in \`code\` via wix.request or put the bytes in the \`files\` bundle.`
+      );
+    }
+    items.push({ a, url });
+  });
+  let remaining = MAX_ATTACHMENTS_BYTES;
+  const out = [];
+  for (const [i, { a, url }] of items.entries()) {
+    const path = attachmentPath(a, url);
+    const label = `attachments[${i}] (${path})`;
+    let res;
+    try {
+      res = await fetchAllowed(url, fetchImpl, label);
+    } catch (e) {
+      if (e instanceof AttachmentError) throw e;
+      throw new AttachmentError(
+        `${label}: download failed (${e.message}).`
+      );
+    }
+    if (!res.ok) {
+      await res.body?.cancel().catch(() => void 0);
+      throw new AttachmentError(
+        `${label}: download returned HTTP ${res.status}. The download_url may have expired; attach the file again.`
+      );
+    }
+    const bytes = await readWithin(
+      res,
+      remaining,
+      () => new AttachmentError(
+        `${label} pushes the attachments past ${MAX_ATTACHMENTS_BYTES} bytes in total for this call; split the upload across calls.`
+      )
+    );
+    remaining -= bytes.byteLength;
+    out.push({ path, content: toBase64(bytes), encoding: "base64" });
+  }
+  return out;
+}
+
 // src/code-mode/validation.ts
 var EXECUTE_FUNCTION_EXPRESSION_HINT = 'ExecuteWixAPI code must be a function expression, not a script body. Pass code like: async () => { const response = await wix.request({ scope: "site", method: "GET", url: "https://www.wixapis.com/..." }); return response.data; }. Do not write top-level const/await/return outside the function and do not invoke the function yourself.';
 function validateExecuteCode(code) {
@@ -22300,6 +22452,327 @@ function validateExecuteCode(code) {
   return { isValid: true };
 }
 
+// src/api-call/site-files.ts
+var MAX_FILES_BUNDLE_CHARS = 4e6;
+var MAX_UNZIP_BYTES = 64 * 1024 * 1024;
+var MAX_SITE_FILES = 2e3;
+var textEncoder = new TextEncoder();
+function base64ToBytes(b64) {
+  const clean = b64.replace(/^data:[^,]*,/, "").replace(/\s+/g, "");
+  return Uint8Array.from(atob(clean), (c) => c.charCodeAt(0));
+}
+function parseFileBundle(bundle) {
+  if (!bundle || !bundle.trim()) return [];
+  if (bundle.length > MAX_FILES_BUNDLE_CHARS) {
+    throw new Error(
+      `files bundle is too large (${bundle.length} chars; max ${MAX_FILES_BUNDLE_CHARS}). Keep it to text and small base64 assets; pass larger files through attachments or reference media by URL.`
+    );
+  }
+  const delimiter = /^=== FILE: (.+?)(?: (base64))? ===[ \t]*$/gm;
+  const matches = [...bundle.matchAll(delimiter)];
+  if (matches.length === 0) {
+    throw new Error(
+      "files bundle has no `=== FILE: <path> ===` sections. Start each file with that line (add ` base64` before the closing === for binary content)."
+    );
+  }
+  return matches.map((match, i) => {
+    const path = match[1].trim();
+    const start = (match.index ?? 0) + match[0].length;
+    const end = i + 1 < matches.length ? matches[i + 1].index ?? bundle.length : bundle.length;
+    const content = bundle.slice(start, end).replace(/^\r?\n/, "").replace(/\r?\n$/, "");
+    return {
+      path,
+      bytes: match[2] === "base64" ? base64ToBytes(content) : textEncoder.encode(content)
+    };
+  });
+}
+async function unzip(z) {
+  const u16 = (o) => z[o] | z[o + 1] << 8;
+  const u32 = (o) => (u16(o) | u16(o + 2) << 16) >>> 0;
+  let end = z.length - 22;
+  while (end >= 0 && !(u32(end) === 101010256 && end + 22 + u16(end + 20) === z.length))
+    end--;
+  if (end < 0) throw new Error("not a zip file (no end-of-central-directory)");
+  const out = [];
+  let p = u32(end + 16);
+  let total = 0;
+  const decoder = new TextDecoder();
+  for (let i = 0, n = u16(end + 10); i < n; i++) {
+    const path = decoder.decode(z.slice(p + 46, p + 46 + u16(p + 28)));
+    const method = u16(p + 10);
+    const size = u32(p + 24);
+    total += size;
+    if (total > MAX_UNZIP_BYTES) {
+      throw new Error(
+        `zip expands past ${MAX_UNZIP_BYTES} bytes; a static site is at most 20 MB`
+      );
+    }
+    const at = u32(p + 42);
+    const start = at + 30 + u16(at + 26) + u16(at + 28);
+    const comp = z.slice(start, start + u32(p + 20));
+    p += 46 + u16(p + 28) + u16(p + 30) + u16(p + 32);
+    if (path.endsWith("/")) continue;
+    let bytes;
+    if (method === 0) bytes = comp;
+    else if (method === 8) {
+      bytes = new Uint8Array(
+        await new Response(
+          new Blob([comp]).stream().pipeThrough(new DecompressionStream("deflate-raw"))
+        ).arrayBuffer()
+      );
+    } else
+      throw new Error(
+        `zip entry '${path}' uses unsupported compression method ${method}`
+      );
+    if (bytes.length !== size) {
+      throw new Error(
+        `zip entry '${path}' declares ${size} bytes but holds ${bytes.length}`
+      );
+    }
+    out.push({ path, bytes });
+  }
+  return out;
+}
+var isZip = (f) => f.bytes.length >= 4 && f.bytes[0] === 80 && f.bytes[1] === 75 && (f.bytes[2] === 3 && f.bytes[3] === 4 || f.bytes[2] === 5 && f.bytes[3] === 6) || /\.zip$/i.test(f.path);
+var isRootIndex = (p) => /^index\.html?$/i.test(p);
+async function normalizeSiteFiles(input) {
+  let list = [];
+  for (const f of input) {
+    if (isZip(f)) list.push(...await unzip(f.bytes));
+    else list.push(f);
+  }
+  list = list.map((f) => ({
+    ...f,
+    path: f.path.replace(/\\/g, "/").replace(/^\.?\//, "")
+  })).filter(
+    (f) => f.path && !f.path.startsWith("__MACOSX/") && !/(^|\/)\.DS_Store$/.test(f.path) && !f.path.split("/").includes("..")
+  );
+  if (list.length === 0) {
+    throw new Error(
+      "No files to upload: pass the site in `files` or `attachments`."
+    );
+  }
+  if (list.length > MAX_SITE_FILES) {
+    throw new Error(
+      `Too many files (${list.length}); a site upload is at most ${MAX_SITE_FILES}.`
+    );
+  }
+  if (!list.some((f) => isRootIndex(f.path))) {
+    const first = list[0].path.split("/")[0];
+    if (list.every((f) => f.path.includes("/") && f.path.split("/")[0] === first)) {
+      list = list.map((f) => ({
+        ...f,
+        path: f.path.split("/").slice(1).join("/")
+      }));
+    }
+  }
+  const rootHtml = list.filter(
+    (f) => !f.path.includes("/") && /\.html?$/i.test(f.path)
+  );
+  if (!list.some((f) => isRootIndex(f.path)) && rootHtml.length === 1) {
+    list = list.map(
+      (f) => f === rootHtml[0] ? { ...f, path: "index.html" } : f
+    );
+  }
+  if (!list.some((f) => isRootIndex(f.path))) {
+    const shown = list.slice(0, 8).map((f) => f.path).join(", ");
+    throw new Error(
+      `The site needs an index.html at its root. Files received: ${shown}${list.length > 8 ? ", \u2026" : ""}`
+    );
+  }
+  return list;
+}
+function guessContentType(path) {
+  const ext = (/\.([a-zA-Z0-9]+)$/.exec(path)?.[1] ?? "").toLowerCase();
+  const map = {
+    html: "text/html",
+    htm: "text/html",
+    css: "text/css",
+    js: "text/javascript",
+    mjs: "text/javascript",
+    json: "application/json",
+    svg: "image/svg+xml",
+    txt: "text/plain",
+    md: "text/markdown",
+    xml: "application/xml",
+    webmanifest: "application/manifest+json",
+    ico: "image/x-icon",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    avif: "image/avif",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    ttf: "font/ttf",
+    otf: "font/otf",
+    pdf: "application/pdf",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mp3: "audio/mpeg"
+  };
+  return map[ext] ?? "application/octet-stream";
+}
+function buildFormData(files) {
+  const fd = new FormData();
+  for (const f of files) {
+    fd.append(
+      "files",
+      new Blob([f.bytes], { type: guessContentType(f.path) }),
+      f.path
+    );
+  }
+  return fd;
+}
+
+// src/api-call/upload-headless-website-files.ts
+var UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME = "UploadHeadlessWebsiteFiles";
+var HEADLESS_BUSINESS = "https://www.wixapis.com/headless-business-setup/v1/headless-business";
+function dropAttribution(clientName) {
+  const slug = (clientName ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+  return `?campaign=mcp&agent=${encodeURIComponent(slug || "wix-mcp")}`;
+}
+var UPLOAD_HEADLESS_WEBSITE_FILES_PARAM_DESCRIPTIONS = {
+  files: "The site files as text, so file bytes never pass through a code string. Sections delimited by a line `=== FILE: <path> ===` (text, raw) or `=== FILE: <path> base64 ===` (binary, base64); `<path>` is relative to the site root and must include `index.html`. Use base64 for small binaries (icons, logos, fonts); large images/video belong behind a URL in the HTML, not in the bundle. Optional when `attachments` carries the files.",
+  attachments: "ChatGPT only. Files attached in the chat or created in your sandbox \u2014 any type: a zip of the whole site, HTML, CSS, JS, images. Pass each file as you have it, its file id or its /mnt/data path, and ChatGPT swaps it for { download_url, file_id, file_name?, mime_type? } before the call reaches Wix. No other client does this swap, so outside ChatGPT a path or file:// URL here fails at once; leave this out and use `files`, or, with a shell that reaches the internet, drop the files with curl as the StartDeployWebsite recipe shows. A zip is unpacked; a top-level folder wrapping the site is stripped. Prefer this over base64 in `files` whenever you have a file handle. Up to 10 MB per call.",
+  siteId: "The metaSiteId of the Wix Headless site to upload into: the one returned by the provision call of the StartDeployWebsite recipe for a new site, or of a site deployed earlier to replace its files. Every upload replaces the whole file set, so send all files; the URL stays the same.",
+  calledStartDeployWebsite: "Whether you called StartDeployWebsite earlier in this conversation and are following the recipe it returned. Answer truthfully; it is recorded, not checked.",
+  agentIdentity: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.agentIdentity,
+  reason: "One sentence: the user request that led here and what is being published."
+};
+function formatDropResult(r) {
+  const shown = r.files.slice(0, 60);
+  return [
+    "Uploaded; the site is live with this file set.",
+    `Live URL: ${r.siteUrl ?? "(not returned)"}`,
+    `metaSiteId: ${r.metaSiteId} \u2014 pass it as \`siteId\` to update this site later; every upload replaces the whole file set.`,
+    `Dashboard: https://manage.wix.com/dashboard/${r.metaSiteId}`,
+    `${r.files.length} file(s): ${shown.join(", ")}${r.files.length > shown.length ? ", \u2026" : ""}`,
+    "",
+    "Give the user the live URL and the dashboard link.",
+    `The upload step is done. For what comes next \u2014 changing the site later, connecting a domain, or adding a Wix backend (forms, bookings, a store) to this same site \u2014 continue with the guide you are following, from where it left off: the StartDeployWebsite recipe (${START_DEPLOY_WEBSITE_RECIPE_URL}) or, for a site built through StartHeadlessBuild, the headless guide (${HEADLESS_GUIDE_URL}).`
+  ].join("\n");
+}
+async function readJson(res, what) {
+  const text = await res.text();
+  if (!res.ok)
+    throw new WixFetchError(res.status, res.statusText, `${what}: ${text}`);
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${what} returned a non-JSON body: ${text.slice(0, 200)}`);
+  }
+}
+function errorResult2(message) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `UploadHeadlessWebsiteFiles error: ${message}`
+      }
+    ]
+  };
+}
+function addUploadHeadlessWebsiteFilesTool(server, options) {
+  const { authStrategy, toolDescriptions } = options;
+  const clientName = () => options.clientName ?? server.clientName?.() ?? server.server?.getClientVersion?.()?.name;
+  const fetchImpl = options.fetchImpl ?? ((u, i) => fetch(u, i));
+  const d = UPLOAD_HEADLESS_WEBSITE_FILES_PARAM_DESCRIPTIONS;
+  const registered = server.tool(
+    UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME,
+    toolDescriptions?.[UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME] ?? defaultToolDescriptions.UploadHeadlessWebsiteFiles,
+    {
+      files: external_exports.string().optional().describe(d.files),
+      attachments: external_exports.array(
+        external_exports.object({
+          download_url: external_exports.string(),
+          file_id: external_exports.string(),
+          file_name: external_exports.string().optional(),
+          mime_type: external_exports.string().optional()
+        })
+      ).optional().describe(d.attachments),
+      siteId: external_exports.string().uuid("siteId must be a Wix metaSiteId (UUID)").describe(d.siteId),
+      calledStartDeployWebsite: external_exports.boolean().describe(d.calledStartDeployWebsite),
+      agentIdentity: external_exports.string().min(1).describe(d.agentIdentity),
+      reason: external_exports.string().describe(d.reason)
+    },
+    // openWorldHint true: it fetches agent-supplied attachment URLs and publishes a
+    // public website.
+    { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    async (rawArgs, extra) => {
+      const {
+        files,
+        attachments,
+        siteId,
+        calledStartDeployWebsite,
+        agentIdentity,
+        reason
+      } = rawArgs;
+      logger.log(
+        `[UploadHeadlessWebsiteFiles] siteId=${siteId} calledStartDeployWebsite=${calledStartDeployWebsite} agent="${agentIdentity}" files=${files?.length ?? 0} chars attachments=${attachments?.length ?? 0} reason="${reason}"`
+      );
+      if (!files?.trim() && !(attachments && attachments.length)) {
+        return errorResult2(
+          "Nothing to publish: pass the site in `files` (text bundle) or `attachments` (files from this chat or your sandbox)."
+        );
+      }
+      let siteFiles;
+      try {
+        const fromAttachments = (await resolveAttachments(attachments, fetchImpl)).map((a) => ({ path: a.path, bytes: base64ToBytes(a.content) }));
+        siteFiles = await normalizeSiteFiles([
+          ...parseFileBundle(files),
+          ...fromAttachments
+        ]);
+      } catch (e) {
+        if (e instanceof AttachmentError || e instanceof Error)
+          return errorResult2(e.message);
+        throw e;
+      }
+      const authHeaders = await authStrategy.getAccountAuthHeaders();
+      try {
+        const metaSiteId = siteId;
+        extra?.setToolBiParams?.({ siteId: metaSiteId });
+        const dropped = await readJson(
+          await fetchImpl(
+            `${HEADLESS_BUSINESS}/${metaSiteId}/drop${dropAttribution(clientName())}`,
+            {
+              method: "POST",
+              headers: { ...authHeaders },
+              // fetch sets the multipart boundary itself
+              body: buildFormData(siteFiles)
+            }
+          ),
+          "drop"
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatDropResult({
+                metaSiteId,
+                siteUrl: dropped.siteUrl,
+                uploadId: dropped.uploadId,
+                files: siteFiles.map((f) => f.path)
+              })
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.log(`[UploadHeadlessWebsiteFiles] Error: ${message}`);
+        rethrowIfUnauthorized(err);
+        await authStrategy.enforceValidWixToken?.(err);
+        return errorResult2(message);
+      }
+    }
+  );
+  registered?.update?.({
+    _meta: { ...registered._meta, "openai/fileParams": ["attachments"] }
+  });
+}
+
 // src/code-mode/index.ts
 var defaultCodeModeFetch = (url, init) => fetch(url, init);
 var SEARCH_TOOL_NAME = "SearchWixAPISpec";
@@ -22497,7 +22970,7 @@ function addExecuteTool(server, options) {
   } = options;
   const executeUrl = `${codeModeBaseUrl}/api/code-mode/execute`;
   const d = desc("ExecuteWixAPI");
-  server.tool(
+  const registered = server.tool(
     EXECUTE_TOOL_NAME,
     toolDescriptions?.[EXECUTE_TOOL_NAME] ?? defaultToolDescriptions.ExecuteWixAPI,
     {
@@ -22514,7 +22987,7 @@ function addExecuteTool(server, options) {
         "One sentence explaining the original user request and why you are executing code to complete it."
       ),
       hasMutations: external_exports.boolean().describe(
-        visitor ? "Whether this code creates, updates, deletes, publishes, imports, uploads, or otherwise mutates site data on the visitor\u2019s behalf. Set this to true for create/update/delete/bulk create/import/upload calls even if the reason is inspection, verification, or response-shape discovery. Read-only GET/query/list/search calls can use false." : "Whether this code creates, updates, deletes, publishes, installs, imports, uploads, or otherwise mutates Wix data or site/account state. Set this to true for create/update/delete/bulk create/import/upload calls even if the reason is inspection, verification, or response-shape discovery. Read-only GET/query/list/search calls can use false."
+        visitor ? "True if the code changes site data on the visitor\u2019s behalf (create, update, delete, import, upload); false if it only reads (get, query, list, search)." : "True if the code changes anything in the Wix account or a site (create, update, delete, publish, install, import, upload); false if it only reads (get, query, list, search)."
       ),
       sourceDocUrls: external_exports.array(external_exports.string()).describe(d.sourceDocUrls),
       files: external_exports.string().optional().describe(
@@ -22526,6 +22999,20 @@ function addExecuteTool(server, options) {
           'Use base64 entries for small assets (icons, logos, fonts) and for files you downloaded and are re-uploading; large images/video go in by URL (`<img src="https://...">`), not in the bundle. A file containing a line exactly like the delimiter is not supported.'
         ].join(" ")
       ),
+      // ChatGPT file attachments (`openai/fileParams`). Item shape must match
+      // OpenAI's file schema: download_url + file_id required, the rest optional.
+      // Declaring it is what makes the platform hand us a download URL instead
+      // of a sandbox path. Resolved host-side into base64 `files` entries.
+      attachments: external_exports.array(
+        external_exports.object({
+          download_url: external_exports.string(),
+          file_id: external_exports.string(),
+          file_name: external_exports.string().optional(),
+          mime_type: external_exports.string().optional()
+        })
+      ).optional().describe(
+        'ChatGPT only. Files attached in the chat or created in your sandbox (any type: a zip of a site, HTML, images, PDFs): pass each file as you have it, its file id or its /mnt/data path, and ChatGPT swaps it for { download_url, file_id, file_name?, mime_type? } before the call reaches Wix. No other client does this swap, so outside ChatGPT a path or file:// URL here fails at once; leave this out and use `files`, or upload from your shell if it reaches the internet. The bytes are fetched here and appended to the `files` global as { path, content, encoding: "base64" } entries (path = file_name), so `wix.multipart()` and `wix.unzip()` work on them unchanged. Prefer this over base64 in `files` whenever you have a file handle. Up to 10 MB per call.'
+      ),
       // Visitor mode takes an agent-supplied token and pins the site; account/site
       // mode lets the agent pick the site.
       ...visitor ? {
@@ -22538,9 +23025,20 @@ function addExecuteTool(server, options) {
         )
       }
     },
-    { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    // openWorldHint true: agent code picks the Wix endpoints at run time (and may
+    // receive platform-resolved attachment URLs); the sandbox's host allowlist
+    // bounds it, but the operation set is open-ended, which is what the hint means.
+    { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     async (rawArgs, extra) => {
-      const { code, reason, hasMutations, sourceDocUrls, visitorToken, files } = rawArgs;
+      const {
+        code,
+        reason,
+        hasMutations,
+        sourceDocUrls,
+        visitorToken,
+        files,
+        attachments
+      } = rawArgs;
       const siteId = visitor ? visitor.siteId : rawArgs.siteId;
       logger.log(
         `[ExecuteWixAPI]${visitor ? " (visitor)" : ""} Executing code (${code.length} chars), siteId=${siteId ?? "none"}, hasMutations=${hasMutations}, sourceDocUrls=${JSON.stringify(sourceDocUrls)}, reason="${reason}"`
@@ -22552,6 +23050,13 @@ function addExecuteTool(server, options) {
         );
         return executeTextResult(validation.error);
       }
+      let attachmentFiles = [];
+      try {
+        attachmentFiles = await resolveAttachments(attachments);
+      } catch (e) {
+        if (e instanceof AttachmentError) return executeErrorResult(e.message);
+        throw e;
+      }
       const accountHeaders = await authStrategy?.getAccountAuthHeaders();
       const siteAuthContext = !visitor && authStrategy?.getSiteAuthContext ? await authStrategy.getSiteAuthContext() : void 0;
       let siteHeaders;
@@ -22586,7 +23091,8 @@ function addExecuteTool(server, options) {
             accountToken: visitor ? visitorToken : accountHeaders?.Authorization,
             accountId: accountHeaders?.["wix-account-id"],
             siteAuthContext,
-            ...files ? { files } : {}
+            ...files ? { files } : {},
+            ...attachmentFiles.length ? { attachmentFiles } : {}
           },
           visitor ? visitorToken : accountHeaders?.Authorization ?? siteHeaders?.Authorization,
           codeModeFetch
@@ -22617,6 +23123,9 @@ function addExecuteTool(server, options) {
       }
     }
   );
+  registered?.update?.({
+    _meta: { ...registered._meta, "openai/fileParams": ["attachments"] }
+  });
 }
 
 // src/infra/panorama.ts
@@ -22912,6 +23421,13 @@ function createWixToolkit(options) {
         maxResponseSize
       });
     }
+    if (requestedTools.has("UploadHeadlessWebsiteFiles") && !disableTools?.includes("UploadHeadlessWebsiteFiles")) {
+      addUploadHeadlessWebsiteFilesTool(server, {
+        authStrategy,
+        toolDescriptions: effectiveToolDescriptions,
+        clientName
+      });
+    }
     const requestedGraphqlTools = GRAPHQL_TOOL_NAMES.filter(
       (name) => requestedTools.has(name)
     );