@wix/mcp 1.0.94 → 1.0.96

package/build/dts/api-call/upload-headless-website-files.js

@@ -5,22 +5,55 @@
  * `/headless-business/{msid}/drop`. Provisioning the site is NOT done here —
  * the recipe's step 1 (StartDeployWebsite → provision) stays with the agent.
  *
+ * A Wix Astro build among the files (`.wix/build-metadata.json` beside `dist/`,
+ * zipped from the project root) takes headless-business-setup's bundle routes
+ * instead, server-side in this handler: `bundle-upload-url` with the zip's size, a
+ * PUT of the zip, a PUT of the project's source zip when the upload holds the
+ * source and the site's repository takes it, then `release-bundle`. The service
+ * provisions the site's managed project and deploys. Same inputs, same siteId.
+ *
  * Takes the same file inputs as ExecuteWixAPI — the `files` text bundle and
  * ChatGPT `attachments` (openai/fileParams) — and does the work directly: parse,
- * unzip, check the site shape, POST, return the live URL. No sandbox, no
+ * unzip, check the site shape, upload, return the live URL. No sandbox, no
  * agent-written code, no runtime dependency.
+ *
+ * A Wix Astro build from a client that cannot hand a file to the tool (no attachment
+ * swap, bytes only as text) has a third form, in two calls over the same routes:
+ * `prepare: true` with the build zip's `size` returns presigned PUT URLs for the
+ * build zip and the project's source zip (the agent uploads them with curl from its
+ * sandbox), and a second call with the `uploadKey` releases the uploaded build
+ * server-side. A static site keeps the drop: `files`, `attachments`, or the
+ * StartDeployWebsite recipe's own drop. Same schema for every client; the
+ * description speaks in capabilities, not names.
  */
 import { z } from 'zod';
 import { AttachmentError, resolveAttachments } from '../code-mode/attachments.js';
-import { base64ToBytes, buildFormData, normalizeSiteFiles, parseFileBundle } from './site-files.js';
+import { base64ToBytes, buildFormData, expandSiteFiles, isZip, staticSiteFiles, parseFileBundle, zipStored } from './site-files.js';
+import { buildSourceFiles, findHeadlessBuild, withoutEmptyStatics } from './headless-release.js';
+import { fileParamNote } from '../config/file-params.js';
+import { WIX_BUSINESS_FEATURES } from '../site-widget-tools/constants.js';
+import { NO_PERSONAL_DATA } from '../docs/start-deploy-website.js';
 import { HEADLESS_GUIDE_URL } from '../docs/start-headless-build.js';
+import { fetchArticleContent } from '../docs/fetch-article.js';
 import { logger } from '../infra/logger.js';
+import { redactPersonalData } from '../infra/redact-personal-data.js';
 import { defaultToolDescriptions } from '../config/default-config.js';
 import { rethrowIfUnauthorized } from '../auth/index.js';
 import { WixFetchError } from '../wix-fetch-error.js';
-import { START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS, START_DEPLOY_WEBSITE_RECIPE_URL as RECIPE_URL } from '../docs/start-deploy-website.js';
+import { START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS } from '../docs/start-deploy-website.js';
 export const UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME = 'UploadHeadlessWebsiteFiles';
 const HEADLESS_BUSINESS = 'https://www.wixapis.com/headless-business-setup/v1/headless-business';
