@wix/mcp 1.0.94 → 1.0.96

package/build/dts/api-call/upload-image-tool.d.ts

@@ -5,5 +5,7 @@ export declare const UPLOAD_IMAGE_TOOL_NAME = "UploadImageToWixSite";
 export declare function addUploadImageTool(server: WixMcpServer, strategy: McpAuthenticationStrategy, options?: {
     description?: string;
     hints?: ToolHintsConfig;
+    /** Set when the session also has the image picker (Claude clients). */
+    imagePickerToolName?: string;
 }): void;
 //# sourceMappingURL=upload-image-tool.d.ts.map

package/build/dts/api-call/upload-image-tool.js

@@ -51,7 +51,7 @@ function errorResponse(text) {
 // ---------------------------------------------------------------------------
 // Upload flows
 // ---------------------------------------------------------------------------
-async function uploadFromUrl(item, authHeaders, displayName) {
+async function uploadFromUrl(item, authHeaders, displayName, imagePickerToolName) {
     if (!item.download_url) {
         return {
             success: false,
@@ -61,7 +61,7 @@ async function uploadFromUrl(item, authHeaders, displayName) {
     if (!/^https?:\/\//i.test(item.download_url)) {
         return {
             success: false,
-            error: `download_url must be a publicly accessible http(s) URL, not a local or sandbox file path (got: "${item.download_url}"). For a user-attached file, pass the file so the platform resolves it to a real download_url; if you only have the raw bytes, use imageBase64 instead.`
+            error: `This server can't read files on your machine or sandbox (got: "${item.download_url}"). Send this image as imageBase64 (the whole file, one per call) or as a public URL in imageUrls${imagePickerToolName ? `, or call ${imagePickerToolName} so the user picks it` : ''}.`
         };
     }
     try {
@@ -165,7 +165,11 @@ function formatBatchResults(results) {
 // Tool registration
 // ---------------------------------------------------------------------------
 export function addUploadImageTool(server, strategy, options) {
-    const description = options?.description ?? defaultToolDescriptions.UploadImageToWixSite;
+    const imagePickerToolName = options?.imagePickerToolName;
+    const baseDescription = options?.description || defaultToolDescriptions.UploadImageToWixSite;
+    const description = imagePickerToolName
+        ? `${baseDescription}\nIf you can't deliver the image any of these ways, call ${imagePickerToolName} so the user picks it.`
+        : baseDescription;
     const hints = {
         readOnlyHint: options?.hints?.readOnlyHint ?? false,
         destructiveHint: options?.hints?.destructiveHint ?? false,
@@ -226,7 +230,7 @@ export function addUploadImageTool(server, strategy, options) {
         logger.log(`[WixMCP] Uploading ${total} image(s) to Wix site: ${siteId}`);
         try {
             const authHeaders = await strategy.getSiteAuthHeaders(siteId);
-            const urlResults = await Promise.all(urlItems.map((item) => uploadFromUrl(item, authHeaders, displayName)));
+            const urlResults = await Promise.all(urlItems.map((item) => uploadFromUrl(item, authHeaders, displayName, imagePickerToolName)));
             let base64Result = null;
             if (imageBase64) {
                 const result = await uploadFromBase64(imageBase64, mimeType, authHeaders, displayName);

package/build/dts/bin.d.ts

@@ -1,5 +1,5 @@
 import './infra/sentry.js';
-declare const PUBLIC_TOOLS: readonly ["WDS", "REST", "SDK", "BUILD_APPS", "WIX_HEADLESS", "VELO", "BUSINESS_SOLUTIONS", "CLI", "OVERVIEW"];
+declare const PUBLIC_TOOLS: readonly ["WDS", "REST", "SDK", "BUILD_APPS", "WIX_HEADLESS", "VELO", "BUSINESS_SOLUTIONS", "CLI", "OVERVIEW", "HELP_CENTER"];
 declare const EXPERIMENTAL_TOOLS: readonly ["WIX_API", "CLI_COMMAND", "GET_TO_KNOW_WIX", "CREATE_WIX_BUSINESS_GUIDE", "VELO_README", "WIX_API_THROUGH_FS", "GRAPHQL"];
 type Tool = (typeof PUBLIC_TOOLS)[number] | (typeof EXPERIMENTAL_TOOLS)[number];
 export declare const DEFAULT_TOOLS: Tool[];

package/build/dts/bin.js

@@ -95,7 +95,9 @@ if (docsTools.length > 0 || hasGetToKnowWix) {
     logger.log('Adding docs tools:', docsTools);
     addDocsTools(server, docsTools, {
         getToKnowWixEnabled: hasGetToKnowWix,
-        dynamicContextEnabled: hasDynamicContext
+        dynamicContextEnabled: hasDynamicContext,
+        // Mintlify docs: --docsSite=mintlify-links (or WIX_MCP_DOCS_SITE).
+        docsSite: parsedArgs['docsSite'] ?? process.env.WIX_MCP_DOCS_SITE
     });
 }
 if (activeTools.includes('VELO_README')) {

package/build/dts/code-mode/attachments.d.ts

@@ -1,11 +1,13 @@
 /**
- * ChatGPT file attachments for ExecuteWixAPI (`openai/fileParams`).
+ * Chat file attachments for ExecuteWixAPI (`openai/fileParams`).
  *
  * ChatGPT resolves a file the user attached — or one the model wrote in its
  * own sandbox — into `{ download_url, file_id, file_name?, mime_type? }` for a
- * param the tool lists under `_meta["openai/fileParams"]`. The bytes never go
- * through the model. We fetch each `download_url` host-side and hand the
- * runtime ready-made base64 file entries, the same shape the `files` bundle
+ * param the tool lists under `_meta["openai/fileParams"]`. For ExecuteWixAPI the
+ * Wix AI Assistant (Aria) does the same by swapping an `attachment://<id>`
+ * reference in the tool args for a signed URL on its own Wix storage. The
+ * bytes never go through the model. We fetch each `download_url` host-side and
+ * hand the runtime ready-made base64 file entries, the same shape the `files` bundle
  * parses into, so `files`, `wix.multipart()` and `wix.unzip()` are unchanged.
  *
  * This is additive: clients without the extension never populate the param
@@ -24,7 +26,8 @@ export interface AttachmentFile {
     encoding: 'base64';
 }
 export declare const MAX_ATTACHMENTS_BYTES: number;
-export declare function isAllowedAttachmentHost(hostname: string): boolean;
+export declare const WIX_AI_ASSISTANT_ATTACHMENT_HOSTS: ReadonlySet<string>;
+export declare function isAllowedAttachmentHost(hostname: string, extraHosts?: ReadonlySet<string>): boolean;
 export declare class AttachmentError extends Error {
 }
 /**
@@ -33,5 +36,5 @@ export declare class AttachmentError extends Error {
  * (ChatGPT passed a sandbox path or a bare id instead of a URL), a host we
  * don't trust, a failed download, or more bytes than MAX_ATTACHMENTS_BYTES.
  */
-export declare function resolveAttachments(attachments: unknown, fetchImpl?: typeof fetch): Promise<AttachmentFile[]>;
+export declare function resolveAttachments(attachments: unknown, fetchImpl?: typeof fetch, extraHosts?: ReadonlySet<string>): Promise<AttachmentFile[]>;
 //# sourceMappingURL=attachments.d.ts.map

package/build/dts/code-mode/attachments.js

@@ -1,11 +1,13 @@
 /**
- * ChatGPT file attachments for ExecuteWixAPI (`openai/fileParams`).
+ * Chat file attachments for ExecuteWixAPI (`openai/fileParams`).
  *
  * ChatGPT resolves a file the user attached — or one the model wrote in its
  * own sandbox — into `{ download_url, file_id, file_name?, mime_type? }` for a
- * param the tool lists under `_meta["openai/fileParams"]`. The bytes never go
- * through the model. We fetch each `download_url` host-side and hand the
- * runtime ready-made base64 file entries, the same shape the `files` bundle
+ * param the tool lists under `_meta["openai/fileParams"]`. For ExecuteWixAPI the
+ * Wix AI Assistant (Aria) does the same by swapping an `attachment://<id>`
+ * reference in the tool args for a signed URL on its own Wix storage. The
+ * bytes never go through the model. We fetch each `download_url` host-side and
+ * hand the runtime ready-made base64 file entries, the same shape the `files` bundle
  * parses into, so `files`, `wix.multipart()` and `wix.unzip()` are unchanged.
  *
  * This is additive: clients without the extension never populate the param
@@ -26,7 +28,7 @@ const MAX_REDIRECTS = 4;
 // - Azure blob accounts behind them, one per OpenAI region.
 //   `blob.core.windows.net` is a shared namespace, so these are exact — a
 //   prefix could be registered by anyone. A new region shows up as an
-//   "is not a ChatGPT file host" error in BI; add it here.
+//   "is not a chat attachment host" error in BI; add it here.
 const OAI_USERCONTENT_HOST = /^[a-z0-9-]+\.oaiusercontent\.com$/;
 const OAI_BLOB_ACCOUNTS = new Set([
     'australiaeast',
@@ -55,18 +57,23 @@ const OAI_BLOB_ACCOUNTS = new Set([
     'westus2',
     'westus3'
 ].map((region) => `oaisdmntpr${region}.blob.core.windows.net`));
-export function isAllowedAttachmentHost(hostname) {
+export const WIX_AI_ASSISTANT_ATTACHMENT_HOSTS = new Set([
+    'wixmp-a85a29aaf55baa3e5171a82d.wixmp.com'
+]);
+export function isAllowedAttachmentHost(hostname, extraHosts) {
     const h = hostname.toLowerCase();
-    return OAI_USERCONTENT_HOST.test(h) || OAI_BLOB_ACCOUNTS.has(h);
+    return (OAI_USERCONTENT_HOST.test(h) ||
+        OAI_BLOB_ACCOUNTS.has(h) ||
+        !!extraHosts?.has(h));
 }
 /** https, default port, allowed host — applied to the first URL and every redirect. */
-function checkAttachmentUrl(url) {
+function checkAttachmentUrl(url, extraHosts) {
     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`;
+    if (!isAllowedAttachmentHost(url.hostname, extraHosts)) {
+        return `host "${url.hostname}" is not a chat attachment host`;
     }
     return undefined;
 }
@@ -98,7 +105,7 @@ function toBase64(bytes) {
  * GET with manual redirects: every hop must pass checkAttachmentUrl, so an
  * allowed host cannot bounce the server to an arbitrary or internal one.
  */
-async function fetchAllowed(start, fetchImpl, label) {
+async function fetchAllowed(start, fetchImpl, label, extraHosts) {
     let url = start;
     for (let hop = 0;; hop++) {
         const res = await fetchImpl(url.toString(), { redirect: 'manual' });
@@ -117,7 +124,7 @@ async function fetchAllowed(start, fetchImpl, label) {
         catch {
             throw new AttachmentError(`${label}: redirect to an invalid URL.`);
         }
-        const problem = checkAttachmentUrl(next);
+        const problem = checkAttachmentUrl(next, extraHosts);
         if (problem) {
             throw new AttachmentError(`${label}: the download redirected to a URL that ${problem}; refused.`);
         }
@@ -166,7 +173,7 @@ async function readWithin(res, budget, overBudget) {
  * (ChatGPT passed a sandbox path or a bare id instead of a URL), a host we
  * don't trust, a failed download, or more bytes than MAX_ATTACHMENTS_BYTES.
  */
-export async function resolveAttachments(attachments, fetchImpl = fetch) {
+export async function resolveAttachments(attachments, fetchImpl = fetch, extraHosts) {
     if (!Array.isArray(attachments) || attachments.length === 0)
         return [];
     const items = [];
@@ -185,9 +192,9 @@ export async function resolveAttachments(attachments, fetchImpl = fetch) {
         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);
+        const problem = checkAttachmentUrl(url, extraHosts);
         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.`);
+            throw new AttachmentError(`attachments[${i}].download_url ${problem}. \`attachments\` takes only files the chat platform attached and resolved; leave it out. For a file at a URL, import it in \`code\` with \`POST https://www.wixapis.com/site-media/v1/files/import\` and \`{ url }\` (Wix fetches it); for a small file you have as text, use the \`files\` bundle.`);
         }
         items.push({ a, url });
     });
@@ -198,7 +205,7 @@ export async function resolveAttachments(attachments, fetchImpl = fetch) {
         const label = `attachments[${i}] (${path})`;
         let res;
         try {
-            res = await fetchAllowed(url, fetchImpl, label);
+            res = await fetchAllowed(url, fetchImpl, label, extraHosts);
         }
         catch (e) {
             if (e instanceof AttachmentError)

package/build/dts/code-mode/index.d.ts

@@ -20,8 +20,13 @@ export interface CodeModeOptions {
     };
     disableTools?: string[];
     toolDescriptions?: Record<string, string>;
-    /** Max response size in chars before truncation (default: 24,000, ~6,000 tokens). */
+    /** Max response size in chars before truncation (defaults: ExecuteWixAPI 100,000, SearchWixAPISpec 64,000). */
     maxResponseSize?: number;
+    /**
+     * The connection's docsSite (see ../docs/mintlify-docs.ts). SearchWixAPISpec
+     * passes it on, so a Mintlify mode also finds schemas by Mintlify page URL.
+     */
+    docsSite?: string;
 }
 export declare const EXECUTE_TOOL_NAME = "ExecuteWixAPI";
 export declare function addCodeModeTools(server: WixMcpServer, options: CodeModeOptions): Promise<void>;

package/build/dts/code-mode/index.js

@@ -1,11 +1,13 @@
 import { z } from 'zod';
-import { AttachmentError, resolveAttachments } from './attachments.js';
+import { AttachmentError, WIX_AI_ASSISTANT_ATTACHMENT_HOSTS, resolveAttachments } from './attachments.js';
+import { fileParamNote } from '../config/file-params.js';
 import { logger } from '../infra/logger.js';
 import { defaultToolDescriptions } from '../config/default-config.js';
 import { truncateResponse } from './truncate-response.js';
 import { MAX_ALLOWED_RESPONSE_CHARS } from '../infra/response-size-limits.js';
 import { validateExecuteCode } from './validation.js';
 import { desc } from '../config/param-descriptions.js';
+import { isMintlifyDocsSite, rewriteDocsLinks, toDevWixHostText } from '../docs/mintlify-docs.js';
 import { rethrowIfUnauthorized } from '../auth/index.js';
 import { WixFetchError } from '../wix-fetch-error.js';
 import { addUploadHeadlessWebsiteFilesTool, UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME } from '../api-call/upload-headless-website-files.js';
@@ -44,13 +46,13 @@ export async function addCodeModeTools(server, options) {
  * lightIndex.
  */
 export function addSearchCodeModeTool(server, options) {
-    const { codeModeBaseUrl, codeModeFetch, authStrategy, disableTools = [], toolDescriptions, maxResponseSize } = options;
+    const { codeModeBaseUrl, codeModeFetch, authStrategy, disableTools = [], toolDescriptions, maxResponseSize, docsSite } = options;
     if (disableTools.includes(SEARCH_TOOL_NAME)) {
         return;
     }
     const description = toolDescriptions?.[SEARCH_TOOL_NAME] ??
         defaultToolDescriptions.SearchWixAPISpec;
-    registerSearchTool(server, codeModeBaseUrl, description, maxResponseSize, authStrategy, codeModeFetch);
+    registerSearchTool(server, codeModeBaseUrl, description, maxResponseSize, authStrategy, codeModeFetch, docsSite);
 }
 export function addExecuteCodeModeTool(server, options) {
     const { codeModeBaseUrl, codeModeFetch, authStrategy, visitor, disableTools = [], toolDescriptions, maxResponseSize } = options;
@@ -67,6 +69,9 @@ export function addExecuteCodeModeTool(server, options) {
     });
 }
 const SEARCH_MAX_RESPONSE_CHARS = 64_000;
+// ExecuteWixAPI's own default, ~25,000 tokens, so a full API listing comes back
+// whole. A session's maxResponseSize still overrides it.
+const EXECUTE_MAX_RESPONSE_CHARS = 100_000;
 /**
  * Search needs no auth of its own; without a header the call is bucketed by the
  * Worker's own IP (see postExecute). Anonymous sessions throw here and stay on
@@ -80,7 +85,7 @@ async function resolveLoopbackAuthorization(authStrategy) {
         return undefined;
     }
 }
-function registerSearchTool(server, codeModeBaseUrl, description, maxResponseSize, authStrategy, codeModeFetch = defaultCodeModeFetch) {
+function registerSearchTool(server, codeModeBaseUrl, description, maxResponseSize, authStrategy, codeModeFetch = defaultCodeModeFetch, docsSite) {
     const searchUrl = `${codeModeBaseUrl}/api/code-mode/search`;
     server.tool(SEARCH_TOOL_NAME, description, {
         code: z
@@ -99,7 +104,8 @@ function registerSearchTool(server, codeModeBaseUrl, description, maxResponseSiz
                     'Content-Type': 'application/json',
                     ...(authorization ? { Authorization: authorization } : {})
                 },
-                body: JSON.stringify({ code })
+                // docsSite only when set: without it the request is as before.
+                body: JSON.stringify(docsSite ? { code, docsSite } : { code })
             });
             if (!resp.ok) {
                 const errorBody = await resp.text();
@@ -126,7 +132,13 @@ function registerSearchTool(server, codeModeBaseUrl, description, maxResponseSiz
                     ]
                 };
             }
-            const text = truncateResponse(data.result, maxResponseSize ?? SEARCH_MAX_RESPONSE_CHARS);
+            // Mintlify docs: the index shows docsUrls on the Mintlify host by rule.
+            // Map them back, then resolve each to its Mintlify page as the docs tools
+            // do, so a page the site doesn't have keeps its dev.wix.com link.
+            const result = isMintlifyDocsSite(docsSite) && data.result !== undefined
+                ? JSON.parse((await rewriteDocsLinks(toDevWixHostText(JSON.stringify(data.result)), { label: 'search SearchWixAPISpec' })).text)
+                : data.result;
+            const text = truncateResponse(result, maxResponseSize ?? SEARCH_MAX_RESPONSE_CHARS);
             return {
                 content: [{ type: 'text', text }]
             };
@@ -167,10 +179,13 @@ async function postExecute(executeUrl, body, authorization, codeModeFetch = defa
     }
     return (await resp.json());
 }
-function executeErrorResult(message) {
+function executeErrorResult(message, failedCalls) {
     return {
         isError: true,
-        content: [{ type: 'text', text: `Execute error: ${message}` }]
+        content: [{ type: 'text', text: `Execute error: ${message}` }],
+        // The failed calls as fields, request ids included. The text carries the
+        // ids too, for clients that don't read structured results.
+        ...(failedCalls?.length ? { structuredContent: { failedCalls } } : {})
     };
 }
 function executeTextResult(message) {
@@ -180,7 +195,7 @@ function executeTextResult(message) {
 }
 function formatExecuteResult(data, maxResponseSize, reportBi) {
     if (data.error) {
-        return executeErrorResult(data.error);
+        return executeErrorResult(data.error, data.failedCalls);
     }
     // Before the slice -- resultTextLength is measured after it and saturates.
     reportBi?.({
@@ -203,7 +218,10 @@ function formatExecuteResult(data, maxResponseSize, reportBi) {
     }
     return {
         content: [
-            { type: 'text', text: truncateResponse(data.result, maxResponseSize) }
+            {
+                type: 'text',
+                text: truncateResponse(data.result, maxResponseSize ?? EXECUTE_MAX_RESPONSE_CHARS)
+            }
         ]
     };
 }
@@ -269,7 +287,8 @@ function addExecuteTool(server, options) {
             mime_type: z.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.'),
+            .describe(fileParamNote('use `files`, or upload from your shell if it reaches the internet') +
+            ' Any type: a zip of a site, HTML, images, PDFs. 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
@@ -309,7 +328,7 @@ function addExecuteTool(server, options) {
         // an agent-facing error, not a server failure.
         let attachmentFiles = [];
         try {
-            attachmentFiles = await resolveAttachments(attachments);
+            attachmentFiles = await resolveAttachments(attachments, undefined, WIX_AI_ASSISTANT_ATTACHMENT_HOSTS);
         }
         catch (e) {
             if (e instanceof AttachmentError)
@@ -360,6 +379,7 @@ function addExecuteTool(server, options) {
                 sessionId,
                 toolInvocationId,
                 clientName: server.server?.getClientVersion?.()?.name,
+                ...(visitor ? { visitorMode: true } : {}),
                 // A visitor token is a site-scoped bearer token: sent as siteToken
                 // (→ Authorization + wix-site-id) and as accountToken only to satisfy
                 // the runtime's required field. Account/site mode uses strategy tokens.

package/build/dts/code-mode/truncate-response.js

@@ -17,6 +17,10 @@ export function truncateResponse(content, maxChars = DEFAULT_MAX_CHARS) {
     const truncated = text.slice(0, effectiveMax);
     const estimatedTokens = Math.ceil(text.length / CHARS_PER_TOKEN);
     const limitTokens = Math.ceil(effectiveMax / CHARS_PER_TOKEN);
-    return `${truncated}\n\n--- TRUNCATED ---\nResponse was ~${estimatedTokens.toLocaleString()} tokens (limit: ${limitTokens.toLocaleString()}). Refine your code to return less data.`;
+    const cutChars = text.length - effectiveMax;
+    const note = `Response was ~${estimatedTokens.toLocaleString()} tokens (limit: ${limitTokens.toLocaleString()}). Showing the first ${effectiveMax.toLocaleString()} of ${text.length.toLocaleString()} characters; the last ${cutChars.toLocaleString()} were cut. To get the rest, run again and return less per call — only the fields you need, the next page (cursor or offset), or the next slice of a large array — and repeat until you have it all.`;
+    // At the top as well as the end: a client that cuts a long result keeps its
+    // head, so a note only at the end is the first thing lost.
+    return `[TRUNCATED: ${note}]\n\n${truncated}\n\n--- TRUNCATED ---\n${note}`;
 }
 //# sourceMappingURL=truncate-response.js.map

package/build/dts/config/default-config.d.ts

@@ -21,29 +21,48 @@ export interface ModeDefaultConfig {
     skillsPrOverrideEnabled?: boolean;
     graphqlEnabled?: boolean;
 }
+/**
+ * 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 declare 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 declare const CALL_WIX_SITE_API_NO_EXECUTE_LINE = "If ExecuteWixAPI isn't in your tool list, use this tool.";
 export declare const SYSTEM_REMINDER_GUIDELINES: string;
 export declare function buildSystemReminder(includeReadme: boolean, includeImageUploadGuidance?: boolean): string;
 export declare const SYSTEM_REMINDER: string;
+/** SearchWixHelpCenter's description and response both carry this: Help Center is for people, the developer docs for the agent's own actions. */
+export declare 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 declare 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). WixHarmonyEditorBuild or SearchSiteTemplates only when the user asked for Wix's editor, the Wix Harmony Editor, a template, Wix Studio or the Classic Editor. Call WixREADME first, except ListWixSites, UploadImageToWixSite, GetSuggestedDomains.";
+/** The tools SERVER_INSTRUCTIONS names. */
+export declare const SERVER_INSTRUCTIONS_TOOLS: string[];
 export declare const SITE_CREATION_COPY: {
     readonly templatePick: {
         readonly nonWidget: "After the user selects a template, call `CreateSiteFromTemplate`.";
         readonly widget: "The gallery creates the site when the user picks one.";
     };
-    readonly unstatedMethod: {
-        readonly 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";
-        readonly widget: "you MUST call `WixSiteCreation` and let them choose";
-    };
 };
 /** Rewrites non-widget copy into its widget form; a no-op on text that carries no divergence. */
 export declare const toWidget: (text: string) => string;
 export declare const executeWixApiDescription: string;
-export declare function buildToolDescriptions(includeReadme: boolean, includeImageUploadGuidance?: boolean): Record<string, string>;
+export declare function buildToolDescriptions(includeReadme: boolean, includeImageUploadGuidance?: boolean, { usageGuideOnce }?: {
+    usageGuideOnce?: boolean;
+}): Record<string, string>;
 /**
  * Canonical (README-inclusive) tool descriptions used by the live MCP server and
  * all existing importers.
  */
 export declare const defaultToolDescriptions: Record<string, string>;
 export declare const executeCodeModeToolDescriptions: Record<string, string>;
+export declare const WIX_SKILLS_README_SECTION: string;
 /**
  * Default readme docs - content for WixREADME tool response.
  * Assumes both ExecuteWixAPI and SearchWixAPISpec are available (execute-and-search mode).
@@ -51,6 +70,9 @@ export declare const executeCodeModeToolDescriptions: Record<string, string>;
  * Joined rather than interpolated into one `dedent` — `dedent` reads indentation from the literal
  * parts only, so a multi-line interpolation gets flattened.
  */
+export declare function buildReadmeDocs({ recipesIndex }?: {
+    recipesIndex?: boolean;
+}): ReadmeDocConfig[];
 export declare const defaultReadmeDocs: ReadmeDocConfig[];
 /**
  * Merge base config with overrides
@@ -64,6 +86,14 @@ export declare function mergeConfig(base: ModeDefaultConfig, overrides: Partial<
  * All tools enabled, all descriptions, good readmeDocs
  */
 export declare const defaultConfig: ModeDefaultConfig;
+/**
+ * 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 declare function withUsageGuideOnEveryTool<Config extends {
+    toolDescriptions?: Record<string, string>;
+}>(config: Config): Config;
 /**
  * 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.