@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-manage/references/sites/upload-static-site.md

@@ -1,6 +1,6 @@
 ---
 name: "Upload a Website or HTML Files"
-description: Publish HTML, CSS, JavaScript or a static build as a Wix Headless website; inspect its deployed files and edit them on the same site and URL. Covers file and ZIP uploads, selective additions, replacements and deletions while preserving other files, full-site replacement, authenticated and anonymous publishing, verification, and connecting a Wix business backend. Use for files the user supplies or pages you create for them. Not for migrating a live site from another platform by URL or CSV (use Site Import), embedding code in an editor-built Wix site, or uploading assets to Media Manager.
+description: Publish HTML, CSS, JavaScript or a static build as a Wix Headless website; inspect its deployed files and edit them on the same site and URL. Covers file and ZIP uploads, selective additions, replacements and deletions while preserving other files, full-site replacement, authenticated and anonymous publishing, verification, and connecting a Wix business backend; a Wix Astro build is released as a server-rendered site rather than dropped. Use for files the user supplies or pages you create for them. Not for migrating a live site from another platform by URL or CSV (use Site Import), embedding code in an editor-built Wix site, or uploading assets to Media Manager.
 ---
 
 # Upload a Website or HTML Files
@@ -16,6 +16,7 @@ site and are not atomic against another editor.
 | Request | Flow |
 | --- | --- |
 | Publish files as a new site | [Choose an upload route](#before-the-calls), [create once](#create-the-site), upload, [verify](#verify-and-report). |
+| Publish a Wix Astro build | [Create once](#create-the-site) for a new site, then [release it](#release-a-wix-astro-build); it is not dropped. |
 | Inspect or edit a deployed site | [Find its ID](#find-an-existing-site), then [list, read or patch](#change-it-later). Do not create another site. |
 | Replace the entire deployed frontend | Confirm replacement of the serving frontend, then drop the complete intended file set on the same ID. |
 | Make a shop, bookings, forms or other business controls work | [Connect a backend](#connect-a-backend) on the same site. A static upload alone does not make them functional. |
@@ -28,7 +29,8 @@ to inspect files authorizes no writes. Do not create from a template: that
 creates an empty site rather than publishing the supplied files.
 
 Quick reference: [upload through MCP](#drop-through-the-wix-mcp) ·
-[upload with curl](#drop-with-curl) · [list/read](#list-and-read) ·
+[upload with curl](#drop-with-curl) ·
+[release an Astro build](#release-a-wix-astro-build) · [list/read](#list-and-read) ·
 [patch](#patch-files) · [ZIP fallback](#download-edit-drop-fallback) ·
 [images](#images) · [limits/errors](#limits-and-failures).
 
@@ -56,6 +58,18 @@ Build projects that need dependencies first, and upload only their static
 output. If your environment cannot build the project, ask for the build output.
 For a Wix business project, follow [Connect a backend](#connect-a-backend).
 
+### Static pages or a Wix Astro build
+
+| What you have | How it goes live |
+| --- | --- |
+| Static pages: HTML, CSS, JS, images, or a static build's output | **Dropped**, by every route in this recipe. |
+| A Wix Astro build: `.wix/build-metadata.json` beside `dist/`, written by `astro build` with the Wix hosting adapter | **Released** as a server-rendered site, by `UploadHeadlessWebsiteFiles` only: [release a Wix Astro build](#release-a-wix-astro-build). Never dropped. |
+
+A build's `dist/client/` dropped as static pages loses its server pages, and a
+drop or patch on a site whose live release is a build replaces the build with
+static files; nothing on the server stops that. [Change it later](#change-it-later)
+tells the two apart before any edit.
+
 The JavaScript examples below run in `ExecuteWixAPI`, not directly in a shell
 or browser. Without MCP, use the curl examples and edit downloaded files locally;
 `wix.request`, `wix.multipart` and `wix.headless.files` are sandbox utilities,
@@ -91,14 +105,14 @@ when available for Wix skill/docs URLs, with web fetch as fallback.
 ## Create the site
 
 Create only for a new site. Use the page title, at most 40 characters. Keep
-`origin: 'drop'`, empty `seedOptions`, and both synchronous steps:
+`origin: 'agent'` and both synchronous steps:
 
 ```javascript
 async function run() {
   return wix.request({ scope: 'account', method: 'POST',
     url: 'https://www.wixapis.com/headless-business-setup/v1/headless-business/provision',
-    body: { origin: 'drop',
-      newMetasite: { namingStrategy: { metaSiteName: 'Northwind Studio' }, seedOptions: [] },
+    body: { origin: 'agent',
+      newMetasite: { namingStrategy: { metaSiteName: 'Northwind Studio' } },
       synchronousSteps: ['SET_METASITE_NAME', 'CONFIGURE_HEADLESS_APP'] }
   });
 }
@@ -110,7 +124,7 @@ The shell equivalent:
 ```bash
 curl -sS -X POST "https://www.wixapis.com/headless-business-setup/v1/headless-business/provision" \
   -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
-  -d '{"origin":"drop","newMetasite":{"namingStrategy":{"metaSiteName":"Northwind Studio"},"seedOptions":[]},"synchronousSteps":["SET_METASITE_NAME","CONFIGURE_HEADLESS_APP"]}'
+  -d '{"origin":"agent","newMetasite":{"namingStrategy":{"metaSiteName":"Northwind Studio"}},"synchronousSteps":["SET_METASITE_NAME","CONFIGURE_HEADLESS_APP"]}'
 ```
 
 ## Drop through the Wix MCP
@@ -167,6 +181,49 @@ curl -sS -X POST \
 A single ZIP part also works: it is unpacked server-side with one wrapping
 folder stripped. `siteUrl` is the final address.
 
+## Release a Wix Astro build
+
+This recipe releases a build you have. Making one is the Wix Headless kit's run
+(`https://www.wix.com/skills/headless-cold-start/headless-kit.md`), which states
+its own requirements: Node, a reachable npm registry, the project's install. A
+sandbox with no network cannot make one.
+
+**Who releases from here:** the build has to reach `UploadHeadlessWebsiteFiles`,
+by one of two carriers. Check before starting, measured rather than assumed:
+
+| Carrier | Check |
+| --- | --- |
+| Attachments | Your client passes `attachments` as files (a local path swapped for a download URL when the call is made). The tool's `attachments` description names the clients that do; a client that is not named, or that shows no way to pass a file, has no attachment carrier, whatever its shell can do. |
+| A shell that reaches the internet | `curl -sI -m 25 https://s3.amazonaws.com` answers with S3's own headers: `x-amz-request-id`, and `Server: AmazonS3` unless a proxy in front rewrote the Server header to its own name. The upload URLs are on Amazon S3; a sandbox limited to a few hosts gets a proxy's refusal instead, an HTTP answer with neither header. A sandbox proxy can take ten seconds to answer. |
+
+With neither, no build is released from here. For a new site, publish static
+pages instead. For a site already released as a build, report that it cannot be
+changed from this environment, and change nothing.
+
+A build goes through `UploadHeadlessWebsiteFiles` and nothing else: no drop
+route takes it. The site stays the same, at the same URL, now server-rendered.
+
+- **Attached:** zip the project from its root after `astro build`, leaving out
+  `node_modules`, `.env*` and caches, and pass the ZIP as `attachments`. The
+  tool releases the build and stores the rest as the project's source in the
+  site's Code Store repository, where a later session continues from. A ZIP of
+  only `.wix/` and `dist/` releases too, storing no source.
+- **From a shell, without attachments:** two calls. `{ siteId, prepare: true, size }`
+  with the ZIP's `size` (`wc -c < build.zip`) answers with `curl` commands for
+  the build ZIP and, when the site's repository takes it, a source ZIP; run them
+  as given, then make the second call it names, with `uploadKey`. A 404 on the
+  second call means the upload URL expired: prepare again. A prepared upload is
+  finished by that second call and by nothing else: a release made another way
+  (the ZIP attached, say) leaves the prepared upload behind and releases without
+  its source, so a prepare that failed on the way is prepared again, not replaced
+  by another carrier.
+
+`expectedHeadRevisionId` is the repository revision the project started from:
+the `headRevisionId` the prepare returned for a project made in this run, or
+the `revision.id` it was [downloaded at](#a-site-released-as-a-wix-astro-build).
+`EXPECTED_HEAD_REQUIRED` or a 409 means the repository holds newer work:
+download it, carry the change over, and release again.
+
 ## Find an existing site
 
 Reuse the ID from the earlier upload. If only a name or URL is known, query the
@@ -192,7 +249,66 @@ Unclaimed anonymous sites instead use their saved ID and
 
 ## Change it later
 
-Use the same site ID and URL. With `ExecuteWixAPI`, prefer its file helpers
+Use the same site ID and URL. The file helpers and the ZIP fallback below edit
+static pages: they read the site's last drop and drop the result. A site whose
+live release is a Wix Astro build is changed in its project instead; a drop or
+patch there replaces the build with static files, and the server does not stop
+it. So first tell what is live.
+
+When this conversation published the site, or the user says how it was made,
+you know. Otherwise one read-only call tells, in `ExecuteWixAPI`:
+
+```javascript
+async function run() {
+  return wix.request({ scope: 'account', method: 'GET',
+    url: 'https://www.wixapis.com/headless-business-setup/v1/headless-business/META_SITE_ID/files' });
+}
+// 200 { revision, files: [{ path, size }] }: the live site is its last static drop
+```
+
+| Answer | What is live | Do |
+| --- | --- | --- |
+| `200` | Its last static drop | [Edit the static pages](#a-site-of-static-pages). |
+| `409 LIVE_SITE_CHANGED` | A release replaced the last drop: a Wix Astro build | [Change the project](#a-site-released-as-a-wix-astro-build). No drop, no patch. |
+| `404 SITE_CODE_NOT_FOUND` | Nothing was ever dropped | Open the live URL. Pages there mean a build released without a drop: change the project. Nothing there means an empty site: drop as for a new one. |
+
+### A site released as a Wix Astro build
+
+The project lives in the site's Code Store repository, which is the managed
+project whose id is the site's app id: `appId` in `wix.config.json`, or the
+companion app. In `ExecuteWixAPI`, in site scope:
+
+```javascript
+async function run() {
+  const siteId = 'META_SITE_ID';
+  const app = await wix.request({ scope: 'site', siteId, method: 'POST',
+    url: 'https://manage.wix.com/_api/companion-apps/v1/companion-apps/get-or-create', body: {} });
+  const appId = app.data.companionApp.id;
+  try {
+    const dl = await wix.request({ scope: 'site', siteId, method: 'POST',
+      url: `https://www.wixapis.com/codestore/v2/git-code-store-projects/${appId}/generate-download-url`, body: {} });
+    return { appId, downloadUrl: dl.data.downloadUrl, revision: dl.data.revision };
+  } catch (e) {
+    return { appId, repository: false, error: String(e.message).slice(0, 200) };
+  }
+}
+```
+
+- **A download URL:** from a shell, `curl -o project.zip "<downloadUrl>"` (the
+  URL is signed and lasts 5 minutes; `ExecuteWixAPI` cannot fetch it), unpack,
+  `npm ci`, make the change, `npx astro build`, and
+  [release the build](#release-a-wix-astro-build) with `revision.id` as
+  `expectedHeadRevisionId`. The download holds the project without
+  `node_modules` or `.env*` files. Without a shell that can build, report that
+  the site is a server-rendered project and change nothing.
+- **A 404 (`NOT_FOUND`, `GIT_BRANCH_NOT_FOUND`), or a repository whose root
+  holds `index.html` rather than a project:** the project's source was not
+  stored with the release. The site can be changed only from the project where
+  it was built; report that, and change nothing here.
+
+### A site of static pages
+
+With `ExecuteWixAPI`, prefer its file helpers
 for selective edits, not `UploadHeadlessWebsiteFiles`: sending only changed
 files to that upload tool would remove omitted files. Without MCP, go directly
 to the [ZIP fallback](#download-edit-drop-fallback).
@@ -466,12 +582,15 @@ Wix MCP.
   `index.html` or `index.htm`.
 - 20 MB per file and site; `UploadHeadlessWebsiteFiles` limits each call
   to 10 MB. Patch also limits the final snapshot to 2,000 files.
-- Drop serves static files, not unbuilt project source.
+- Drop serves static files, not unbuilt project source. A Wix Astro build is
+  [released](#release-a-wix-astro-build), not dropped.
 
 | Failure | Action |
 | --- | --- |
 | `400` with `MISSING_INDEX_HTML`, `FILE_TOO_LARGE`, `TOTAL_TOO_LARGE` | Read `details.applicationError.code` and fix the files. |
 | Drop `403 PERMISSION_DENIED` | Check token freshness and access to this site. An unclaimed anonymous site requires upload/release, not drop. |
+| `409 LIVE_SITE_CHANGED` from the files endpoint or a patch | The live site is a Wix Astro build, not its last drop: [change the project](#a-site-released-as-a-wix-astro-build). Do not drop. |
+| Release `400 EXPECTED_HEAD_REQUIRED` / `409` | The repository holds newer work than the project started from: download it, carry the change over, release again. |
 | Drop/upload `500` | Inspect current state before retrying once; retain the request ID if it fails again and offer the drop page. Hand-built malformed multipart can also cause this: use `wix.multipart`. |
 | Anonymous `404` | The hour expired or the site was claimed; do not create a replacement without explaining. |
 

package/skills/wix-manage/references/stores/update-product-with-options.md

@@ -1,6 +1,6 @@
 ---
 name: "Update Product with Options (Catalog V3)"
-description: "Start here for existing Catalog V3 product updates, including digital products that fail at add-to-cart with ITEM_NOT_FOUND_IN_CATALOG. Includes name lookup, Get Product, and PATCH in one flow, plus importing a supplied PDF and attaching it to the existing variant. Covers options, variant prices and SKUs, product visibility (hide/unhide through `visible`, never delete), description edits that preserve Rich Content, and revision-based updates. Read another recipe only for a field or operation this flow does not cover."
+description: "Start here for existing Catalog V3 product updates, including digital products that fail at add-to-cart with ITEM_NOT_FOUND_IN_CATALOG. Includes name lookup, Get Product, and PATCH in one flow, plus importing a supplied PDF and attaching it to the existing variant. Covers options, variant prices and SKUs, variant shipping weight in the site's weight unit, product visibility (hide/unhide through `visible`, never delete), description edits that preserve Rich Content, and revision-based updates. Read another recipe only for a field or operation this flow does not cover."
 ---
 **RECIPE**: Business Recipe - Updating a Wix Store Product (Catalog V3)
 
@@ -156,7 +156,7 @@ For prepend, append, and text removal, execute the documented calls directly: th
 | Get Product | `GET https://www.wixapis.com/stores/v3/products/{productId}?fields=DESCRIPTION` | `product.id`, `product.revision`, and the full `product.description`. |
 | Update Product | `PATCH https://www.wixapis.com/stores/v3/products/{productId}` with `{ product: { id, revision, description }, fields: ["DESCRIPTION"] }`, using the read ID/revision and complete edited document. | `product.description` verifies the edit; `product.revision` is the new revision. |
 
-The request-level `fields` array projects response data; it is separate from `search.search.fields`, which selects the fields searched. A description-only PATCH needs only the three product fields shown above; variant, option, price, and physical-property fields belong to other update flows.
+The request-level `fields` array projects response data; it is separate from `search.search.fields`, which selects the fields searched. A description-only PATCH needs only the three product fields shown above. Variant, option, and price changes use [Prepare a Price or SKU Update](#prepare-a-price-or-sku-update); shipping weight uses [Set Shipping Weight](#set-shipping-weight).
 
 Use a single read-modify-write operation: locate the product, read its description and revision, make the requested change in memory, then PATCH once and verify the response.
 
@@ -510,6 +510,61 @@ const skuPatchBody = { product: variantPatchProduct };
 
 Send the selected body to `PATCH https://www.wixapis.com/stores/v3/products/{productId}` in the same ExecuteWixAPI invocation as the name lookup and Get Product. Its response is `{ product: { id, revision, variantsInfo: { variants } } }`; verify the changed variant by its retained ID and confirm from that response. These examples provide the request fields and response paths for price and SKU changes; proceed directly after reading this recipe. Discover further schemas only for fields not covered here or a documented call that fails.
 
+### Set Shipping Weight
+
+Shipping weight belongs to the variant: `variantsInfo.variants[].physicalProperties.weight`, a number in the site's weight unit. The unit is a site-wide, read-only setting at `product.physicalProperties.weightMeasurementUnitInfo.weightMeasurementUnit` (`KG` or `LB`). Get Product returns it only when `fields` includes `WEIGHT_MEASUREMENT_UNIT_INFO`; the default read omits it.
+
+1. Use the name lookup above, then Get Product with the preparation read plus the unit: `GET https://www.wixapis.com/stores/v3/products/{productId}?fields=WEIGHT_MEASUREMENT_UNIT_INFO&fields=VARIANT_OPTION_CHOICE_NAMES&fields=MERCHANT_DATA&fields=PRODUCT_CHOICES_MEDIA_REFERENCES&fields=PRODUCT_CHOICES_DISPLAY_IMAGE`.
+2. Convert the requested value to the returned unit in code, in either direction (1 kg = 2.20462262 lb). A value given without a unit is already in the site's unit.
+3. Build `variantPatchProduct` as in **Prepare a Price or SKU Update**, select the target variants, and set `physicalProperties.weight` only on them. A named choice (`Size = Large`) selects exactly one variant, as in the SKU example; if it matches none or several, ask the user. Set every variant only when the product has one variant or the user asked for all of them; otherwise ask which variant they mean. The other variants stay in the body unchanged.
+4. Send the PATCH with top-level `fields: ["WEIGHT_MEASUREMENT_UNIT_INFO"]`, in the same execution as the lookup and read. Do not send `product.physicalProperties`: product-level `physicalProperties` is accepted on create (see [Create Product (Catalog V3)](create-product-catalog-v3.md)) but not on update, where the unit cannot be changed and a PATCH that carries it is rejected with `400 productType cannot be provided with any these fields: physical_properties`.
+5. Confirm from the PATCH response: `product.variantsInfo.variants[].physicalProperties.weight` on the retained variant IDs, and the unit at `product.physicalProperties.weightMeasurementUnitInfo.weightMeasurementUnit`. Report both value and unit to the user, for example "0.5 kg (stored as 1.1023 lb, the store's unit)".
+
+```javascript
+const unit = getResponse.product.physicalProperties.weightMeasurementUnitInfo.weightMeasurementUnit;
+const requested = { value: 0.5, unit: "KG" }; // requested weight and its unit ("KG" or "LB")
+const factor = requested.unit === unit ? 1 : unit === "LB" ? 2.20462262 : 1 / 2.20462262;
+const weight = Number((requested.value * factor).toFixed(4));
+const choice = { optionName: "Size", choiceName: "Large" }; // null when the user named no variant
+const allVariants = false; // true when the user asked for every variant
+const targets = choice
+  ? variants.filter(variant => variant.choices.some(c =>
+      c.optionChoiceNames.optionName === choice.optionName && c.optionChoiceNames.choiceName === choice.choiceName))
+  : variants;
+if (choice && targets.length !== 1) throw new Error("Clarify which variant should receive the weight");
+if (!choice && !allVariants && variants.length !== 1) throw new Error("Clarify whether every variant should receive the weight");
+for (const variant of targets) variant.physicalProperties = { ...variant.physicalProperties, weight };
+const weightPatchBody = { product: variantPatchProduct, fields: ["WEIGHT_MEASUREMENT_UNIT_INFO"] };
+```
+
+Set `choice` to `null` and `allVariants` to `true` when the user asked for every variant. Send `weightPatchBody`, not a body rebuilt by hand: each variant in `variants` still carries its SKU, barcode, visibility and cost, which a PATCH without them drops.
+
+For a simple product (one variant, no options) on a `KG` site whose variant has no SKU, barcode, cost or other state yet, the request is:
+
+```bash
+curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: <AUTH>" \
+  -d '{
+    "product": {
+      "id": "{productId}",
+      "revision": "{currentRevision}",
+      "options": [],
+      "variantsInfo": {
+        "variants": [{
+          "id": "{existingVariantId}",
+          "choices": [],
+          "price": { "actualPrice": { "amount": "{existingPrice}" } },
+          "physicalProperties": { "weight": 0.5 }
+        }]
+      }
+    },
+    "fields": ["WEIGHT_MEASUREMENT_UNIT_INFO"]
+  }'
+```
+
+The response returns `product.variantsInfo.variants[0].physicalProperties.weight: 0.5` and `product.physicalProperties.weightMeasurementUnitInfo.weightMeasurementUnit: "KG"`, which confirm the stored weight and its unit.
+
 ### Update Variant Price Only
 
 Read `{existingVariantId}` off the Get Product response; a Search or Query Products result does not carry it. The curl below is for a single-variant product without options. For an optioned product, use the complete options/variants body in **Prepare a Price or SKU Update**.
@@ -607,6 +662,7 @@ Copy any other writable variant fields from the read product using the preparati
 | `price must not be empty` | A variant was sent without a price — including an existing variant rebuilt from only its `id` and the field being changed | Carry `price.actualPrice.amount` on every variant you send, not just new ones; copy it from the Get Product response for variants you are not repricing |
 | `variantsInfo is invalid: variants has size 0, expected 1 or more` | Variants were read from a Search or Query Products response, which does not return them | Re-read the product with Get Product and send its `variantsInfo.variants` |
 | `Missing option choices` or `INVALID_DEFAULT_VARIANT` | Product has options but at least one variant has no matching choices | Rebuild `variantsInfo.variants` so every variant includes choices for all product options |
+| `productType cannot be provided with any these fields: physical_properties` | Sent `product.physicalProperties`, for example to set the weight unit | Leave it out; weight goes on `variantsInfo.variants[].physicalProperties.weight` — see [Set Shipping Weight](#set-shipping-weight) |
 | `DIGITAL_PRODUCT_CANNOT_BE_VISIBLE_IN_POS` | Sent `visibleInPos: true` on a digital product | Digital products can't be visible in POS; leave `visibleInPos` out of the body |
 | `ITEM_NOT_FOUND_IN_CATALOG` at add-to-cart, product exists | A `DIGITAL` variant has no `digitalProperties.digitalFile` | Attach a file — see [Attach a Digital File](#attach-a-digital-file) |
 | `exceeds available inventory` at add-to-cart, product exists | The variant has no stock (`DIGITAL` products included) | Update its stock through the Inventory API; inventory is separate from an Update Product PATCH |

package/skills/wix-replatform/.publish-manifest.json

@@ -1,8 +1,8 @@
 {
-  "bundle": "replatform",
-  "version": "1.2.0",
+  "bundle": "wix-replatform",
+  "version": "2.2.3",
   "sourceRepo": "wix-private/replatform",
-  "sourcePath": "skills/",
-  "sourceCommit": "9aaaebd",
-  "publishedAt": "2026-08-05T13:55:48Z"
+  "sourcePath": "skills/wix-replatform/",
+  "sourceCommit": "6bde03f",
+  "publishedAt": "2026-10-22T22:14:10Z"
 }

package/skills/wix-replatform/CLI.md

@@ -0,0 +1,162 @@
+# RePlatform CLI
+
+`replatform` is the non-interactive process supervisor for a RePlatform migration. It starts
+an installed coding agent, gives it the active migration project, observes durable migration
+artifacts, and exposes run control from another terminal.
+
+It is **not** a second migration engine. The installed `wix-replatform` skill still chooses
+the next stage and performs migration work; existing receipts remain the only proof of
+completion. The CLI provides the outer lifecycle: start, observe, answer human checkpoints,
+cancel, and resume.
+
+## Start here
+
+From the repository during development:
+
+```bash
+yarn replatform --help
+yarn replatform run <project> --agent codex
+```
+
+From an installed bundle:
+
+```bash
+node <bundle>/scripts/replatform.js --help
+```
+
+The CLI never prompts for stdin, opens an editor or pager, or begins a vendor login flow.
+Required human work becomes a durable request that can be inspected and continued later.
+
+## Common lifecycle
+
+```bash
+# Start and receive normalized JSONL events (the default).
+replatform run migrations/example --agent codex
+
+# Check a live or completed run from another terminal.
+replatform status <project-or-run-id>
+replatform tail <project-or-run-id> --follow
+
+# Read the persisted work plan, active task, and agent topology.
+replatform tasks <project-or-run-id> --format json
+
+# Read the identity currently authenticated in the local Wix CLI before a destination action.
+replatform account
+
+# Read a required human action, then provide the permitted response.
+replatform requests <project-or-run-id>
+replatform show <project-or-run-id> <request-id>
+replatform answer --project <project> --request-id <request-id> --choice approved --continue
+
+# A manual action has no approval choice. Complete the stated prerequisite first, then
+# acknowledge it; the resumed stage verifies the prerequisite itself.
+replatform answer --project <project> --request-id <request-id> --acknowledge --continue
+
+# Stop only a supervisor that owns an active run, preserving migration recovery artifacts.
+replatform cancel <project-or-run-id>
+```
+
+## Output and liveness
+
+`run`, `resume`, and `answer --continue` default to `--format jsonl`. The first event carries
+the run ID and the final event has `type: "result"`. Use `--format json` for exactly one final
+result object, or `--format text` for a concise human result. `--format event-stream` is an
+alias for `jsonl`.
+
+When a run needs a person, its `user_action_requested` event carries the full safe action
+summary: why it is needed (`message` and `userAction.prompt`), response mode, permitted choices,
+and reviewable artifacts. A JSONL consumer can therefore render the decision without reading a
+project file; `show` remains available for the complete durable request or artifact contents.
+
+Foreground runs emit a truthful liveness heartbeat every `60s` when no newer observable
+progress exists. Detached runs default to no heartbeat. Set `--status-interval off` to disable
+foreground heartbeats, or choose a value from `10s` to `5m`. `--events-file <path>` mirrors
+normalized JSONL events to a file.
+
+## Human checkpoints
+
+`requests` lists every pending action with its response mode and a copyable next command.
+
+- `choice` accepts only one declared `--choice` value.
+- `choice` and a manual `--acknowledge` also accept an optional `--note` to record the
+  operator's context without changing the selected decision or acknowledgement.
+- `text` accepts `--text` or `--text-file`.
+- `none` is a manual prerequisite. Run the stated external action, then use
+  `--acknowledge`; this records the operator statement but does not replace deterministic
+  verification by the resumed migration stage.
+
+Some declared choices carry a narrowly scoped durable effect. For example, choosing
+`switch_to_standard` after a quick-import preflight changes `managementImportMode` to `standard`
+before `--continue` resumes. The event and result include that request's choices; the CLI never
+infers an effect from a label alone.
+
+`show` can display the action itself or an explicitly reviewable artifact. It never exposes
+arbitrary project files. If it truncates a large artifact, it prints the exact emitted and total
+byte counts.
+
+## Source and delivery choices
+
+`run --help` describes every supported value. In brief:
+
+- `--source-mode public_content` reads public pages and content.
+- `authenticated_api` uses standard source API access.
+- `private_data` requires protected source credentials.
+- `files_only` imports supplied `--file` paths.
+- `--delivery-mode management` migrates backend data; `website` migrates the frontend only;
+  `management_and_website` performs both.
+- `--management-import-mode standard` uses the full discovery and mapping flow; `quick` uses a
+  bounded public adapter and plan.
+- `--site-type headless|studio|harmony` chooses the type of a new destination site (with
+  `--destination new`). Headless is a website developed in code; Studio and Harmony are
+  websites designed in a Wix editor. There is no default: without it, a new-site run raises a
+  durable site-type request before anything is created. The type cannot be changed later.
+- `--site-business-type store|bookings|other` is valid only with `--site-type harmony`. It
+  records the business context for the run; it does not change how the site is created:
+  Harmony always starts from the blank template (Harmony site generation is not used).
+- Before the first Studio or Harmony site is created, a request shows the account the Wix CLI
+  is logged into and the site name; nothing is created until that account is confirmed.
+- Destination recovery requests (uncertain creation, editor or publication checks) are
+  answered like any other request; an answer only triggers one new bounded check, never a
+  second site. RePlatform never publishes or unpublishes an Editor site.
+
+## Safety and recovery
+
+Every run writes a run ID before it launches an agent. A run is not complete because an agent
+said so: aggregate completion receipts must validate. Cancellation is a durable state change;
+it requests graceful shutdown before forced termination, never labels a partial import as
+completed, and preserves recovery artifacts for a later `replatform resume`.
+
+Run `replatform doctor` to check available adapters and local prerequisites without printing
+credentials.
+
+`replatform account` reports the identity returned by the local `wix whoami` command. It is a
+live check, not a migration artifact: confirm that identity is authorized before acknowledging a
+destination-creation action.
+
+## Local browser console
+
+`replatform-console` is an optional loopback-only browser control surface for this CLI:
+
+```bash
+node <bundle>/scripts/replatform-console.js
+```
+
+It prints a tokenized `127.0.0.1` URL. Keep that URL private: its token authorizes local
+control requests. The console starts the same non-interactive CLI commands, renders the
+persisted work state alongside the normalized event stream, presents durable human actions, and reads only artifacts that `show`
+already permits. It never accepts credentials or exposes vendor diagnostics. `--port <port>`
+chooses a port; the server refuses any non-loopback host.
+
+The Work panel reads `state/runner/task-state.json` through `replatform tasks`, so it survives
+console reloads and restarts. It records router work and direct agent processes; extra workers
+appear only when an adapter reports their structured topology. The observed activity feed remains
+diagnostic evidence and never marks work complete by itself.
+
+For destination-creation acknowledgements, the console also displays the identity reported by
+the local Wix CLI and requires that check to succeed before it enables acknowledgement. The
+identity is shown only in the token-protected dialog and is never saved to migration artifacts.
+
+For reconnectable consumers, `tail --since <event-id>` replays events strictly after that
+event. `tail --since <duration>` uses an inclusive time window. `show --format json` returns
+the declared artifact media type plus `cursor`/`nextCursor` byte offsets for bounded reads, and
+`projects --format json` lists valid migration projects under the configured migrations root.

package/skills/wix-replatform/README.md

@@ -0,0 +1,52 @@
+# wix-replatform
+
+`wix-replatform` is a migration skill for moving business data from another platform into
+Wix.
+
+Its public entrypoint is `wix-replatform`. The bundled internal resources handle the workflow
+stages behind that entrypoint.
+
+## Quick start
+
+Install the skill:
+
+```bash
+npx skills add wix/skills/skills/wix-replatform
+```
+
+Or install it globally:
+
+```bash
+npx skills add wix/skills/skills/wix-replatform -g
+```
+
+Then, in your agent:
+
+1. Invoke `wix-replatform`.
+2. If you want the migration to run end to end with grouped intake and no routine
+   checkpoint pauses, invoke it as `wix-replatform in 1-click mode`.
+3. Provide the source site URL and any required destination/source-access details.
+4. Follow the routed workflow through discovery, mapping, setup, code generation, and import.
+5. Choose whether the run is backend-only (`management`) or backend + storefront
+   (`website`).
+6. After setup discovery, the skill writes `website/handoff.json` even for backend-only
+   runs. In `website` mode it also asks for a late `websiteScope` decision so the
+   storefront skill can start with suggested scopes based on the discovered content. In
+   `1-click mode`, it picks the deterministic default instead of pausing.
+7. If the delivery mode is `website`, continue into the frontend phase through the
+   migration project's `website/handoff.json` package.
+
+If the user explicitly asks for `1-click mode`, the skill should gather any missing
+required inputs up front once, record `automationMode=one_click` with `source: "user"`, record routine
+mapping/execution approvals as `approved` with `decidedBy: "agent"`, create a demo
+member for blog import when needed, and continue through the frontend phase as well when
+`deliveryMode=management_and_website` (or user input `both`). `deliveryMode=website` is
+frontend-only.
+
+For CSV, explicit user-requested 1-click also accepts a passing sample preview as the agent
+and continues without routine questions. Without that explicit user-authored decision, CSV
+keeps its normal mapping review, sample-preview validation, and execution-plan approval
+pauses. File upload alone never implies 1-click.
+
+Migration artifacts are written to a local project directory such as `migrations/<project>/`.
+They are not written back into the skill package.