+/** The largest site zip `bundle-upload-url` presigns (headless-business-setup's MAX_BUNDLE_BYTES). */
+export const MAX_BUNDLE_BYTES = 100 * 1024 * 1024;
+/**
+ * The static files a build's client folder can hold and still release. Builds of up to 2,550
+ * released and every one from 4,818 failed (headless-business-setup logs, October 2026): the
+ * deployments service's reply outgrows its 4 MiB gRPC limit well before its 5,000-file cap.
+ * Both failures reach us as a bare 500.
+ */
+export const MAX_RELEASE_STATIC_FILES = 2_500;
+/** Code Store refuses a larger source zip (`REPOSITORY_ARCHIVE_TOO_LARGE`), and with it the release. */
+export const MAX_SOURCE_ZIP_BYTES = 64 * 1024 * 1024;
 /**
  * Attribution the drop endpoint stamps on its upload BI event (`source` from
  * `campaign`, `agent` from `agent`, both ≤ 64 chars) — the same parser as the
@@ -36,13 +69,36 @@ export function dropAttribution(clientName) {
     return `?campaign=mcp&agent=${encodeURIComponent(slug || 'wix-mcp')}`;
 }
 export const 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 — 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.',
+    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; a static site 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. A Wix Astro build (`.wix/build-metadata.json` and `dist/` as `astro build` with the Wix hosting adapter wrote them, zipped from the project root) needs no `index.html`: it is released to the site's Wix hosting instead of dropped, and the project's other files in the upload are stored as its source when the site's repository accepts it.",
+    attachments: fileParamNote('for a static site use `files`, or drop the files as the StartDeployWebsite recipe shows; for a Wix Astro build from a shell that reaches the internet, zip it, call with `prepare: true` and its `size` and PUT the zips with curl') +
+        " Any type: a zip of the whole site, HTML, CSS, JS, images. A zip is unpacked; a top-level folder wrapping the site is stripped. A Wix Astro build zipped with the whole project (minus `node_modules`) is released with its source stored when the site's repository accepts it. Prefer this over base64 in `files` whenever you have a file handle. Up to 10 MB per call.",
+    prepare: "Phase one of the two-call upload of a Wix Astro build, for a shell that reaches the internet and no file handle (a sandbox whose network is limited to a few hosts cannot upload to the URLs): zip the build first, then `true` with its `size` returns presigned upload URLs for the build zip and, when the site's repository takes it, the project source zip, as `curl` commands to run verbatim, with the exact second call. The two calls: {siteId, prepare: true, size}, then {siteId, uploadKey, sourceUploadId?, expectedHeadRevisionId?, releaseNotes?}. No `files`, `attachments`, `uploadKey` or `sourceUploadId` on the first; `expectedHeadRevisionId` and `releaseNotes` given on the first are echoed into the second. Not for a static site: send its files in `files` or `attachments`, or drop them as the StartDeployWebsite recipe shows.",
+    size: `Phase one, with \`prepare: true\` only, and required there: the build zip's length in bytes (\`wc -c < build.zip\`), 1 to ${MAX_BUNDLE_BYTES} (100 MB). The upload URL takes a body of exactly this length; a zip changed after the prepare needs a new prepare.`,
+    uploadKey: 'Phase two of the two-call upload: the `uploadKey` the `prepare` call returned, after the build zip was PUT to its URL. Releases that build to the site: {siteId, uploadKey, sourceUploadId?, expectedHeadRevisionId?, releaseNotes?}. Excludes `files` and `attachments`.',
+    sourceUploadId: 'Phase two: the `sourceUploadId` the `prepare` call returned, after the source zip was PUT to its URL. Stores the project source with the release. Needs `uploadKey`; leave it out when the prepare returned no source upload.',
+    expectedHeadRevisionId: 'The repository revision your project started from, so the source replaces only that and a commit made since (another chat, a Dev Machine) is never dropped unseen: the revision you downloaded the project at; for a project started here, the `headRevisionId` the `prepare` call returned. Leave it out only for a repository with nothing in it yet. Goes with `uploadKey`, or with `files`/`attachments` holding a build.',
+    releaseNotes: 'Optional: one line on what this release changes, at most 200 characters, kept with the deployment of a Wix Astro build, whether it comes in `files`/`attachments` or as the second call with `uploadKey` (given on the `prepare` call it is echoed into the second). A static drop keeps no notes.',
+    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. A build released here replaces static pages dropped earlier, at the same URL.',
     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.'
+    reason: `One sentence: the user request that led here and what is being published. ${NO_PERSONAL_DATA}`
 };
+// The wix-manage skill's recipes, which the success reply points to for what comes next.
+const UPLOAD_RECIPE_SKILL_URL = 'https://www.wix.com/skills/wix-manage/references/sites/upload-static-site.md';
+const DOMAIN_RECIPE_SKILL_URL = 'https://www.wix.com/skills/wix-manage/references/domains/domain-search-purchase-and-connect.md';
+/** The headless guide, inline, after a static drop: the same page StartHeadlessBuild returns. */
+export function formatInlineGuide(guide) {
+    if (!guide || !guide.trim())
+        return '';
+    return [
+        '',
+        '---',
+        '',
+        `Wix's headless guide, the build of a site that needs Wix business features (also at https://www.wix.com/headless/skill.md):`,
+        '',
+        guide.trim()
+    ].join('\n');
+}
 export function formatDropResult(r) {
     const shown = r.files.slice(0, 60);
     return [
@@ -52,10 +108,247 @@ export function formatDropResult(r) {
         `Dashboard: https://manage.wix.com/dashboard/${r.metaSiteId}`,
         `${r.files.length} file(s): ${shown.join(', ')}${r.files.length > shown.length ? ', …' : ''}`,
         '',
-        'Give the user the live URL and the dashboard link.',
-        `The upload step is done. For what comes next — changing the site later, connecting a domain, or adding a Wix backend (forms, bookings, a store) to this same site — continue with the guide you are following, from where it left off: the StartDeployWebsite recipe (${RECIPE_URL}) or, for a site built through StartHeadlessBuild, the headless guide (${HEADLESS_GUIDE_URL}).`
+        `Give the user both links, each on its own line and named for what it is: the live site, and the site's dashboard. Then offer a custom domain, bought through Wix or one they already own (${DOMAIN_RECIPE_SKILL_URL}).`,
+        '',
+        `- To change this site later: "Change it later" in ${UPLOAD_RECIPE_SKILL_URL}, with this metaSiteId (${r.metaSiteId}). The same site every time, never a new one.`,
+        `- When the site needs Wix business features (${WIX_BUSINESS_FEATURES}), a drop of static pages is not its build: a full Wix Headless site has those features run by Wix and its pages reading from them. That build is Wix's headless guide, https://www.wix.com/headless/skill.md (what StartHeadlessBuild returns; call it with startingPoint "an existing Wix Headless site", this site is one): it installs the solution on this site, seeds its content through the API, and puts up pages that fetch it, uploaded here again. A site with no business features is done.`
+    ].join('\n');
+}
+/** The curl that PUTs a zip to its presigned URL, with the headers the route returned. */
+function curlPut(zipName, put, fallback) {
+    const headers = Object.entries(put.headers && Object.keys(put.headers).length ? put.headers : fallback);
+    return [
+        'curl -X PUT',
+        ...headers.map(([k, v]) => `-H "${k}: ${v}"`),
+        `--data-binary @${zipName} "${put.putUrl}"`
+    ].join(' ');
+}
+const BUILD_ZIP_CONTENTS = 'Build zip, from the project root after `astro build` with the Wix hosting adapter: `dist/` (with `dist/_wix/app-manifest.json`) and `.wix/build-metadata.json`.';
+const SOURCE_ZIP_CONTENTS = 'Source zip, from the project root: the project minus `node_modules`, `dist`, `.wix`, `.astro`, `.env*` and `.agents`.';
+/** The prepare reply: what the agent runs, verbatim, and the exact second call. */
+export function formatPrepareResult(siteId, urls, size, given = {}) {
+    const expiry = urls.expiresAt ? ` They expire at ${urls.expiresAt}.` : '';
+    const secondCall = {
+        siteId,
+        uploadKey: urls.uploadKey
+    };
+    const zipHeaders = {
+        'content-type': 'application/zip',
+        ...(size ? { 'content-length': String(size) } : {})
+    };
+    const lines = [
+        `Upload URLs ready for site ${siteId}.${expiry} Two steps, then call this tool again.`,
+        '',
+        `1. ${BUILD_ZIP_CONTENTS} Its client folder (\`dist/client\`) holds at most ${MAX_RELEASE_STATIC_FILES} files (\`find dist/client -type f | wc -l\`); a larger build fails the release. Upload the zip you measured${size ? ` (${size} bytes)` : ''}; the URL takes a body of exactly that length, so a zip changed since needs a new prepare with its size:`,
+        `   ${curlPut('build.zip', urls, zipHeaders)}`
+    ];
+    // The agent's own revision wins: it is the one its project started from. Given, it is echoed
+    // whether or not a source half came back.
+    if (given.expectedHeadRevisionId)
+        secondCall.expectedHeadRevisionId = given.expectedHeadRevisionId;
+    if (urls.source) {
+        const s = urls.source;
+        secondCall.sourceUploadId = s.uploadId;
+        if (!secondCall.expectedHeadRevisionId && s.headRevisionId)
+            secondCall.expectedHeadRevisionId = s.headRevisionId;
+        lines.push('', `2. ${SOURCE_ZIP_CONTENTS} At most 64 MiB (\`wc -c < source.zip\`): a larger one fails the whole release. Leave large media and generated files out of it; if it is still larger, skip this upload and leave \`sourceUploadId\` out of the second call, and the site is released without its source. Upload it:`, `   ${curlPut('source.zip', s, { 'content-type': 'application/zip' })}`, ...(s.expiresAt && s.expiresAt !== urls.expiresAt
+            ? [`   This URL expires at ${s.expiresAt}.`]
+            : []), ...(s.headRevisionId
+            ? [
+                `   The repository's head revision is ${s.headRevisionId}. The second call passes \`expectedHeadRevisionId\`: this head for a project started here; if you downloaded the project from the repository, the revision you downloaded it at instead, so a commit made since is never dropped.`
+            ]
+            : []));
+    }
+    else {
+        lines.push('', "2. The site's repository takes no source this time: the project's source is not uploaded, and the second call carries no `sourceUploadId`.");
+    }
+    if (given.releaseNotes)
+        secondCall.releaseNotes = releaseNotesForService(given.releaseNotes);
+    lines.push('', `3. Call UploadHeadlessWebsiteFiles again with ${JSON.stringify(secondCall)} (plus \`calledStartDeployWebsite\`, \`agentIdentity\`, \`reason\`). No \`files\` or \`attachments\` on that call.`);
+    if (secondCall.sourceUploadId) {
+        const withoutSource = { ...secondCall };
+        delete withoutSource.sourceUploadId;
+        lines.push(`   If you skipped the source upload in step 2, call with ${JSON.stringify(withoutSource)} instead: a \`sourceUploadId\` whose zip was never uploaded fails the release.`);
+    }
+    return lines.join('\n');
+}
+/** The release-bundle reply, for both the two-call form and a build uploaded as files. */
+export function formatBundleReleaseResult(siteId, r, notes = []) {
+    return [
+        'Released; the site is live.',
+        `Live URL: ${r.siteUrl ?? '(not returned)'}`,
+        `metaSiteId: ${siteId} — pass it as \`siteId\` to release this site again, the same way. The URL stays.`,
+        `Dashboard: https://manage.wix.com/dashboard/${siteId}`,
+        `Deployment ${r.deploymentId ?? '(id not returned)'}.${r.revision?.id ? ` Source stored as revision ${r.revision.id}.` : ''}`,
+        ...notes,
+        '',
+        'This release replaced whatever the site served before, at the same URL. A change to the site is a change to the project: edit, build if it is an Astro project, upload again.',
+        "Give the user both links, each on its own line and named for what it is: the live site, and the site's dashboard."
     ].join('\n');
 }
+const startOver = (retry) => retry === 'prepare'
+    ? "call with `prepare: true` and the zip's `size` again, upload the zips to the new URLs, and release with the new `uploadKey`"
+    : 'call this tool again with the same files';
+const apiBody = (err) => err.response.data ? ` (${err.response.data.slice(0, 300)})` : '';
+/**
+ * The permission every owner route (drop, the upload URL, the release, the files helpers)
+ * checks on the caller for the site. A 403 naming it is about the login, not the upload: the
+ * connected Wix account is not the one that owns the site, or its role there is too low.
+ */
+export const SITE_ACCESS_PERMISSION = 'OAUTH_APP.APP_CREATE';
+/**
+ * A 403 for the site itself, as the agent should act on it; null for any other error.
+ * `stagedKey` is the uploadKey of a build already PUT when the refusal came from the
+ * release: that upload is kept, and counts against the site's unreleased uploads.
+ */
+export function describeSiteAccessDenied(err, siteId, stagedKey) {
+    if (!(err instanceof WixFetchError) ||
+        err.status !== 403 ||
+        !err.response.data.includes(SITE_ACCESS_PERMISSION)) {
+        return null;
+    }
+    const site = siteId ? `site ${siteId}` : 'this site';
+    const outcome = stagedKey
+        ? `Nothing was released; the build you uploaded is still staged under uploadKey ${stagedKey} and counts against the site's unreleased uploads, so do not call \`prepare\` again and do not send the files again. The same call fails the same way until the login changes; once connected as the owning account, release that staged upload by calling with \`uploadKey: "${stagedKey}"\` before preparing a new one.`
+        : 'Nothing was uploaded, and the same call fails the same way, so do not retry and do not stage another upload.';
+    return `The connected Wix login has no rights on ${site}: Wix refused it the \`${SITE_ACCESS_PERMISSION}\` permission there. That means the site belongs to another Wix account, or this login's role on the owning account is too low (a Basic Team Member cannot upload). ${outcome} Ask the user which Wix account owns the site. Reconnecting Wix helps only if they pick that account, as its owner or an admin, at the consent screen; otherwise the owner has to give this login a higher role on the account, or move the site to it.${apiBody(err)}`;
+}
+/** The bundle-upload-url route's errors, as the agent should act on them. */
+export function describeBundleUploadUrlError(err, siteId) {
+    if (!(err instanceof WixFetchError)) {
+        return err instanceof Error ? err.message : String(err);
+    }
+    const denied = describeSiteAccessDenied(err, siteId);
+    if (denied)
+        return denied;
+    const body = apiBody(err);
+    switch (err.status) {
+        case 400:
+            return `The upload URL was refused: \`size\` is the build zip's length in bytes, an integer from 1 to ${MAX_BUNDLE_BYTES} (100 MB). A larger build: leave out what the site does not serve (source maps, unused assets).${body}`;
+        case 429:
+            return `Too many unreleased uploads are waiting for this site: release one with its \`uploadKey\`, or wait for a running release to finish, then ask again.${body}`;
+        default:
+            return err.message;
+    }
+}
+/**
+ * The site token, repeated in the release body: a build whose server code is over the
+ * service's gRPC limit is deployed over REST as the caller, the way the CLI deploys, and
+ * the gateway does not hand the Authorization header on to the service.
+ */
+function deployAuthorization(siteHeaders) {
+    const authorization = siteHeaders.Authorization ?? siteHeaders.authorization;
+    return authorization ? { deployAuthorization: authorization } : {};
+}
+/** The deployment label the service keeps is 200 characters; longer notes are cut, not refused. */
+export const RELEASE_NOTES_MAX_CHARS = 200;
+export function releaseNotesForService(notes) {
+    // Code points, not UTF-16 units, so an emoji at the boundary stays whole.
+    const chars = [...notes.replace(/\s+/g, ' ').trim()];
+    return chars.length <= RELEASE_NOTES_MAX_CHARS
+        ? chars.join('')
+        : `${chars
+            .slice(0, RELEASE_NOTES_MAX_CHARS - 1)
+            .join('')
+            .trimEnd()}…`;
+}
+/** The release-bundle route's errors, as the agent should act on them. */
+export function describeBundleReleaseError(err, uploadKey, retry = 'prepare', siteId) {
+    if (!(err instanceof WixFetchError)) {
+        return err instanceof Error ? err.message : String(err);
+    }
+    const denied = describeSiteAccessDenied(err, siteId, uploadKey);
+    if (denied)
+        return denied;
+    const body = apiBody(err);
+    const code = err.response.data ?? '';
+    const sameCall = `calling with \`uploadKey: "${uploadKey}"\`${retry === 'resend' ? ' (plus the `expectedHeadRevisionId` and `releaseNotes` you passed, if any; the source is stored with the next release)' : ' and the same ids and `releaseNotes`'}`;
+    // A staged zip is deleted once its release succeeds, and the source it stored moves the
+    // repository's head: after a dropped connection, a 404 or a 409 on the same key is the first
+    // release having gone through.
+    const afterDrop = 'If an earlier call with this `uploadKey` ended in a dropped connection, that release went through: the site is live with this build, so do not upload it again.';
+    // The gateway lost the connection or timed out (its own body, not the service's JSON) while
+    // the release ran on. The service usually completes it.
+    if (err.status >= 502 &&
+        err.status <= 504 &&
+        !code.includes('RELEASE_NOT_HELD') &&
+        !code.includes('{')) {
+        return `The connection to Wix dropped while the release ran (HTTP ${err.status}); the release most likely went through. Do not call \`prepare\` again and do not send the files again. Wait two minutes, then check once by ${sameCall}: an answer that nothing is staged for this key, or that the repository moved, means the first release went through and the site is live. Any other answer is about the release itself.${body}`;
+    }
+    switch (err.status) {
+        case 404:
+            return `Nothing uploaded for uploadKey ${uploadKey}: the build zip was not PUT to its URL, the URL expired, or a release of it already went through (a staged zip is deleted once released). ${afterDrop} Otherwise, to try again, ${startOver(retry)}.${body}`;
+        case 409:
+            return `The project's source repository moved since the upload URLs were made; nothing was released by this call. ${afterDrop} Otherwise: ${retry === 'prepare' ? "call with `prepare: true` and the zip's `size` again, re-upload the source zip to the new URL, and release with the new `uploadKey`, `sourceUploadId` and `expectedHeadRevisionId`." : 'download the project again from the repository, carry your change over, and upload with `expectedHeadRevisionId` set to the revision you downloaded.'}${body}`;
+        case 403:
+            return `Wix refused to deploy this build onto the site's project; nothing was released, and the same call will be refused again. Do not call \`prepare\` again. Tell the user the release is blocked on Wix's side and give them the request id from the error.${body}`;
+        case 413:
+        case 428:
+            return `The build's server code is larger than the release can carry from here; nothing was released. Do not call \`prepare\` again. Tell the user the release is blocked on Wix's side and give them the request id from the error.${body}`;
+        case 400:
+            if (code.includes('EXPECTED_HEAD_REQUIRED')) {
+                return `The site's repository already holds work, and the source replaces only what you started from; nothing was released. ${retry === 'prepare' ? "Call with `prepare: true` and the zip's `size` again and pass the `headRevisionId` it returns as `expectedHeadRevisionId` (with its new `uploadKey` and `sourceUploadId`)." : 'Call again with `expectedHeadRevisionId`: the revision you downloaded the project at, so the source replaces only that. To replace the repository with this upload on purpose, pass its current head.'}${body}`;
+            }
+            if (code.includes('BUNDLE_TOO_LARGE')) {
+                return `The build zip is over ${MAX_BUNDLE_BYTES} bytes (100 MB): leave out what the site does not serve (source maps, unused assets), then ${startOver(retry)}.${body}`;
+            }
+            if (code.includes('INVALID_RELEASE')) {
+                return `The release was refused by Wix's deployment service; nothing was released. The staged upload is kept: call again with the same \`uploadKey\` and the field the message names fixed (release notes are cut to ${RELEASE_NOTES_MAX_CHARS} characters here).${body}`;
+            }
+            if (code.includes('INVALID_UPLOAD_KEY')) {
+                return `\`uploadKey\` is the lowercase UUID the \`prepare\` call returned; pass it as it came.${body}`;
+            }
+            return `The uploaded zip was not accepted. Zip \`dist/\` and \`.wix/build-metadata.json\` from the project root after \`astro build\` with the Wix hosting adapter, then ${startOver(retry)}. A static site goes in \`files\` or \`attachments\` instead, or is dropped as the StartDeployWebsite recipe shows.${body}`;
+        default:
+            if (err.status >= 500) {
+                const what = code.includes('RELEASE_NOT_HELD')
+                    ? 'The release could not hold its upload'
+                    : `Wix's release step failed on its side (HTTP ${err.status})`;
+                // The two-call form's zips are the agent's own, so they can be over the limits the
+                // service reports only as a 500; the one-call form's upload is capped below them.
+                const limits = retry === 'prepare' && !code.includes('RELEASE_NOT_HELD')
+                    ? ` A build over Wix's limits fails here with no reason given: more than ${MAX_RELEASE_STATIC_FILES} files in its client folder (\`find dist/client -type f | wc -l\`), or a source zip over 64 MiB (\`wc -c < source.zip\`). If either is over, a retry fails the same way: make the build or the source zip smaller, then call with \`prepare: true\` again.`
+                    : '';
+                // Both forms retry the staged upload itself: the two-call form with its uploadKey, the
+                // one-call form by switching to that key instead of sending the files again, which would
+                // stage another upload. One retry, then the user hears the request id.
+                return `${what}; nothing was released.${limits} The staged upload is kept under uploadKey ${uploadKey}, so do not call \`prepare\` again${limits ? ' for the same zips' : ''} and do not send the files again: every upload staged and not released counts against the site, which refuses new ones after a few. Retry once, after a minute, by ${sameCall}. If that fails too, stop and tell the user the release is blocked on Wix's side, with the request id from the error.${body}`;
+            }
+            return err.message;
+    }
+}
+/** The inputs of the two-call form against each other and against the one-call form. */
+function validateBundleArgs(a) {
+    const hasContent = !!a.files?.trim() || !!(a.attachments && a.attachments.length);
+    if (a.prepare) {
+        if (hasContent || a.uploadKey || a.sourceUploadId) {
+            return '`prepare: true` goes with `siteId` and `size`: no `files`, `attachments`, `uploadKey` or `sourceUploadId` on that call. Example: {siteId, prepare: true, size}, then {siteId, uploadKey, sourceUploadId?, expectedHeadRevisionId?, releaseNotes?}.';
+        }
+        if (a.size === undefined) {
+            return "`prepare: true` needs `size`: zip the build first and pass the zip's length in bytes (`wc -c < build.zip`).";
+        }
+        if (!Number.isInteger(a.size) || a.size < 1 || a.size > MAX_BUNDLE_BYTES) {
+            return `\`size\` is the build zip's length in bytes, an integer from 1 to ${MAX_BUNDLE_BYTES} (100 MB); got ${a.size}.`;
+        }
+        return null;
+    }
+    if (a.size !== undefined) {
+        return '`size` goes only with `prepare: true`: it is the length of the build zip that call makes an upload URL for.';
+    }
+    if (a.uploadKey) {
+        if (hasContent) {
+            return '`uploadKey` releases a build zip already uploaded to its URL: pass no `files` or `attachments` with it.';
+        }
+        return null;
+    }
+    if (a.sourceUploadId) {
+        return '`sourceUploadId` goes with the `uploadKey` the `prepare` call returned.';
+    }
+    if (a.expectedHeadRevisionId && !hasContent) {
+        return '`expectedHeadRevisionId` goes with `uploadKey`, or with `files`/`attachments` holding a build.';
+    }
+    return null;
+}
 async function readJson(res, what) {
     const text = await res.text();
     if (!res.ok)
@@ -67,6 +360,63 @@ async function readJson(res, what) {
         throw new Error(`${what} returned a non-JSON body: ${text.slice(0, 200)}`);
     }
 }
+/** A PUT to a presigned URL; content-length is left to fetch, which sends the body's own length. */
+async function putZip(fetchImpl, put, bytes, what) {
+    const headers = Object.fromEntries(Object.entries(put.headers ?? { 'content-type': 'application/zip' }).filter(([k]) => k.toLowerCase() !== 'content-length'));
+    const res = await fetchImpl(put.putUrl, {
+        method: 'PUT',
+        headers,
+        body: bytes
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`The ${what} upload was refused (${res.status}${text ? `: ${text.slice(0, 200)}` : ''}); call this tool again with the same files.`);
+    }
+}
+/**
+ * A build that came as files, released over the bundle routes: an upload URL for the
+ * site zip's size, the zip PUT there, the source zip PUT to the repository's URL when
+ * the service offered one and the upload holds source files, then the release with
+ * the ids. `onStaged` hears the uploadKey once the site zip is staged.
+ */
+export async function releaseBuildByUrl(o) {
+    const log = o.log ?? (() => { });
+    const headers = { ...o.siteHeaders, 'Content-Type': 'application/json' };
+    const urls = (await readJson(await o.fetchImpl(`${HEADLESS_BUSINESS}/${o.siteId}/bundle-upload-url`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ size: o.siteZip.byteLength })
+    }), 'bundle-upload-url'));
+    if (!urls.uploadKey || !urls.putUrl) {
+        throw new Error('bundle-upload-url returned no uploadKey or putUrl.');
+    }
+    await putZip(o.fetchImpl, urls, o.siteZip, 'site zip');
+    o.onStaged?.(urls.uploadKey);
+    log(`staged ${urls.uploadKey} (${o.siteZip.byteLength} bytes), source ${urls.source ? `offered, ${o.sourceFiles.length} file(s)` : 'not offered'}`);
+    const source = urls.source && o.sourceFiles.length > 0 ? urls.source : undefined;
+    if (source) {
+        await putZip(o.fetchImpl, source, zipStored(o.sourceFiles), 'source zip');
+    }
+    return (await readJson(await o.fetchImpl(`${HEADLESS_BUSINESS}/${o.siteId}/release-bundle`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+            uploadKey: urls.uploadKey,
+            ...deployAuthorization(o.siteHeaders),
+            ...(o.releaseNotes
+                ? { releaseNotes: releaseNotesForService(o.releaseNotes) }
+                : {}),
+            ...(source
+                ? {
+                    sourceUploadId: source.uploadId,
+                    ...(o.expectedHeadRevisionId
+                        ? { expectedHeadRevisionId: o.expectedHeadRevisionId }
+                        : {})
+                }
+                : {})
+        })
+    }), 'release-bundle'));
+}
 function errorResult(message) {
     return {
         isError: true,
@@ -84,6 +434,12 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
         server.clientName?.() ??
         server.server?.getClientVersion?.()?.name;
     const fetchImpl = options.fetchImpl ?? ((u, i) => fetch(u, i));
+    const guideFetch = options.guideFetch ??
+        (async (httpClient) => {
+            if (!httpClient)
+                return undefined;
+            return fetchArticleContent(httpClient, HEADLESS_GUIDE_URL, 'article', true, options.guide?.skillsPortalUrl, options.guide?.repo, options.guide?.commitHash);
+        });
     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, {
@@ -97,6 +453,16 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
         }))
             .optional()
             .describe(d.attachments),
