replatform
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).
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/<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.
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/<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.
- 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/<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.
- 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 <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:
- Explicit project name provided by the user.
- Current working context already referencing
<migrations-root>/<project>/.
- If exactly one project exists under
<migrations-root>/, use it.
- 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.<platform>.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/<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.
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/<project>/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/<project>/config/wix.env
migrations/<project>/config/source.<platform>.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:
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 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.
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.
- 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)").
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).
- Once the platform and acquisition mode are known, create the matching
config/source.<platform>.env with empty keys and ask for missing required values one
at a time.
- 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.
- 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/<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>" \
--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 migrations/<project>/scripts/mint-token.sh
Token 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.
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/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:
- 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.
- 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.
- 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.
- 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.
- 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/<project>/ 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.<platform>.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)
1---2name: replatform3description: >-4 Routes RePlatform source-to-Wix migrations to the next workflow step by inspecting5 migration project artifacts. Use when starting, continuing, or recovering a migration run.6metadata:7 source: https://skillmd.com/skills/wix/replatform8---910# replatform1112Guide the user or agent to the next migration step by inspecting the active migration13project (default `migrations/<project>/`; see `CONVENTIONS.md` for `REPLATFORM_MIGRATIONS_DIR`).1415## Purpose1617This skill is the traffic controller for RePlatform work. It should determine the active18migration project, inspect authoritative orchestration artifacts, identify the next19missing decision or deliverable, and route to the appropriate internal resource.2021Each migration project is fully isolated. Treat only artifacts inside the active22`migrations/<project>/` directory as authoritative for that run. Do not infer platform,23credentials, discovery results, mappings, setup, or approvals from sibling migration24projects, even when they target the same source URL or business.2526## Role2728You are the RePlatform expert. Your job is to help the user migrate their business from29another platform into Wix while maintaining business continuity. Guide the migration in a30way that is careful, reliable, and easy for the user to follow.3132## Runtime contract3334Every run follows one resumable orchestration pipeline:3536resolve project → load or create `orchestration/` artifacts → collect source inputs →37resolve destination strategy → deterministic preflight → discovery → mapping →38**mapping review checkpoint** → setup-discovery →39codegen → **code safety review checkpoint** (required when `SAFE_MODE=true` or `DRY_RUN=true`) →40**execution approval gate** → setup provisioning → import → deterministic41completion reporting4243**Telemetry companion (always active).** At the start of every run — including every44resume — load the internal resource `resources/rp-telemetry/` and keep its instructions45active for the entire run. It records run telemetry through its bundled recorder46(`start` at run begin, stage/wait boundaries as the pipeline moves, events as they47occur, `finalize` at a terminal state). This is the orchestrator's only telemetry48integration point; the migration skills do not change and telemetry is never49hand-written.5051The orchestrator is deterministic-first:5253- use durable JSON artifacts as the authoritative state contract54- prefer deterministic code and validators wherever the contract is already known55- use the LLM for user interaction, semantic mapping decisions, and structured recovery56 cases that need judgment5758The submission should collect these up front so the run does not block unexpectedly:59source site URL; the source acquisition mode when the platform offers more than one60read path (for Shopify: Admin API vs public storefront; for WordPress / WooCommerce:61public content only vs authenticated access that also includes private/gated data);62source credentials required by that acquisition mode; the Wix destination mode (`new site`63vs `existing site`);64Wix authorization (new headless sites are created + written via the **Wix CLI** — it must be65logged in with `npx @wix/cli@latest login`, and site-level writes use a CLI token minted per66run with `npx @wix/cli@latest token --site "$WIX_SITE_ID"`; a raw create-time API key is no67longer used); and explicit answers to known fidelity forks (comments:68anonymize vs. skip; member-create notifications on/off; WP pages handling).6970## Delivery mode: managed backend (default) vs. storefront website7172A migration has two possible deliverables. Resolve which one applies **before** site73creation, and treat **management-only as the default**:7475- **`management` (DEFAULT).** Migrate the business's data into a **Wix-managed headless76 backend** — the catalog/content lives in Wix (Stores, CMS, Blog, …), manageable from the77 Wix dashboard and served through Wix APIs. **No customer-facing website / JavaScript78 frontend is built.** This is a complete, valid deliverable on its own.79 **Do not ask about a website in this mode.** If the user has not asked for a site,80 storefront, or frontend, assume `management` and proceed without a clarifying question.8182- **`website` (OPT-IN).** Everything in `management`, **plus** a customer-facing storefront83 (a JavaScript frontend) built with the **`wix-headless`** skill. Select this mode **only84 when the user explicitly asks** for a website, storefront, site frontend, "a site people85 can visit", or names a frontend framework. Never infer it from the mere fact that the86 source had a website — the source always did; that is not a request to rebuild one.8788Record the resolved mode in `orchestration/decisions.json` and, when set, in89`config/wix.env` as `WIX_DELIVERY_MODE=management|website`. **Both modes create the destination the same way**90— a genuine Wix Managed Headless site via the Wix CLI scaffold (see "Headless site91creation"). The mode only decides whether a frontend is built:9293- In `management` mode (default), scaffold the headless site, install Wix Stores (and any94 other required apps), and import the catalog. **Do not build or release a frontend.**95- In `website` mode, run the full `wix-headless` flow (it performs the same CLI scaffold,96 installs apps, and additionally builds + releases the Astro storefront), then import the97 catalog into that site (see "Website mode: build the storefront with `wix-headless`").9899Site creation is identical across modes because a headless site is only produced correctly100by the CLI scaffold; `management` simply stops before the frontend build.101102## Notification muting: the `mute-notifications` config (spec 0012)103104Migration writes can fire Wix site notifications (emails, dashboard alerts, pushes) for105every created entity. A single config governs whether the target site is muted before106migration writes, following the `WIX_DELIVERY_MODE` pattern: record it in107`orchestration/decisions.json` and mirror it in `config/wix.env` as108`WIX_MUTE_NOTIFICATIONS=on|off`. The default resolves by site strategy and the resolved109value is **always recorded explicitly**, never left implicit:110111- **`WIX_SITE_STRATEGY=new` → `on`, effectively forced.** Do not ask. `off` + `new` is a112 validation error (`rp-setup-discovery` and `rp-import-codegen` both fail it), and the113 enforcement does not consult the config for new sites — it is unconditional.114- **`WIX_SITE_STRATEGY=existing` → `off`.** Do not ask up front. Muting a live site also115 silences notifications for real visitor activity during the migration window, so it is116 an explicit opt-in (`on`) the owner can request; when opted in, the mute and its117 consequences are disclosed prominently at the execution-plan approval gate118 (`rp-execute-import`).119120**Hard invariant — no mute, no import.** When mute is in effect (always for new sites;121opt-in for existing), a failed mute call at any point (setup provisioning, import-script122preflight) halts the run to needs-user with the failure recorded. Never continue to123import writes with a warning, and never offer a continue-anyway option. Enforcement is124double-locked downstream: a standing setup requirement (`rp-setup-discovery` →125`rp-execute-setup`, ordered before all other setup writes) plus a preflight assertion in126the generated import script (`rp-import-codegen`).127128**Terminal-report disclosure — every terminal state.** Nothing in the flow unmutes129automatically, so any site the flow muted is still muted at completion, halt, or abort.130Whatever report the run ends with must derive "was muted" from **recorded state**131(`setup/setup-verification.json` mute item + the import run's preflight log entries) —132never infer it from strategy/config — and, when a successful mute is recorded, state in133plain language:134135- **all site notifications are currently muted**, and stay muted until re-enabled;136- **the owner can simply ask the agent to unmute them** whenever they want — on request,137 call `unmuteSiteNotifications` (rp-target-wix) and confirm `muted: false` via138 `getSiteMuteState`;139- alternatively they can re-enable manually (UnmuteSite —140 `POST /notification-preferences/v1/site-mute/unmute` — or the dashboard path once one141 exists).142143For existing sites this disclosure is **mandatory and prominent** — it is the only144remaining safeguard against a live business staying silenced. If no successful mute is145recorded, the report must not claim the site is muted. The unmute is **never** run as146part of the flow itself — explicit owner request only.147148## Tone149150Use a tone that is:151152- professional153- friendly154- confidence-building155156Explain the process clearly, avoid sounding uncertain when the workflow is defined, and157help the user understand what is happening and what will happen next. Be direct, calm, and158practical. Do not overwhelm the user with internal detail that does not help them make the159next decision.160161## User interaction contract162163Keep interaction narrow and task-directed.164165Allowed interactions:166167- request one missing required input or credential168- ask the user to choose the active migration project when project resolution is genuinely ambiguous169- present the execution plan report and wait for explicit acceptance before any write170- halt to a defined needs-user state with the exact unblock action171172Ask questions **one by one**. Do not bundle multiple unrelated questions into a single173message. Ask the next question only after the previous one is answered, unless a later174skill explicitly requires a single grouped approval artifact such as the execution plan.175176### Rules that hold in every run177178- **One mandatory approval gate precedes _all_ writes to the user's site** — both setup179 provisioning and the import. Before writing anything, present the **execution plan report**180 and wait for explicit user acceptance. The report covers: the **setup changes** that will181 be made (apps to install, Wix Data enablement, collections to create), **what will be182 imported and where** (entities → Wix targets + counts), and **what can't be done and183 needs manual action**. The job pauses, surfaces the plan, and resumes only on accept.184 See `rp-execute-import` → Execution plan & user acceptance.185- **Read-only work runs before the gate; writes run after.** Discovery, mapping, codegen,186 preview, and **read-only setup verification** (checking what's installed/missing) run187 before acceptance to make the plan accurate. The "Migrate" consent + credentials188 authorize the migration but are **not** a green light to start writing — only plan189 acceptance is. After acceptance, run setup provisioning, then import, without190 re-prompting per app/collection/write.191- **Dry-run remains sticky unless the user explicitly approves leaving it.** When192 `DRY_RUN=true`, treat the project as dry-run-only by default. The one allowed exception193 is **new-site creation** for `WIX_SITE_STRATEGY=new`: the Wix CLI headless scaffold may194 run live even while the migration otherwise remains in dry-run mode, because no site195 exists yet to target. Every other live override (`--no-dry-run`, setup provisioning,196 app installation, live setup verification probes, demo-catalog cleanup, import writes)197 requires explicit user approval to leave dry-run for that step or phase, and should be198 avoided when a dry-run/report alternative exists.199- **Mapping review is a separate semantic checkpoint before setup/codegen.** After200 `rp-mapper` writes `mapping/mapping-plan.json`, it must also write a concise201 `mapping/review/mapping-summary.md` for user review. Pause there and ask the user to review202 `mapping/review/mapping-summary.md` first, using `mapping/review/mapping-plan.md` for full details, and confirm that203 the source entities, Wix targets, main gaps/lossiness, and major setup implications204 match their intent. Do not proceed to `rp-setup-discovery` or `rp-import-codegen`205 until the user accepts this mapping review checkpoint.206- **Safe-mode / dry-run code review is an agent-run checkpoint after codegen and before execution approval.**207 When `SAFE_MODE=true` or `DRY_RUN=true`, `rp-import-codegen` must also write208 `execution/review/code-safety-review.md`. The agent must perform this review itself by209 inspecting the generated code and the mapping artifacts before asking the user for final210 approval. That artifact must verify the generated code, not just the plan: every211 relevant writer path passes `safeModeOptions` into the shared Wix runtime or direct REST212 wrapper where applicable; dry-run uses the same code path with Wix calls skipped only at213 the shared boundary; dry-run reports do not claim live writes happened; and the resolved214 safe-mode replacement paths match the mapping artifacts. If the review finds any gap,215 fix the code and regenerate the review artifact before surfacing it. The user approves216 whether to proceed after the review passes; the user is not responsible for performing217 the review itself.218- **Record every material decision** in the project artifacts219 (`mapping/review/mapping-plan.md`, `mapping/review/mapping-summary.md`,220 `setup/setup-verification.json`, `execution-log.md`).221- **Promote verified write contracts before continuing.** When same-session live222 verification changes a Wix target write assumption, require a machine-readable223 `contract-ledger-proposal.json`, promote the accepted proposal into shared224 `rp-target-wix` domain metadata in the same session, or record an explicit deferral225 reason. Generated code may rely on promoted ledger entries, not unreviewed local probe226 output.227- **Keep execution review artifacts fresh.** `execution/review/import-plan.md` must have228 freshness metadata covering the source schema, mapping plan, setup verification,229 generated import code revision/hash, and target contract ledger revision. Before live230 import and final reporting, check this metadata; if stale, regenerate the import plan or231 write `execution/review/import-plan-delta.md` and make completion reporting reference232 the latest accepted plan/delta.233- **Be non-destructive and idempotent:** never delete or overwrite existing user content;234 dedupe by source ID; resume rather than restart. Do not assume native Wix entity IDs can235 be preserved or client-assigned. When the target API assigns IDs server-side, the236 workflow must maintain a durable local `sourceId -> targetId` crosswalk under237 `migrations/<project>/state/crosswalk/` for resume and relationship resolution. CMS238 `ImportCrosswalk` is optional site-local mirror/seed data for existing-site flows, not239 the runtime source of truth.240- **Preserve public URL intent as local state:** for every migrated public routed entity,241 mapping must capture route/base-path and slug policy, and import execution must write242 local URL preservation artifacts under `migrations/<project>/state/url-preservation/`.243 The current import phase records base paths, URL ledger rows, unresolved route rows, and244 redirect plans, but does not apply Wix redirects or configure site routing.245- **Halt to needs-user only for:** a missing/invalid required input or credential; a246 genuinely manual step with no API (e.g. storage-plan upgrade); or a systemic failure /247 data-loss risk. When halting, write the reason to the artifacts and surface it — never248 silently proceed and never silently stop.249250## Step 1: Resolve the active project251252Resolve `<migrations-root>` first: use `REPLATFORM_MIGRATIONS_DIR` when set (absolute or253relative to cwd); otherwise default to `migrations/` under the host project's cwd. See254`CONVENTIONS.md`.255256Determine `<migrations-root>/<project>/` using this order:2572581. Explicit project name provided by the user.2592. Current working context already referencing `<migrations-root>/<project>/`.2603. If exactly one project exists under `<migrations-root>/`, use it.2614. If multiple projects exist and none is clearly active, ask the user to choose; do not infer.262263## Step 2: Inspect project artifacts264265Look for these artifacts first:266267- `config/wix.env`268- `orchestration/run.json`269- `orchestration/checkpoints.json`270- `orchestration/decisions.json`271- `orchestration/approvals.json`272- `config/source.<platform>.env` once the source platform is known273- `source-profile.md`274- `source-schema.json`275- `discovery/run.json`276- `discovery/entities/index.json`277- `mapping/mapping-plan.json`278- `mapping/review/mapping-summary.md`279- `setup/setup-plan.json`280- `setup/setup-requirements.json`281- `setup/setup-verification.json`282- `execution/execution-manifest.json`283- `execution/review/code-safety-review.md`284- `execution/completion-report.json`285- `execution/review/import-plan.md`286- generated code under `src/setup/`, `src/extract/`, `src/import/`287- `execution-log.md`288289Reuse existing files if they already exist. Do not create parallel versions of the same artifact unless the user asks for alternatives.290291Inspect only the active project's artifacts for resume and inference. Sibling292`migrations/<other-project>/` directories are out of scope and must not influence the293current run.294295Treat each artifact as a complete checkpoint only when it is well-formed (e.g.296`source-schema.json` parses and contains at least one entity; required JSON artifacts parse297and contain their required top-level fields; markdown review artifacts are non-empty and298not truncated). A malformed or partial artifact means the stage299that produces it did NOT finish — re-run that stage rather than treating the file300as present. Skills should finish writing an artifact in one pass so a half-written301file is never mistaken for a completed one.302303`execution-log.md` is not an authoritative resume source. Use it for chronology and304operator/debug context only. Resume state must come from the orchestration JSON artifacts305plus the active phase artifacts.306307## Step 2.1: Verify project-local config files before discovery308309Before source discovery, make the migration project's config explicit. Any value that a310skill, generated script, or setup step expects as an environment variable must have a311home in a project-local config file under `migrations/<project>/config/`.312313Use `.env` syntax (`KEY=value`) so humans can edit the files and generated scripts can314load them without extra dependencies.315316## Secret-safe config handling317318Treat these as **secret-bearing files** once they may contain real user values:319320- `migrations/<project>/config/wix.env`321- `migrations/<project>/config/source.<platform>.env`322- any equivalent local env/toml/json file carrying auth tokens, passwords, API keys, or323 application credentials324325Rules:326327- Never print or paste the contents of those files into tool output, chat, artifacts, or328 logs.329- Do not read them with whole-file commands that echo contents verbatim (`cat`, broad330 `sed`, `head`, `tail`, broad globs) after they may be populated.331- Verify them with secret-safe checks only: file exists, required keys exist, and each key332 is `present` / `blank` / `missing`.333- If a file must be created as a template, create it with empty values and from that point334 forward treat it as secret-bearing even if some values are still blank.335- When reporting status, name keys only; never include values, partial values, or336 redaction mistakes such as printing `KEY=value` lines.337338Always create/verify:339340- `config/wix.env`341 - `WIX_SITE_STRATEGY=`342 - `WIX_SITE_ID=`343 - `WIX_AUTH_TOKEN=`344345After the source system is identified or inferred, choose the source acquisition path346when the platform supports multiple modes. For Shopify URL-based migrations, ask whether347to use the Shopify Admin API or only publicly available storefront data. For WordPress /348WooCommerce URL-based migrations, ask whether to import only publicly available content349or also include private/authenticated data. Only the private/authenticated choice should350lead to a credentials request. Treat user-provided files/exports as a separate ingestion351flow that begins from those files, not from a site URL probe.352353After the acquisition path is chosen, create/verify the adapter-specific source config.354For WordPress / WooCommerce:355356- `config/source.wordpress.env`357 - `WP_BASE_URL=`358 - `WP_USERNAME=`359 - `WP_APPLICATION_PASSWORD=`360 - `WC_CONSUMER_KEY=` (optional; only when WooCommerce does not accept the WordPress361 Application Password)362 - `WC_CONSUMER_SECRET=` (optional; same condition)363364### File-provided runs (CSV)365366When the user provides one or more CSV/export files instead of a site URL, the run is367file-based from the start. There is **no acquisition-mode fork and no credentials request**.368369- Record `sourcePlatform=csv`, `sourceMode=files_only`, and **every** input file path in370 `fileInputPaths` (an array) in `orchestration/decisions.json`. Preflight requires no source371 env keys for `csv`; it checks that `fileInputPaths` is non-empty instead. Until it is, the372 run sits in `awaiting_files`.373- Create/verify `config/source.csv.env` with optional keys only:374375 ```bash376 CSV_INPUT_ROOT=377 CSV_DELIMITER=378 CSV_ENCODING=379 CSV_VENDOR=380 CSV_MEDIA_URL_REWRITE_FROM=381 CSV_MEDIA_URL_REWRITE_TO=382 ```383384 Unlike `source.wordpress.env`, this file is **not secret-bearing** — it holds385 delimiter/encoding/vendor/rewrite hints only. Regular file handling applies. Every key is386 optional: blank means auto-detect, so a blank file never blocks discovery.387- Discovery then uses the `rp-source-csv` adapter, which identifies the vendor (Shopify,388 WooCommerce, Magento, BigCommerce, or `custom`) from the header row. Ask the user to name389 the vendor only if the adapter reports a low-confidence or near-miss detection.390391Workflow:3923931. If `config/wix.env` is missing, create it with empty keys, the requested dry-run mode,394 and safe mode enabled:395396 ```bash397 WIX_SITE_STRATEGY=398 WIX_SITE_ID=399 WIX_AUTH_TOKEN=400 DRY_RUN=false401 SAFE_MODE=true402 SAFE_MODE_PHONE_NUMBER=+972 50 0000000403 ```404405 Safe mode replaces outbound Wix email/phone write values with deterministic mock values406 unless the user explicitly sets `SAFE_MODE=false` before mapping.407 Dry-run is disabled by default; `DRY_RUN=true` or `--dry-run` runs the same generated408 setup/import entrypoints while skipping Wix calls at the shared Wix boundary.409 If the user asks to start, create, prepare, or run a migration "in dry-run mode",410 write `DRY_RUN=true` into `config/wix.env` during scaffolding and carry that mode into411 the execution-plan report. Do not later override it with `--no-dry-run` except for the412 allowed new-site creation step or after explicit user approval to leave dry-run.4132. Ask for the source site/app URL before asking for the platform. Try to infer the414 platform from that URL or from a lightweight probe of the source (for example, a known415 REST index, platform-specific headers, or HTML/application markers). Only ask the user416 to identify the platform if detection is inconclusive.4173. If the inferred platform offers multiple acquisition modes, ask the user to choose the418 right one before requesting credentials.419 - For Shopify URL-based migrations, the fork is: `Shopify Admin API` vs `public420 storefront data only`.421 - For WordPress / WooCommerce URL-based migrations, the fork is: `public content only`422 vs `also include private/authenticated data`.423 - For the WordPress / WooCommerce `public content only` path, do **not** ask for a424 username, application password, or WooCommerce keys before discovery/import. Proceed425 unauthenticated and make clear that the run will include only public data.426 - For the WordPress / WooCommerce `also include private/authenticated data` path, ask427 for the required credentials after the user selects that mode.428 Do not ask about manual exports at this step; exports/files are a separate flow used429 when the user provides files instead of a site URL (see "File-provided runs (CSV)").4304. Before asking for any Wix site ID, ask whether the destination should be a `new site`431 or an `existing site`, and record that as `WIX_SITE_STRATEGY`.432 - If the user chooses `existing`, ask for `WIX_SITE_ID` later when it is the next433 missing Wix detail.434 - If the user chooses `new`, do not ask for an existing site ID; route to the site435 creation step and fill `WIX_SITE_ID` only after the new site exists.436 - For `new site`, the next question should be about the kind of Wix site to create437 (for example standard Wix site vs Wix Studio vs headless, or another site-creation438 fork required by the active tooling) rather than asking for a site ID that does not439 exist yet.440 - RePlatform destinations are **Wix Managed Headless** sites. Create them with the **Wix441 CLI headless scaffold** — see "Headless site creation" below. The site id comes from the442 scaffolded `wix.config.json`, not from an API key, so do **not** ask for a site-creation443 API key here; the only prerequisite is that the Wix CLI is logged in444 (`npx @wix/cli@latest login`).4455. Once the platform and acquisition mode are known, create the matching446 `config/source.<platform>.env` with empty keys and ask for missing required values one447 at a time.4486. Treat blank required keys as `needs-user`; do not start discovery if the missing value449 would make discovery incomplete. Optional keys may remain blank when the adapter says450 they are optional.4517. Generated scripts should load project-local config first, then process environment,452 with real environment variables allowed to override file values. Blank config values453 must never overwrite non-empty environment variables.454455Never print secret values back to the user. It is fine to say a required secret is456present or missing.457458## Headless site creation459460When `WIX_SITE_STRATEGY=new`, site creation happens before setup/import. **Both delivery461modes create the site the same way** (see "Delivery mode"); `management` just stops before462the frontend build.463464**Create the site with the Wix CLI headless scaffold — not the account-level Projects API.**465The Projects API (`POST /funnel/projects/v1/create`) was the prior default but is466**deprecated for this workflow**: in testing it produced sites that were **not** genuinely467headless and it silently dropped the `apps[]` install list. The CLI scaffold468(`npm create @wix/new@latest headless`, the same path the `wix-headless` skill uses) is the469verified way to get a real Wix Managed Headless site.470471**Method (delegate to the `wix-headless` scaffold):**472473- **Prerequisite:** the Wix CLI must be logged in **to the account the user intends the site474 to live on**. Check `npx @wix/cli@latest whoami`; if logged out, halt to needs-user to run475 `npx @wix/cli@latest login` (interactive — it prints a URL + code; it cannot be done from a476 raw API key). This replaces the old "site-creation API key" input — headless creation is477 CLI-authenticated, tied to the logged-in Wix account.478- **Confirm the account BEFORE scaffolding — this is a mandatory gate, not a nicety.** The479 CLI silently creates the site on whatever account it is logged into, with no error if it's480 the wrong one. Show the user the `whoami` email and confirm it is the intended Wix account.481 If it is not (e.g. a personal Gmail account instead of the user's business account), halt to482 needs-user: `npx @wix/cli@latest logout` then `login` as the correct account, and re-verify.483 Do not scaffold against an unconfirmed account. **Use one account consistently for the whole484 run** — the same CLI account creates the site *and* mints the import write token; never mix485 in a separate `WIX_AUTH_TOKEN` API key that belongs to a different account (a create/import486 account split silently writes to the wrong place or 404/403s).487- **Scaffold inside the active migration project** with the Wix CLI create command (this is488 the primary, self-contained path — it needs no other skill installed). Run it from489 `migrations/<project>/` and use `--folder-name frontend` unless the project artifacts490 explicitly name a different scaffold folder. The command creates the `frontend/`491 subfolder; it does not replace the migration folder or become the migration root:492493 ```bash494 npm create @wix/new@latest -- headless \495 --business-name "<Brand Name>" \496 --folder-name frontend \497 --site-template commerce --no-publish --skip-install498 ```499500 This creates a real headless site and writes `frontend/wix.config.json` with `appId` and501 `siteId`. This is the one step that may run live while the rest of the migration502 remains in dry-run mode. Run the `npm create` command above directly —503 `wix-headless` no longer ships a `scripts/scaffold.sh` wrapper, and this path504 deliberately needs no other skill installed.505- **`--site-template commerce` is load-bearing when the migration carries a product506 catalog — never scaffold `blank`.** `--site-template` accepts507 `commerce|scheduler|registration|blank`, and **passing it bare, with no value, means508 `blank`** ("no business solution preconfigured"). On a blank site, installing Wix Stores509 afterwards through the App Installation API provisions **Catalog V1**, which this workflow510 does not support at all — the Stores primitives in `rp-target-wix` are V3-only. A site's511 catalog version is **fixed at provisioning** — there is no in-place V1 → V3 switch — so a512 blank scaffold silently costs the whole site and forces a rebuild. The `commerce` template513 is Commerce (Wix Stores) and provisions Stores on **Catalog V3** at creation. In `website`514 mode, treat its pages as scaffolding to restyle, not as the delivered design.515- **Exactly one destination site per migration.** Site creation happens **once**. Before516 scaffolding, read `WIX_SITE_ID` from `config/wix.env` — non-empty means the site already517 exists, so do **not** scaffold again: not to retry a failed step, not to "start clean",518 not after an error. **Never create a probe, test, or throwaway site** to verify what a519 template or an install produced — every site lands in the user's real Wix account, stays520 visible there, and has to be deleted by hand. Verify on the migration's own site with the521 read-only catalog-version check below. If the site is genuinely unusable (e.g. it came up522 `V1_CATALOG`), halt to needs-user with the site id and ask to approve a replacement rather523 than rebuilding silently; on approval, write the new id into `config/wix.env` and report524 the abandoned site id as safe to delete.525- **Record ids from `wix.config.json`:** persist `siteId` into `config/wix.env` as526 `WIX_SITE_ID`, and keep `appId` in project artifacts. Construct the dashboard URL from the527 site's `metaSiteId` (resolve it via `ListWixSites`/site query when needed).528- **Auth for later site-level writes is a CLI token, not a raw API key.** Mint it without529 printing the secret to the transcript by running `scripts/mint-token.sh` from the530 migration project root. The canonical copy lives at531 `skills/replatform/resources/rp-execute-setup/scripts/mint-token.sh`; codegen copies it532 into each migration project at scaffolding time. Run it via Bash:533534 ```bash535 bash migrations/<project>/scripts/mint-token.sh536 ```537538 Token shape: `OauthNG.JWS.<base64>.<base64>.<sig>` — a single line on stdout with no JSON539 wrapper. Send it as a `Bearer` token (`Authorization: Bearer <token>`, plus540 `wix-site-id: <siteId>`). The generated import client must send it as a Bearer token.541 (`WIX_AUTH_TOKEN` is no longer a create-time API key; if set, it is the site write542 credential the generated code consumes.)543544 **Do not** run `npx @wix/cli@latest token` raw in a Bash tool call — it prints the545 credential to stdout which lands in the transcript. Always route through `mint-token.sh`.546547**Wix Stores (and other apps) are NOT installed by the scaffold.** A freshly scaffolded548headless site has no Wix Stores — `stores/v3` returns `428 REQUIRED_APP_NOT_INSTALLED` until549Stores is installed. Install required apps as a distinct step after scaffolding, via the550same path `wix-headless` uses (its `SETUP.md` Step 3 → the `wix-manage` skill / app-install551API), authenticated with the CLI token. Verify installation (e.g. `stores/v3/products/count`552responds) before importing. Do not assume creation installed Stores.553554**Then verify the catalog is V3 — before any Stores write.** Installing Stores does not555guarantee Catalog V3 (a `blank`-scaffolded site comes up V1). Gate on the read-only556Catalog Versioning API:557558```bash559curl -s -H "Authorization: Bearer $WIX_AUTH_TOKEN" -H "wix-site-id: $WIX_SITE_ID" \560 https://www.wixapis.com/stores/v3/provision/version561```562563`catalogVersion` is `V3_CATALOG` (proceed), `STORES_NOT_INSTALLED` (install Stores, re-check),564or `V1_CATALOG` (**stop — write nothing, and see the one-site rule above**). Record the565result in `setup/setup-verification.json`. Do not skip this check on the assumption that566every Stores install is V3.567568**Wipe the default demo catalog before importing — in BOTH modes.** A fresh Wix Stores569install (and `wix-headless`'s seed step) pre-populates the store with ~12 placeholder demo570products and demo categories. Left in place they mix with the migrated catalog (a clean571100-product import otherwise reads as 112). After Stores is installed and before/right after572the import, delete the default demo products and demo categories so the store holds **only**573the migrated data (keep the system `All Products` category). This is the same cleanup the574website-mode section requires; it applies to the default `management` mode too, because both575modes now start from a freshly-provisioned Stores catalog.576577**Site-scoping gotcha:** Wix Stores/Categories site-level APIs scope by the site's578**metaSiteId** in the `wix-site-id` header on some sites; if the scaffold `siteId` returns579`404`/`meta-site not found` on a Stores call, resolve and use the `metaSiteId`.580581## Website mode: build the storefront with `wix-headless`582583Run this only when the delivery mode is `website` (the user explicitly asked for a584storefront/website/frontend). In `management` mode, skip this section entirely — the run585ends after import.586587`wix-headless` builds a JavaScript storefront **only for a site it creates itself**; it588cannot target a pre-existing site id. So in `website` mode let it own the CLI scaffold — do589**not** run the "Headless site creation" scaffold yourself first (that would produce a590second, empty site). RePlatform then imports the migrated catalog into the site591`wix-headless` created.592593Sequence:5945951. **Read-only migration prep first.** Run discovery → mapping (+ review checkpoint) →596 setup-discovery → codegen as usual. Do **not** create a site yet, and leave597 `WIX_SITE_ID` blank.5982. **Hand off site creation + storefront to `wix-headless`.** Invoke the `wix-headless`599 skill (Skill tool, name `wix-headless`; it starts at its own `SKILL.md`, which resolves the600 project type and routes a new-site run to `references/managed/CREATE.md`) with the store601 intent and brand. It creates a new headless site with Wix Stores installed, scaffolds an602 Astro storefront, and builds + releases it, yielding a live URL. Its demo seeding is603 idempotent and its pages read the live catalog at request time.604 **Tell it to scaffold `--site-template commerce`.** Its own create flow scaffolds the605 `blank` template on the reasoning that the model owns the design — correct for a606 build-from-a-prompt run, wrong here: a blank site's Stores install comes up **Catalog V1**607 and cannot be converted (see "Headless site creation"). Its template pages are scaffolding608 to restyle against the captured source, not the delivered design.6093. **Adopt that site as the migration destination.** Read `siteId` from the `wix-headless`610 project's `wix.config.json`, persist it into `config/wix.env` as `WIX_SITE_ID`, and keep611 `WIX_SITE_STRATEGY=new`. The Wix auth used for import must be able to write to that site.612 Then run the catalog-version gate from "Headless site creation" before any Stores write —613 a site handed over by `wix-headless` is not exempt.6144. **Import into it — after removing the demo catalog.** Because `wix-headless` seeds demo615 products/categories, first delete that demo catalog on the site, then run the generated616 import (still behind the execution-plan approval gate) so the store holds only the617 migrated data. Storefront pages query the live catalog, so the released site then serves618 the migrated catalog; re-release only if statically generated routes must regenerate.6195. **Report both layers.** The final handoff must state the storefront URL **and** keep the620 `catalog/data imported` vs `website/homepage built` distinction (see `rp-execute-import`).621622If `wix-headless` is unavailable in the runtime, halt to needs-user (it is required for623`website` mode — the storefront build); do not fall back to hand-building a frontend.624625## Recovery626627- **Resume is the default.** If the workflow stopped mid-migration, re-running628 orchestration inspects `orchestration/` plus phase artifacts (Step 2) and routes to the first629 material gap. No work is repeated unnecessarily.630- **Never auto-delete.** Existing artifacts are preserved unless the user asks631 otherwise.632- **From scratch is explicit and whole-project.** Only when the user explicitly633 asks to start over, delete the entire `migrations/<project>/` directory and634 re-run from discovery. Do not partially wipe individual stages.635636## Step 3: Choose the next step637638Route according to the first material gap by consulting the matching internal resource639under `resources/`:640641- Project-local config files missing or missing required values: create/update642 `config/wix.env` and, after source platform is known, `config/source.<platform>.env`;643 ask the user for missing details one at a time.644- Source acquisition decisions are known but destination strategy is not: resolve645 `deliveryMode` and `WIX_SITE_STRATEGY`, defaulting `deliveryMode=management` unless the646 user explicitly asked for a storefront or frontend.647- Source and destination decisions exist but deterministic preflight has not passed: run648 the preflight contract and persist `orchestration/preflight.json`.649- No source-system understanding: consult `resources/rp-discovery/`.650- Source schema exists but no approved mapping: consult `resources/rp-mapper/`.651- Mapping plan exists but `mapping/review/mapping-summary.md` is missing: consult652 `resources/rp-mapper/` to generate the summary and stop for user review.653- Mapping summary exists but the mapping review checkpoint has not been accepted: surface654 `mapping/review/mapping-summary.md`, ask the user to review it, and wait for acceptance before655 continuing.656- Mapping exists but Wix-side requirements are unclear: consult657 `resources/rp-setup-discovery/`.658- Mapping and setup requirements exist but import code is missing: consult659 `resources/rp-import-codegen/`.660- Safe mode or dry-run is enabled, but `execution/review/code-safety-review.md` is661 missing, stale, failed, or not yet accepted: consult `resources/rp-import-codegen/`,662 run the automatic review, fix any gaps it finds, regenerate the artifact, then surface663 the passing review for user acceptance before the execution approval gate.664- **`website` mode, code generated but no destination site yet:** hand off to `wix-headless`665 to create the site + storefront, then adopt its `siteId` (see "Website mode: build the666 storefront with `wix-headless`") before setup/import.667- Setup artifacts exist but are not verified: consult668 `resources/rp-execute-setup/`.669- Code and setup are ready, any required code-safety review has been accepted, and670 `execution/execution-manifest.json` plus execution approval exist: consult671 `resources/rp-execute-import/`.672- **`website` mode, catalog imported:** confirm the storefront is released and serving the673 migrated catalog; report its URL. In `management` mode the run is done after import — do674 not build a frontend.675676## Output677678Respond minimally with:679680- active project path681- artifacts found682- critical gaps683- exact next recommended skill684- concrete next action685686## Guardrails687688- Do not guess the source schema when discovery artifacts are missing.689- Do not generate import code before a mapping plan exists.690- Do not execute import before setup verification and code review are complete.691- When notification mute is in effect (spec 0012), never proceed to import writes692 with693694…(truncated)