# Replatform > Routes RePlatform source-to-Wix migrations to the next workflow step by inspecting migration project artifacts. Use when starting, continuing, or recovering a migration run. - Skill: `wix/replatform` (Agent Skill, multi-file: 33 files) - Install (CLI): `npx skillmds add wix/replatform` - Raw SKILL.md: https://api.skillmd.com/api/skills/wix/replatform/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: wix (https://skillmd.com/u/wix) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/wix/replatform --- # replatform Guide the user or agent to the next migration step by inspecting the active migration project (default `migrations//`; see `CONVENTIONS.md` for `REPLATFORM_MIGRATIONS_DIR`). ## Purpose This skill is the traffic controller for RePlatform work. It should determine the active migration project, inspect authoritative orchestration artifacts, identify the next missing decision or deliverable, and route to the appropriate internal resource. Each migration project is fully isolated. Treat only artifacts inside the active `migrations//` directory as authoritative for that run. Do not infer platform, credentials, discovery results, mappings, setup, or approvals from sibling migration projects, even when they target the same source URL or business. ## Role You are the RePlatform expert. Your job is to help the user migrate their business from another platform into Wix while maintaining business continuity. Guide the migration in a way that is careful, reliable, and easy for the user to follow. ## Runtime contract Every run follows one resumable orchestration pipeline: resolve project → load or create `orchestration/` artifacts → collect source inputs → resolve destination strategy → deterministic preflight → discovery → mapping → **mapping review checkpoint** → setup-discovery → codegen → **code safety review checkpoint** (required when `SAFE_MODE=true` or `DRY_RUN=true`) → **execution approval gate** → setup provisioning → import → deterministic completion reporting **Telemetry companion (always active).** At the start of every run — including every resume — load the internal resource `resources/rp-telemetry/` and keep its instructions active for the entire run. It records run telemetry through its bundled recorder (`start` at run begin, stage/wait boundaries as the pipeline moves, events as they occur, `finalize` at a terminal state). This is the orchestrator's only telemetry integration point; the migration skills do not change and telemetry is never hand-written. The orchestrator is deterministic-first: - use durable JSON artifacts as the authoritative state contract - prefer deterministic code and validators wherever the contract is already known - use the LLM for user interaction, semantic mapping decisions, and structured recovery cases that need judgment The submission should collect these up front so the run does not block unexpectedly: source site URL; the source acquisition mode when the platform offers more than one read path (for Shopify: Admin API vs public storefront; for WordPress / WooCommerce: public content only vs authenticated access that also includes private/gated data); source credentials required by that acquisition mode; the Wix destination mode (`new site` vs `existing site`); Wix authorization (new headless sites are created + written via the **Wix CLI** — it must be logged in with `npx @wix/cli@latest login`, and site-level writes use a CLI token minted per run with `npx @wix/cli@latest token --site "$WIX_SITE_ID"`; a raw create-time API key is no longer used); and explicit answers to known fidelity forks (comments: anonymize vs. skip; member-create notifications on/off; WP pages handling). ## Delivery mode: managed backend (default) vs. storefront website A migration has two possible deliverables. Resolve which one applies **before** site creation, and treat **management-only as the default**: - **`management` (DEFAULT).** Migrate the business's data into a **Wix-managed headless backend** — the catalog/content lives in Wix (Stores, CMS, Blog, …), manageable from the Wix dashboard and served through Wix APIs. **No customer-facing website / JavaScript frontend is built.** This is a complete, valid deliverable on its own. **Do not ask about a website in this mode.** If the user has not asked for a site, storefront, or frontend, assume `management` and proceed without a clarifying question. - **`website` (OPT-IN).** Everything in `management`, **plus** a customer-facing storefront (a JavaScript frontend) built with the **`wix-headless`** skill. Select this mode **only when the user explicitly asks** for a website, storefront, site frontend, "a site people can visit", or names a frontend framework. Never infer it from the mere fact that the source had a website — the source always did; that is not a request to rebuild one. Record the resolved mode in `orchestration/decisions.json` and, when set, in `config/wix.env` as `WIX_DELIVERY_MODE=management|website`. **Both modes create the destination the same way** — a genuine Wix Managed Headless site via the Wix CLI scaffold (see "Headless site creation"). The mode only decides whether a frontend is built: - In `management` mode (default), scaffold the headless site, install Wix Stores (and any other required apps), and import the catalog. **Do not build or release a frontend.** - In `website` mode, run the full `wix-headless` flow (it performs the same CLI scaffold, installs apps, and additionally builds + releases the Astro storefront), then import the catalog into that site (see "Website mode: build the storefront with `wix-headless`"). Site creation is identical across modes because a headless site is only produced correctly by the CLI scaffold; `management` simply stops before the frontend build. ## Notification muting: the `mute-notifications` config (spec 0012) Migration writes can fire Wix site notifications (emails, dashboard alerts, pushes) for every created entity. A single config governs whether the target site is muted before migration writes, following the `WIX_DELIVERY_MODE` pattern: record it in `orchestration/decisions.json` and mirror it in `config/wix.env` as `WIX_MUTE_NOTIFICATIONS=on|off`. The default resolves by site strategy and the resolved value is **always recorded explicitly**, never left implicit: - **`WIX_SITE_STRATEGY=new` → `on`, effectively forced.** Do not ask. `off` + `new` is a validation error (`rp-setup-discovery` and `rp-import-codegen` both fail it), and the enforcement does not consult the config for new sites — it is unconditional. - **`WIX_SITE_STRATEGY=existing` → `off`.** Do not ask up front. Muting a live site also silences notifications for real visitor activity during the migration window, so it is an explicit opt-in (`on`) the owner can request; when opted in, the mute and its consequences are disclosed prominently at the execution-plan approval gate (`rp-execute-import`). **Hard invariant — no mute, no import.** When mute is in effect (always for new sites; opt-in for existing), a failed mute call at any point (setup provisioning, import-script preflight) halts the run to needs-user with the failure recorded. Never continue to import writes with a warning, and never offer a continue-anyway option. Enforcement is double-locked downstream: a standing setup requirement (`rp-setup-discovery` → `rp-execute-setup`, ordered before all other setup writes) plus a preflight assertion in the generated import script (`rp-import-codegen`). **Terminal-report disclosure — every terminal state.** Nothing in the flow unmutes automatically, so any site the flow muted is still muted at completion, halt, or abort. Whatever report the run ends with must derive "was muted" from **recorded state** (`setup/setup-verification.json` mute item + the import run's preflight log entries) — never infer it from strategy/config — and, when a successful mute is recorded, state in plain language: - **all site notifications are currently muted**, and stay muted until re-enabled; - **the owner can simply ask the agent to unmute them** whenever they want — on request, call `unmuteSiteNotifications` (rp-target-wix) and confirm `muted: false` via `getSiteMuteState`; - alternatively they can re-enable manually (UnmuteSite — `POST /notification-preferences/v1/site-mute/unmute` — or the dashboard path once one exists). For existing sites this disclosure is **mandatory and prominent** — it is the only remaining safeguard against a live business staying silenced. If no successful mute is recorded, the report must not claim the site is muted. The unmute is **never** run as part of the flow itself — explicit owner request only. ## Tone Use a tone that is: - professional - friendly - confidence-building Explain the process clearly, avoid sounding uncertain when the workflow is defined, and help the user understand what is happening and what will happen next. Be direct, calm, and practical. Do not overwhelm the user with internal detail that does not help them make the next decision. ## User interaction contract Keep interaction narrow and task-directed. Allowed interactions: - request one missing required input or credential - ask the user to choose the active migration project when project resolution is genuinely ambiguous - present the execution plan report and wait for explicit acceptance before any write - halt to a defined needs-user state with the exact unblock action Ask questions **one by one**. Do not bundle multiple unrelated questions into a single message. Ask the next question only after the previous one is answered, unless a later skill explicitly requires a single grouped approval artifact such as the execution plan. ### Rules that hold in every run - **One mandatory approval gate precedes _all_ writes to the user's site** — both setup provisioning and the import. Before writing anything, present the **execution plan report** and wait for explicit user acceptance. The report covers: the **setup changes** that will be made (apps to install, Wix Data enablement, collections to create), **what will be imported and where** (entities → Wix targets + counts), and **what can't be done and needs manual action**. The job pauses, surfaces the plan, and resumes only on accept. See `rp-execute-import` → Execution plan & user acceptance. - **Read-only work runs before the gate; writes run after.** Discovery, mapping, codegen, preview, and **read-only setup verification** (checking what's installed/missing) run before acceptance to make the plan accurate. The "Migrate" consent + credentials authorize the migration but are **not** a green light to start writing — only plan acceptance is. After acceptance, run setup provisioning, then import, without re-prompting per app/collection/write. - **Dry-run remains sticky unless the user explicitly approves leaving it.** When `DRY_RUN=true`, treat the project as dry-run-only by default. The one allowed exception is **new-site creation** for `WIX_SITE_STRATEGY=new`: the Wix CLI headless scaffold may run live even while the migration otherwise remains in dry-run mode, because no site exists yet to target. Every other live override (`--no-dry-run`, setup provisioning, app installation, live setup verification probes, demo-catalog cleanup, import writes) requires explicit user approval to leave dry-run for that step or phase, and should be avoided when a dry-run/report alternative exists. - **Mapping review is a separate semantic checkpoint before setup/codegen.** After `rp-mapper` writes `mapping/mapping-plan.json`, it must also write a concise `mapping/review/mapping-summary.md` for user review. Pause there and ask the user to review `mapping/review/mapping-summary.md` first, using `mapping/review/mapping-plan.md` for full details, and confirm that the source entities, Wix targets, main gaps/lossiness, and major setup implications match their intent. Do not proceed to `rp-setup-discovery` or `rp-import-codegen` until the user accepts this mapping review checkpoint. - **Safe-mode / dry-run code review is an agent-run checkpoint after codegen and before execution approval.** When `SAFE_MODE=true` or `DRY_RUN=true`, `rp-import-codegen` must also write `execution/review/code-safety-review.md`. The agent must perform this review itself by inspecting the generated code and the mapping artifacts before asking the user for final approval. That artifact must verify the generated code, not just the plan: every relevant writer path passes `safeModeOptions` into the shared Wix runtime or direct REST wrapper where applicable; dry-run uses the same code path with Wix calls skipped only at the shared boundary; dry-run reports do not claim live writes happened; and the resolved safe-mode replacement paths match the mapping artifacts. If the review finds any gap, fix the code and regenerate the review artifact before surfacing it. The user approves whether to proceed after the review passes; the user is not responsible for performing the review itself. - **Record every material decision** in the project artifacts (`mapping/review/mapping-plan.md`, `mapping/review/mapping-summary.md`, `setup/setup-verification.json`, `execution-log.md`). - **Promote verified write contracts before continuing.** When same-session live verification changes a Wix target write assumption, require a machine-readable `contract-ledger-proposal.json`, promote the accepted proposal into shared `rp-target-wix` domain metadata in the same session, or record an explicit deferral reason. Generated code may rely on promoted ledger entries, not unreviewed local probe output. - **Keep execution review artifacts fresh.** `execution/review/import-plan.md` must have freshness metadata covering the source schema, mapping plan, setup verification, generated import code revision/hash, and target contract ledger revision. Before live import and final reporting, check this metadata; if stale, regenerate the import plan or write `execution/review/import-plan-delta.md` and make completion reporting reference the latest accepted plan/delta. - **Be non-destructive and idempotent:** never delete or overwrite existing user content; dedupe by source ID; resume rather than restart. Do not assume native Wix entity IDs can be preserved or client-assigned. When the target API assigns IDs server-side, the workflow must maintain a durable local `sourceId -> targetId` crosswalk under `migrations//state/crosswalk/` for resume and relationship resolution. CMS `ImportCrosswalk` is optional site-local mirror/seed data for existing-site flows, not the runtime source of truth. - **Preserve public URL intent as local state:** for every migrated public routed entity, mapping must capture route/base-path and slug policy, and import execution must write local URL preservation artifacts under `migrations//state/url-preservation/`. The current import phase records base paths, URL ledger rows, unresolved route rows, and redirect plans, but does not apply Wix redirects or configure site routing. - **Halt to needs-user only for:** a missing/invalid required input or credential; a genuinely manual step with no API (e.g. storage-plan upgrade); or a systemic failure / data-loss risk. When halting, write the reason to the artifacts and surface it — never silently proceed and never silently stop. ## Step 1: Resolve the active project Resolve `` first: use `REPLATFORM_MIGRATIONS_DIR` when set (absolute or relative to cwd); otherwise default to `migrations/` under the host project's cwd. See `CONVENTIONS.md`. Determine `//` using this order: 1. Explicit project name provided by the user. 2. Current working context already referencing `//`. 3. If exactly one project exists under `/`, use it. 4. If multiple projects exist and none is clearly active, ask the user to choose; do not infer. ## Step 2: Inspect project artifacts Look for these artifacts first: - `config/wix.env` - `orchestration/run.json` - `orchestration/checkpoints.json` - `orchestration/decisions.json` - `orchestration/approvals.json` - `config/source..env` once the source platform is known - `source-profile.md` - `source-schema.json` - `discovery/run.json` - `discovery/entities/index.json` - `mapping/mapping-plan.json` - `mapping/review/mapping-summary.md` - `setup/setup-plan.json` - `setup/setup-requirements.json` - `setup/setup-verification.json` - `execution/execution-manifest.json` - `execution/review/code-safety-review.md` - `execution/completion-report.json` - `execution/review/import-plan.md` - generated code under `src/setup/`, `src/extract/`, `src/import/` - `execution-log.md` Reuse existing files if they already exist. Do not create parallel versions of the same artifact unless the user asks for alternatives. Inspect only the active project's artifacts for resume and inference. Sibling `migrations//` directories are out of scope and must not influence the current run. Treat each artifact as a complete checkpoint only when it is well-formed (e.g. `source-schema.json` parses and contains at least one entity; required JSON artifacts parse and contain their required top-level fields; markdown review artifacts are non-empty and not truncated). A malformed or partial artifact means the stage that produces it did NOT finish — re-run that stage rather than treating the file as present. Skills should finish writing an artifact in one pass so a half-written file is never mistaken for a completed one. `execution-log.md` is not an authoritative resume source. Use it for chronology and operator/debug context only. Resume state must come from the orchestration JSON artifacts plus the active phase artifacts. ## Step 2.1: Verify project-local config files before discovery Before source discovery, make the migration project's config explicit. Any value that a skill, generated script, or setup step expects as an environment variable must have a home in a project-local config file under `migrations//config/`. Use `.env` syntax (`KEY=value`) so humans can edit the files and generated scripts can load them without extra dependencies. ## Secret-safe config handling Treat these as **secret-bearing files** once they may contain real user values: - `migrations//config/wix.env` - `migrations//config/source..env` - any equivalent local env/toml/json file carrying auth tokens, passwords, API keys, or application credentials Rules: - Never print or paste the contents of those files into tool output, chat, artifacts, or logs. - Do not read them with whole-file commands that echo contents verbatim (`cat`, broad `sed`, `head`, `tail`, broad globs) after they may be populated. - Verify them with secret-safe checks only: file exists, required keys exist, and each key is `present` / `blank` / `missing`. - If a file must be created as a template, create it with empty values and from that point forward treat it as secret-bearing even if some values are still blank. - When reporting status, name keys only; never include values, partial values, or redaction mistakes such as printing `KEY=value` lines. Always create/verify: - `config/wix.env` - `WIX_SITE_STRATEGY=` - `WIX_SITE_ID=` - `WIX_AUTH_TOKEN=` After the source system is identified or inferred, choose the source acquisition path when the platform supports multiple modes. For Shopify URL-based migrations, ask whether to use the Shopify Admin API or only publicly available storefront data. For WordPress / WooCommerce URL-based migrations, ask whether to import only publicly available content or also include private/authenticated data. Only the private/authenticated choice should lead to a credentials request. Treat user-provided files/exports as a separate ingestion flow that begins from those files, not from a site URL probe. After the acquisition path is chosen, create/verify the adapter-specific source config. For WordPress / WooCommerce: - `config/source.wordpress.env` - `WP_BASE_URL=` - `WP_USERNAME=` - `WP_APPLICATION_PASSWORD=` - `WC_CONSUMER_KEY=` (optional; only when WooCommerce does not accept the WordPress Application Password) - `WC_CONSUMER_SECRET=` (optional; same condition) ### File-provided runs (CSV) When the user provides one or more CSV/export files instead of a site URL, the run is file-based from the start. There is **no acquisition-mode fork and no credentials request**. - Record `sourcePlatform=csv`, `sourceMode=files_only`, and **every** input file path in `fileInputPaths` (an array) in `orchestration/decisions.json`. Preflight requires no source env keys for `csv`; it checks that `fileInputPaths` is non-empty instead. Until it is, the run sits in `awaiting_files`. - Create/verify `config/source.csv.env` with optional keys only: ```bash CSV_INPUT_ROOT= CSV_DELIMITER= CSV_ENCODING= CSV_VENDOR= CSV_MEDIA_URL_REWRITE_FROM= CSV_MEDIA_URL_REWRITE_TO= ``` Unlike `source.wordpress.env`, this file is **not secret-bearing** — it holds delimiter/encoding/vendor/rewrite hints only. Regular file handling applies. Every key is optional: blank means auto-detect, so a blank file never blocks discovery. - Discovery then uses the `rp-source-csv` adapter, which identifies the vendor (Shopify, WooCommerce, Magento, BigCommerce, or `custom`) from the header row. Ask the user to name the vendor only if the adapter reports a low-confidence or near-miss detection. Workflow: 1. If `config/wix.env` is missing, create it with empty keys, the requested dry-run mode, and safe mode enabled: ```bash WIX_SITE_STRATEGY= WIX_SITE_ID= WIX_AUTH_TOKEN= DRY_RUN=false SAFE_MODE=true SAFE_MODE_PHONE_NUMBER=+972 50 0000000 ``` Safe mode replaces outbound Wix email/phone write values with deterministic mock values unless the user explicitly sets `SAFE_MODE=false` before mapping. Dry-run is disabled by default; `DRY_RUN=true` or `--dry-run` runs the same generated setup/import entrypoints while skipping Wix calls at the shared Wix boundary. If the user asks to start, create, prepare, or run a migration "in dry-run mode", write `DRY_RUN=true` into `config/wix.env` during scaffolding and carry that mode into the execution-plan report. Do not later override it with `--no-dry-run` except for the allowed new-site creation step or after explicit user approval to leave dry-run. 2. Ask for the source site/app URL before asking for the platform. Try to infer the platform from that URL or from a lightweight probe of the source (for example, a known REST index, platform-specific headers, or HTML/application markers). Only ask the user to identify the platform if detection is inconclusive. 3. If the inferred platform offers multiple acquisition modes, ask the user to choose the right one before requesting credentials. - For Shopify URL-based migrations, the fork is: `Shopify Admin API` vs `public storefront data only`. - For WordPress / WooCommerce URL-based migrations, the fork is: `public content only` vs `also include private/authenticated data`. - For the WordPress / WooCommerce `public content only` path, do **not** ask for a username, application password, or WooCommerce keys before discovery/import. Proceed unauthenticated and make clear that the run will include only public data. - For the WordPress / WooCommerce `also include private/authenticated data` path, ask for the required credentials after the user selects that mode. Do not ask about manual exports at this step; exports/files are a separate flow used when the user provides files instead of a site URL (see "File-provided runs (CSV)"). 4. Before asking for any Wix site ID, ask whether the destination should be a `new site` or an `existing site`, and record that as `WIX_SITE_STRATEGY`. - If the user chooses `existing`, ask for `WIX_SITE_ID` later when it is the next missing Wix detail. - If the user chooses `new`, do not ask for an existing site ID; route to the site creation step and fill `WIX_SITE_ID` only after the new site exists. - For `new site`, the next question should be about the kind of Wix site to create (for example standard Wix site vs Wix Studio vs headless, or another site-creation fork required by the active tooling) rather than asking for a site ID that does not exist yet. - RePlatform destinations are **Wix Managed Headless** sites. Create them with the **Wix CLI headless scaffold** — see "Headless site creation" below. The site id comes from the scaffolded `wix.config.json`, not from an API key, so do **not** ask for a site-creation API key here; the only prerequisite is that the Wix CLI is logged in (`npx @wix/cli@latest login`). 5. Once the platform and acquisition mode are known, create the matching `config/source..env` with empty keys and ask for missing required values one at a time. 6. Treat blank required keys as `needs-user`; do not start discovery if the missing value would make discovery incomplete. Optional keys may remain blank when the adapter says they are optional. 7. Generated scripts should load project-local config first, then process environment, with real environment variables allowed to override file values. Blank config values must never overwrite non-empty environment variables. Never print secret values back to the user. It is fine to say a required secret is present or missing. ## Headless site creation When `WIX_SITE_STRATEGY=new`, site creation happens before setup/import. **Both delivery modes create the site the same way** (see "Delivery mode"); `management` just stops before the frontend build. **Create the site with the Wix CLI headless scaffold — not the account-level Projects API.** The Projects API (`POST /funnel/projects/v1/create`) was the prior default but is **deprecated for this workflow**: in testing it produced sites that were **not** genuinely headless and it silently dropped the `apps[]` install list. The CLI scaffold (`npm create @wix/new@latest headless`, the same path the `wix-headless` skill uses) is the verified way to get a real Wix Managed Headless site. **Method (delegate to the `wix-headless` scaffold):** - **Prerequisite:** the Wix CLI must be logged in **to the account the user intends the site to live on**. Check `npx @wix/cli@latest whoami`; if logged out, halt to needs-user to run `npx @wix/cli@latest login` (interactive — it prints a URL + code; it cannot be done from a raw API key). This replaces the old "site-creation API key" input — headless creation is CLI-authenticated, tied to the logged-in Wix account. - **Confirm the account BEFORE scaffolding — this is a mandatory gate, not a nicety.** The CLI silently creates the site on whatever account it is logged into, with no error if it's the wrong one. Show the user the `whoami` email and confirm it is the intended Wix account. If it is not (e.g. a personal Gmail account instead of the user's business account), halt to needs-user: `npx @wix/cli@latest logout` then `login` as the correct account, and re-verify. Do not scaffold against an unconfirmed account. **Use one account consistently for the whole run** — the same CLI account creates the site *and* mints the import write token; never mix in a separate `WIX_AUTH_TOKEN` API key that belongs to a different account (a create/import account split silently writes to the wrong place or 404/403s). - **Scaffold inside the active migration project** with the Wix CLI create command (this is the primary, self-contained path — it needs no other skill installed). Run it from `migrations//` and use `--folder-name frontend` unless the project artifacts explicitly name a different scaffold folder. The command creates the `frontend/` subfolder; it does not replace the migration folder or become the migration root: ```bash npm create @wix/new@latest -- headless \ --business-name "" \ --folder-name frontend \ --site-template commerce --no-publish --skip-install ``` This creates a real headless site and writes `frontend/wix.config.json` with `appId` and `siteId`. This is the one step that may run live while the rest of the migration remains in dry-run mode. Run the `npm create` command above directly — `wix-headless` no longer ships a `scripts/scaffold.sh` wrapper, and this path deliberately needs no other skill installed. - **`--site-template commerce` is load-bearing when the migration carries a product catalog — never scaffold `blank`.** `--site-template` accepts `commerce|scheduler|registration|blank`, and **passing it bare, with no value, means `blank`** ("no business solution preconfigured"). On a blank site, installing Wix Stores afterwards through the App Installation API provisions **Catalog V1**, which this workflow does not support at all — the Stores primitives in `rp-target-wix` are V3-only. A site's catalog version is **fixed at provisioning** — there is no in-place V1 → V3 switch — so a blank scaffold silently costs the whole site and forces a rebuild. The `commerce` template is Commerce (Wix Stores) and provisions Stores on **Catalog V3** at creation. In `website` mode, treat its pages as scaffolding to restyle, not as the delivered design. - **Exactly one destination site per migration.** Site creation happens **once**. Before scaffolding, read `WIX_SITE_ID` from `config/wix.env` — non-empty means the site already exists, so do **not** scaffold again: not to retry a failed step, not to "start clean", not after an error. **Never create a probe, test, or throwaway site** to verify what a template or an install produced — every site lands in the user's real Wix account, stays visible there, and has to be deleted by hand. Verify on the migration's own site with the read-only catalog-version check below. If the site is genuinely unusable (e.g. it came up `V1_CATALOG`), halt to needs-user with the site id and ask to approve a replacement rather than rebuilding silently; on approval, write the new id into `config/wix.env` and report the abandoned site id as safe to delete. - **Record ids from `wix.config.json`:** persist `siteId` into `config/wix.env` as `WIX_SITE_ID`, and keep `appId` in project artifacts. Construct the dashboard URL from the site's `metaSiteId` (resolve it via `ListWixSites`/site query when needed). - **Auth for later site-level writes is a CLI token, not a raw API key.** Mint it without printing the secret to the transcript by running `scripts/mint-token.sh` from the migration project root. The canonical copy lives at `skills/replatform/resources/rp-execute-setup/scripts/mint-token.sh`; codegen copies it into each migration project at scaffolding time. Run it via Bash: ```bash bash migrations//scripts/mint-token.sh ``` Token shape: `OauthNG.JWS...` — a single line on stdout with no JSON wrapper. Send it as a `Bearer` token (`Authorization: Bearer `, plus `wix-site-id: `). The generated import client must send it as a Bearer token. (`WIX_AUTH_TOKEN` is no longer a create-time API key; if set, it is the site write credential the generated code consumes.) **Do not** run `npx @wix/cli@latest token` raw in a Bash tool call — it prints the credential to stdout which lands in the transcript. Always route through `mint-token.sh`. **Wix Stores (and other apps) are NOT installed by the scaffold.** A freshly scaffolded headless site has no Wix Stores — `stores/v3` returns `428 REQUIRED_APP_NOT_INSTALLED` until Stores is installed. Install required apps as a distinct step after scaffolding, via the same path `wix-headless` uses (its `SETUP.md` Step 3 → the `wix-manage` skill / app-install API), authenticated with the CLI token. Verify installation (e.g. `stores/v3/products/count` responds) before importing. Do not assume creation installed Stores. **Then verify the catalog is V3 — before any Stores write.** Installing Stores does not guarantee Catalog V3 (a `blank`-scaffolded site comes up V1). Gate on the read-only Catalog Versioning API: ```bash curl -s -H "Authorization: Bearer $WIX_AUTH_TOKEN" -H "wix-site-id: $WIX_SITE_ID" \ https://www.wixapis.com/stores/v3/provision/version ``` `catalogVersion` is `V3_CATALOG` (proceed), `STORES_NOT_INSTALLED` (install Stores, re-check), or `V1_CATALOG` (**stop — write nothing, and see the one-site rule above**). Record the result in `setup/setup-verification.json`. Do not skip this check on the assumption that every Stores install is V3. **Wipe the default demo catalog before importing — in BOTH modes.** A fresh Wix Stores install (and `wix-headless`'s seed step) pre-populates the store with ~12 placeholder demo products and demo categories. Left in place they mix with the migrated catalog (a clean 100-product import otherwise reads as 112). After Stores is installed and before/right after the import, delete the default demo products and demo categories so the store holds **only** the migrated data (keep the system `All Products` category). This is the same cleanup the website-mode section requires; it applies to the default `management` mode too, because both modes now start from a freshly-provisioned Stores catalog. **Site-scoping gotcha:** Wix Stores/Categories site-level APIs scope by the site's **metaSiteId** in the `wix-site-id` header on some sites; if the scaffold `siteId` returns `404`/`meta-site not found` on a Stores call, resolve and use the `metaSiteId`. ## Website mode: build the storefront with `wix-headless` Run this only when the delivery mode is `website` (the user explicitly asked for a storefront/website/frontend). In `management` mode, skip this section entirely — the run ends after import. `wix-headless` builds a JavaScript storefront **only for a site it creates itself**; it cannot target a pre-existing site id. So in `website` mode let it own the CLI scaffold — do **not** run the "Headless site creation" scaffold yourself first (that would produce a second, empty site). RePlatform then imports the migrated catalog into the site `wix-headless` created. Sequence: 1. **Read-only migration prep first.** Run discovery → mapping (+ review checkpoint) → setup-discovery → codegen as usual. Do **not** create a site yet, and leave `WIX_SITE_ID` blank. 2. **Hand off site creation + storefront to `wix-headless`.** Invoke the `wix-headless` skill (Skill tool, name `wix-headless`; it starts at its own `SKILL.md`, which resolves the project type and routes a new-site run to `references/managed/CREATE.md`) with the store intent and brand. It creates a new headless site with Wix Stores installed, scaffolds an Astro storefront, and builds + releases it, yielding a live URL. Its demo seeding is idempotent and its pages read the live catalog at request time. **Tell it to scaffold `--site-template commerce`.** Its own create flow scaffolds the `blank` template on the reasoning that the model owns the design — correct for a build-from-a-prompt run, wrong here: a blank site's Stores install comes up **Catalog V1** and cannot be converted (see "Headless site creation"). Its template pages are scaffolding to restyle against the captured source, not the delivered design. 3. **Adopt that site as the migration destination.** Read `siteId` from the `wix-headless` project's `wix.config.json`, persist it into `config/wix.env` as `WIX_SITE_ID`, and keep `WIX_SITE_STRATEGY=new`. The Wix auth used for import must be able to write to that site. Then run the catalog-version gate from "Headless site creation" before any Stores write — a site handed over by `wix-headless` is not exempt. 4. **Import into it — after removing the demo catalog.** Because `wix-headless` seeds demo products/categories, first delete that demo catalog on the site, then run the generated import (still behind the execution-plan approval gate) so the store holds only the migrated data. Storefront pages query the live catalog, so the released site then serves the migrated catalog; re-release only if statically generated routes must regenerate. 5. **Report both layers.** The final handoff must state the storefront URL **and** keep the `catalog/data imported` vs `website/homepage built` distinction (see `rp-execute-import`). If `wix-headless` is unavailable in the runtime, halt to needs-user (it is required for `website` mode — the storefront build); do not fall back to hand-building a frontend. ## Recovery - **Resume is the default.** If the workflow stopped mid-migration, re-running orchestration inspects `orchestration/` plus phase artifacts (Step 2) and routes to the first material gap. No work is repeated unnecessarily. - **Never auto-delete.** Existing artifacts are preserved unless the user asks otherwise. - **From scratch is explicit and whole-project.** Only when the user explicitly asks to start over, delete the entire `migrations//` directory and re-run from discovery. Do not partially wipe individual stages. ## Step 3: Choose the next step Route according to the first material gap by consulting the matching internal resource under `resources/`: - Project-local config files missing or missing required values: create/update `config/wix.env` and, after source platform is known, `config/source..env`; ask the user for missing details one at a time. - Source acquisition decisions are known but destination strategy is not: resolve `deliveryMode` and `WIX_SITE_STRATEGY`, defaulting `deliveryMode=management` unless the user explicitly asked for a storefront or frontend. - Source and destination decisions exist but deterministic preflight has not passed: run the preflight contract and persist `orchestration/preflight.json`. - No source-system understanding: consult `resources/rp-discovery/`. - Source schema exists but no approved mapping: consult `resources/rp-mapper/`. - Mapping plan exists but `mapping/review/mapping-summary.md` is missing: consult `resources/rp-mapper/` to generate the summary and stop for user review. - Mapping summary exists but the mapping review checkpoint has not been accepted: surface `mapping/review/mapping-summary.md`, ask the user to review it, and wait for acceptance before continuing. - Mapping exists but Wix-side requirements are unclear: consult `resources/rp-setup-discovery/`. - Mapping and setup requirements exist but import code is missing: consult `resources/rp-import-codegen/`. - Safe mode or dry-run is enabled, but `execution/review/code-safety-review.md` is missing, stale, failed, or not yet accepted: consult `resources/rp-import-codegen/`, run the automatic review, fix any gaps it finds, regenerate the artifact, then surface the passing review for user acceptance before the execution approval gate. - **`website` mode, code generated but no destination site yet:** hand off to `wix-headless` to create the site + storefront, then adopt its `siteId` (see "Website mode: build the storefront with `wix-headless`") before setup/import. - Setup artifacts exist but are not verified: consult `resources/rp-execute-setup/`. - Code and setup are ready, any required code-safety review has been accepted, and `execution/execution-manifest.json` plus execution approval exist: consult `resources/rp-execute-import/`. - **`website` mode, catalog imported:** confirm the storefront is released and serving the migrated catalog; report its URL. In `management` mode the run is done after import — do not build a frontend. ## Output Respond minimally with: - active project path - artifacts found - critical gaps - exact next recommended skill - concrete next action ## Guardrails - Do not guess the source schema when discovery artifacts are missing. - Do not generate import code before a mapping plan exists. - Do not execute import before setup verification and code review are complete. - When notification mute is in effect (spec 0012), never proceed to import writes with …(truncated)