+        prepare: z.boolean().optional().describe(d.prepare),
+        size: z.number().int().optional().describe(d.size),
+        uploadKey: z.string().min(1).optional().describe(d.uploadKey),
+        sourceUploadId: z.string().min(1).optional().describe(d.sourceUploadId),
+        expectedHeadRevisionId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe(d.expectedHeadRevisionId),
+        releaseNotes: z.string().optional().describe(d.releaseNotes),
         siteId: z
             .string()
             .uuid('siteId must be a Wix metaSiteId (UUID)')
@@ -110,25 +476,187 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
     // 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}"`);
+        const { files, attachments, prepare, size, uploadKey, sourceUploadId, expectedHeadRevisionId, releaseNotes, siteId, calledStartDeployWebsite, agentIdentity, reason } = rawArgs;
+        const phase = prepare
+            ? 'prepare'
+            : uploadKey
+                ? 'release-bundle'
+                : 'files';
+        logger.log(`[UploadHeadlessWebsiteFiles] siteId=${siteId} phase=${phase} calledStartDeployWebsite=${calledStartDeployWebsite} agent="${redactPersonalData(agentIdentity)}" files=${files?.length ?? 0} chars attachments=${attachments?.length ?? 0} reason="${redactPersonalData(reason)}"`);
+        const invalid = validateBundleArgs(rawArgs);
+        if (invalid)
+            return errorResult(invalid);
+        if (prepare || uploadKey) {
+            // The two-call form: both routes take the site token (outside the try so
+            // UnauthorizedError reaches the wrapper).
+            const siteHeaders = await authStrategy.getSiteAuthHeaders(siteId);
+            const headers = {
+                ...siteHeaders,
+                'Content-Type': 'application/json'
+            };
+            try {
+                extra?.setToolBiParams?.({ siteId });
+                if (prepare) {
+                    const urls = (await readJson(await fetchImpl(`${HEADLESS_BUSINESS}/${siteId}/bundle-upload-url`, {
+                        method: 'POST',
+                        headers,
+                        body: JSON.stringify({ size })
+                    }), 'bundle-upload-url'));
+                    if (!urls.uploadKey || !urls.putUrl) {
+                        throw new Error('bundle-upload-url returned no uploadKey or putUrl.');
+                    }
+                    extra?.setToolBiParams?.({
+                        siteId,
+                        upload: { path: 'prepare', sourceOffered: Boolean(urls.source) }
+                    });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: formatPrepareResult(siteId, urls, size, {
+                                    expectedHeadRevisionId,
+                                    releaseNotes
+                                })
+                            }
+                        ]
+                    };
+                }
+                const released = (await readJson(await fetchImpl(`${HEADLESS_BUSINESS}/${siteId}/release-bundle`, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({
+                        uploadKey,
+                        ...deployAuthorization(siteHeaders),
+                        ...(sourceUploadId ? { sourceUploadId } : {}),
+                        ...(expectedHeadRevisionId ? { expectedHeadRevisionId } : {}),
+                        ...(releaseNotes
+                            ? { releaseNotes: releaseNotesForService(releaseNotes) }
+                            : {})
+                    })
+                }), 'release-bundle'));
+                extra?.setToolBiParams?.({
+                    siteId,
+                    upload: {
+                        path: 'release-bundle',
+                        sourceStored: Boolean(released.revision?.id)
+                    }
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: formatBundleReleaseResult(siteId, released)
+                        }
+                    ]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.log(`[UploadHeadlessWebsiteFiles] ${phase} error: ${message}`);
+                rethrowIfUnauthorized(err);
+                await authStrategy.enforceValidWixToken?.(err);
+                return errorResult(uploadKey
+                    ? describeBundleReleaseError(err, uploadKey, 'prepare', siteId)
+                    : describeBundleUploadUrlError(err, siteId));
+            }
+        }
         if (!files?.trim() && !(attachments && attachments.length)) {
-            return errorResult('Nothing to publish: pass the site in `files` (text bundle) or `attachments` (files from this chat or your sandbox).');
+            return errorResult('Nothing to publish: pass the site in `files` (text bundle) or `attachments` (files from this chat or your sandbox), or, for a Wix Astro build from a shell that reaches the internet, zip it and call with `prepare: true` and its `size`.');
         }
