Setting the skill. One moment.
Skills
Skill 21 of 48
Routes RePlatform source-to-Wix migrations to the next workflow step by inspecting migration project artifacts.
24 minutes · 5,229 words · 19 sections
Install
npx skills add wix/skills --skill replatformnpx skills add wix/skills/plugin marketplace add wix/skillsThe first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.
Guide the user or agent to the next migration step by inspecting the active migration
project (default migrations/<project>/; see CONVENTIONS.md for REPLATFORM_MIGRATIONS_DIR).
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/<project>/ 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.
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.
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:
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).
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:
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.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.
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:
unmuteSiteNotifications (rp-target-wix) and confirm muted: false via
getSiteMuteState;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.
Use a tone that is:
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.
Keep interaction narrow and task-directed.
Allowed interactions:
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.
rp-execute-import → Execution plan & user acceptance.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.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=true or DRY_RUN=true, rp-import-codegen must also write
. 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 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.Resolve <migrations-root> 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 <migrations-root>/<project>/ using this order:
<migrations-root>/<project>/.<migrations-root>/, use it.Look for these artifacts first:
config/wix.envorchestration/run.jsonorchestration/checkpoints.jsonorchestration/decisions.jsonorchestration/approvals.jsonconfig/source.<platform>.env once the source platform is knownsource-profile.mdsource-schema.jsondiscovery/run.jsondiscovery/entities/index.jsonmapping/mapping-plan.jsonmapping/review/mapping-summary.mdsetup/setup-plan.jsonsetup/setup-requirements.jsonsetup/setup-verification.jsonexecution/execution-manifest.jsonexecution/review/code-safety-review.mdexecution/completion-report.jsonexecution/review/import-plan.mdsrc/setup/, src/extract/, src/import/execution-log.mdReuse 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/<other-project>/ 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.
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/<project>/config/.
Use .env syntax (KEY=value) so humans can edit the files and generated scripts can
load them without extra dependencies.
Treat these as secret-bearing files once they may contain real user values:
migrations/<project>/config/wix.envmigrations/<project>/config/source.<platform>.envRules:
cat, broad
sed, head, tail, broad globs) after they may be populated.present / blank / missing.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)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:
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:
If config/wix.env is missing, create it with empty keys, the requested dry-run mode,
and safe mode enabled:
WIX_SITE_STRATEGY=
WIX_SITE_ID=
WIX_AUTH_TOKEN=
DRY_RUN=false
SAFE_MODE=true
SAFE_MODE_PHONE_NUMBER=+972 50 0000000Safe 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.
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.
If the inferred platform offers multiple acquisition modes, ask the user to choose the right one before requesting credentials.
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).config/source.<platform>.env with empty keys and ask for missing required values one
at a time.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.Never print secret values back to the user. It is fine to say a required secret is present or missing.
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/<project>/ 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:
npm create @wix/new@latest -- headless \
--business-name "<Brand Name>" \
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:
curl -s -H "Authorization: Bearer $WIX_AUTH_TOKEN" -H "wix-site-id: $WIX_SITE_ID" \
https://www.wixapis.com/stores/v3/provision/versioncatalogVersion 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.
wix-headlessRun 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:
WIX_SITE_ID blank.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.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.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.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.
orchestration/ plus phase artifacts (Step 2) and routes to the first
material gap. No work is repeated unnecessarily.migrations/<project>/ directory and
re-run from discovery. Do not partially wipe individual stages.Route according to the first material gap by consulting the matching internal resource
under resources/:
config/wix.env and, after source platform is known, config/source.<platform>.env;
ask the user for missing details one at a time.deliveryMode and WIX_SITE_STRATEGY, defaulting deliveryMode=management unless the
user explicitly asked for a storefront or frontend.orchestration/preflight.json.resources/rp-discovery/.resources/rp-mapper/.mapping/review/mapping-summary.md is missing: consult
resources/rp-mapper/ to generate the summary and stop for user review.mapping/review/mapping-summary.md, ask the user to review it, and wait for acceptance before
continuing.resources/rp-setup-discovery/.resources/rp-import-codegen/.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.resources/rp-execute-setup/.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.Respond minimally with:
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.
The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.
main, last pushed 24 September 2026.SKILL.md, not by matching a directory convention. 8 distinct layouts observed: .claude/skills/*/SKILL.md, skills/*/SKILL.md, skills/wix-headless-fast/*/skill.md, skills/wix-headless/*/skill.md, skills/wix-replatform/resources/*/SKILL.md, wix-headless-replatform/resources/*/SKILL.md, */SKILL.md, wix-replatform/resources/*/SKILL.md.h1 and no skipped levels:.claude-plugin/marketplace.json by Wix, declaring 1 plugin. It is read for editorial metadata only — never as the skill index, which is always the repository tree./wix/skills.md, and each skill at its own .md URL.20 files · 123 KB
Everything this skill ships beside its prose. All of it is set here, as subchapters of skill 21.
Executable code the skill can run.
execution/review/code-safety-review.mdsafeModeOptionsmapping/review/mapping-plan.md, mapping/review/mapping-summary.md,
setup/setup-verification.json, execution-log.md).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.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.sourceId -> targetId crosswalk under
migrations/<project>/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.migrations/<project>/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.Shopify Admin API vs public storefront data only.public content only
vs also include private/authenticated data.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.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)”).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.
existing, ask for WIX_SITE_ID later when it is the next
missing Wix detail.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.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.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 migrations/<project>/scripts/mint-token.shToken shape: OauthNG.JWS.<base64>.<base64>.<sig> — a single line on stdout with no JSON
wrapper. Send it as a Bearer token (Authorization: Bearer <token>, plus
wix-site-id: <siteId>). 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.
Everything else published alongside the skill.