-        // 1. Gather bytes: bundle + resolved attachments. All agent-facing errors.
-        let siteFiles;
+        // 1. Gather bytes: bundle + resolved attachments, zips unpacked. A Wix Astro build
+        //    among them is released (below); anything else is a static site and is dropped.
+        //    All agent-facing errors.
+        let siteFiles = [];
+        let uploaded = [];
+        let given = [];
+        let build = null;
         try {
             const fromAttachments = (await resolveAttachments(attachments, fetchImpl)).map((a) => ({ path: a.path, bytes: base64ToBytes(a.content) }));
-            siteFiles = await normalizeSiteFiles([
-                ...parseFileBundle(files),
-                ...fromAttachments
-            ]);
+            given = [...parseFileBundle(files), ...fromAttachments];
+            uploaded = await expandSiteFiles(given);
+            build = findHeadlessBuild(uploaded);
+            if (!build)
+                siteFiles = staticSiteFiles(uploaded);
         }
         catch (e) {
             if (e instanceof AttachmentError || e instanceof Error)
                 return errorResult(e.message);
             throw e;
         }
+        if (!build && expectedHeadRevisionId) {
+            return errorResult("`expectedHeadRevisionId` applies to a Wix Astro build, whose source is stored in the site's repository; these files are a static site, which has none. Call again without it.");
+        }
+        if (build) {
+            // 2. Site auth (outside the try so UnauthorizedError reaches the wrapper).
+            const siteHeaders = await authStrategy.getSiteAuthHeaders(siteId);
+            let stagedKey;
+            try {
+                extra?.setToolBiParams?.({ siteId });
+                // 3. The bundle routes, as the two-call form runs them, from here. The hosting
+                //    refuses an empty static file, so a build with one is zipped again without it.
+                const sourceFiles = buildSourceFiles(uploaded, build);
+                const statics = withoutEmptyStatics(uploaded, build);
+                const released = await releaseBuildByUrl({
+                    siteId,
+                    // One zip as given goes as is; anything else is zipped from the expanded files.
+                    siteZip: given.length === 1 &&
+                        isZip(given[0]) &&
+                        statics.dropped.length === 0
+                        ? given[0].bytes
+                        : zipStored(statics.files),
+                    sourceFiles,
+                    expectedHeadRevisionId,
+                    releaseNotes,
+                    siteHeaders,
+                    fetchImpl,
+                    onStaged: (key) => {
+                        stagedKey = key;
+                    },
+                    log: (line) => logger.log(`[UploadHeadlessWebsiteFiles] release ${line}`)
+                });
+                const sourceStored = Boolean(released.revision?.id);
+                extra?.setToolBiParams?.({
+                    siteId,
+                    upload: {
+                        path: 'build',
+                        sourceStored,
+                        sourceFiles: sourceFiles.length,
+                        emptyStaticsDropped: statics.dropped.length
+                    }
+                });
+                const notes = [
+                    ...(statics.dropped.length
+                        ? [
+                            `Left out, empty: ${statics.dropped.slice(0, 20).join(', ')} (the hosting serves no file of size 0).`
+                        ]
+                        : []),
+                    ...(sourceStored
+                        ? []
+                        : [
+                            sourceFiles.length
+                                ? "The project's source was not stored: the site's repository took none this time."
+                                : "The project's source was not stored: the upload held only the build. A later chat can continue this site only from its source; next time zip the whole project from its root, leaving out node_modules, .env files and the caches."
+                        ])
+                ];
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: formatBundleReleaseResult(siteId, released, notes)
+                        }
+                    ]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.log(`[UploadHeadlessWebsiteFiles] release error: ${message}`);
+                rethrowIfUnauthorized(err);
+                await authStrategy.enforceValidWixToken?.(err);
+                return errorResult(stagedKey
+                    ? describeBundleReleaseError(err, stagedKey, 'resend', siteId)
+                    : describeBundleUploadUrlError(err, siteId));
+            }
+        }
         // 2. Account auth (outside the try so UnauthorizedError reaches the wrapper).
         const authHeaders = await authStrategy.getAccountAuthHeaders();
         try {
@@ -140,6 +668,19 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
                 headers: { ...authHeaders }, // fetch sets the multipart boundary itself
                 body: buildFormData(siteFiles)
             }), 'drop');
+            extra?.setToolBiParams?.({
+                siteId: metaSiteId,
+                upload: { path: 'drop', files: siteFiles.length }
+            });
+            // The headless guide rides along, inline: a static drop is not the build of a site
+            // that needs Wix business features, and the agent that stops here has read nothing else.
+            let guide;
+            try {
+                guide = await guideFetch(extra?.httpClient);
+            }
+            catch (e) {
+                logger.log(`[UploadHeadlessWebsiteFiles] guide fetch failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
             return {
                 content: [
                     {
@@ -149,7 +690,11 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
                             siteUrl: dropped.siteUrl,
                             uploadId: dropped.uploadId,
                             files: siteFiles.map((f) => f.path)
-                        })
+                        }) +
+                            (releaseNotes
+                                ? '\n\nRelease notes are kept for a Wix Astro build only; a static drop has none, so yours were not stored.'
+                                : '') +
+                            formatInlineGuide(guide)
                     }
                 ]
             };
@@ -159,7 +704,7 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
             logger.log(`[UploadHeadlessWebsiteFiles] Error: ${message}`);
             rethrowIfUnauthorized(err);
             await authStrategy.enforceValidWixToken?.(err);
-            return errorResult(message);
+            return errorResult(describeSiteAccessDenied(err, siteId) ?? message);
         }
     });
     // ChatGPT resolves `attachments` into download URLs only for params listed