@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-replatform/SKILL.md

@@ -0,0 +1,693 @@
+---
+name: replatform
+description: >-
+  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.
+---
+
+# 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:
+
+1. Explicit project name provided by the user.
+2. Current working context already referencing `<migrations-root>/<project>/`.
+3. If exactly one project exists under `<migrations-root>/`, use it.
+4. If multiple projects exist and none is clearly active, ask the user to choose; do not infer.
+
+## Step 2: Inspect project artifacts
+
+Look for these artifacts first:
+
+- `config/wix.env`
+- `orchestration/run.json`
+- `orchestration/checkpoints.json`
+- `orchestration/decisions.json`
+- `orchestration/approvals.json`
+- `config/source.<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:
+
+  ```bash
+  CSV_INPUT_ROOT=
+  CSV_DELIMITER=
+  CSV_ENCODING=
+  CSV_VENDOR=
+  CSV_MEDIA_URL_REWRITE_FROM=
+  CSV_MEDIA_URL_REWRITE_TO=
+  ```
+
+  Unlike `source.wordpress.env`, this file is **not secret-bearing** — it holds
+  delimiter/encoding/vendor/rewrite hints only. Regular file handling applies. Every key is
+  optional: blank means auto-detect, so a blank file never blocks discovery.
+- Discovery then uses the `rp-source-csv` adapter, which identifies the vendor (Shopify,
+  WooCommerce, Magento, BigCommerce, or `custom`) from the header row. Ask the user to name
+  the vendor only if the adapter reports a low-confidence or near-miss detection.
+
+Workflow:
+
+1. If `config/wix.env` is missing, create it with empty keys, the requested dry-run mode,
+   and safe mode enabled:
+
+   ```bash
+   WIX_SITE_STRATEGY=
+   WIX_SITE_ID=
+   WIX_AUTH_TOKEN=
+   DRY_RUN=false
+   SAFE_MODE=true
+   SAFE_MODE_PHONE_NUMBER=+972 50 0000000
+   ```
+
+   Safe mode replaces outbound Wix email/phone write values with deterministic mock values
+   unless the user explicitly sets `SAFE_MODE=false` before mapping.
+   Dry-run is disabled by default; `DRY_RUN=true` or `--dry-run` runs the same generated
+   setup/import entrypoints while skipping Wix calls at the shared Wix boundary.
+   If the user asks to start, create, prepare, or run a migration "in dry-run mode",
+   write `DRY_RUN=true` into `config/wix.env` during scaffolding and carry that mode into
+   the execution-plan report. Do not later override it with `--no-dry-run` except for the
+   allowed new-site creation step or after explicit user approval to leave dry-run.
+2. Ask for the source site/app URL before asking for the platform. Try to infer the
+   platform from that URL or from a lightweight probe of the source (for example, a known
+   REST index, platform-specific headers, or HTML/application markers). Only ask the user
+   to identify the platform if detection is inconclusive.
+3. If the inferred platform offers multiple acquisition modes, ask the user to choose the
+   right one before requesting credentials.
+   - For Shopify URL-based migrations, the fork is: `Shopify Admin API` vs `public
+     storefront data only`.
+   - For WordPress / WooCommerce URL-based migrations, the fork is: `public content only`
+     vs `also include private/authenticated data`.
+   - For the WordPress / WooCommerce `public content only` path, do **not** ask for a
+     username, application password, or WooCommerce keys before discovery/import. Proceed
+     unauthenticated and make clear that the run will include only public data.
+   - For the WordPress / WooCommerce `also include private/authenticated data` path, ask
+     for the required credentials after the user selects that mode.
+   Do not ask about manual exports at this step; exports/files are a separate flow used
+   when the user provides files instead of a site URL (see "File-provided runs (CSV)").
+4. Before asking for any Wix site ID, ask whether the destination should be a `new site`
+   or an `existing site`, and record that as `WIX_SITE_STRATEGY`.
+   - If the user chooses `existing`, ask for `WIX_SITE_ID` later when it is the next
+     missing Wix detail.
+   - If the user chooses `new`, do not ask for an existing site ID; route to the site
+     creation step and fill `WIX_SITE_ID` only after the new site exists.
+   - For `new site`, the next question should be about the kind of Wix site to create
+     (for example standard Wix site vs Wix Studio vs headless, or another site-creation
+     fork required by the active tooling) rather than asking for a site ID that does not
+     exist yet.
+  - RePlatform destinations are **Wix Managed Headless** sites. Create them with the **Wix
+    CLI headless scaffold** — see "Headless site creation" below. The site id comes from the
+    scaffolded `wix.config.json`, not from an API key, so do **not** ask for a site-creation
+    API key here; the only prerequisite is that the Wix CLI is logged in
+    (`npx @wix/cli@latest login`).
+5. Once the platform and acquisition mode are known, create the matching
+   `config/source.<platform>.env` with empty keys and ask for missing required values one
+   at a time.
+6. Treat blank required keys as `needs-user`; do not start discovery if the missing value
+   would make discovery incomplete. Optional keys may remain blank when the adapter says
+   they are optional.
+7. Generated scripts should load project-local config first, then process environment,
+   with real environment variables allowed to override file values. Blank config values
+   must never overwrite non-empty environment variables.
+
+Never print secret values back to the user. It is fine to say a required secret is
+present or missing.
+
+## Headless site creation
+
+When `WIX_SITE_STRATEGY=new`, site creation happens before setup/import. **Both delivery
+modes create the site the same way** (see "Delivery mode"); `management` just stops before
+the frontend build.
+
+**Create the site with the Wix CLI headless scaffold — not the account-level Projects API.**
+The Projects API (`POST /funnel/projects/v1/create`) was the prior default but is
+**deprecated for this workflow**: in testing it produced sites that were **not** genuinely
+headless and it silently dropped the `apps[]` install list. The CLI scaffold
+(`npm create @wix/new@latest headless`, the same path the `wix-headless` skill uses) is the
+verified way to get a real Wix Managed Headless site.
+
+**Method (delegate to the `wix-headless` scaffold):**
+
+- **Prerequisite:** the Wix CLI must be logged in **to the account the user intends the site
+  to live on**. Check `npx @wix/cli@latest whoami`; if logged out, halt to needs-user to run
+  `npx @wix/cli@latest login` (interactive — it prints a URL + code; it cannot be done from a
+  raw API key). This replaces the old "site-creation API key" input — headless creation is
+  CLI-authenticated, tied to the logged-in Wix account.
+- **Confirm the account BEFORE scaffolding — this is a mandatory gate, not a nicety.** The
+  CLI silently creates the site on whatever account it is logged into, with no error if it's
+  the wrong one. Show the user the `whoami` email and confirm it is the intended Wix account.
+  If it is not (e.g. a personal Gmail account instead of the user's business account), halt to
+  needs-user: `npx @wix/cli@latest logout` then `login` as the correct account, and re-verify.
+  Do not scaffold against an unconfirmed account. **Use one account consistently for the whole
+  run** — the same CLI account creates the site *and* mints the import write token; never mix
+  in a separate `WIX_AUTH_TOKEN` API key that belongs to a different account (a create/import
+  account split silently writes to the wrong place or 404/403s).
+- **Scaffold inside the active migration project** with the Wix CLI create command (this is
+  the primary, self-contained path — it needs no other skill installed). Run it from
+  `migrations/<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:
+
+  ```bash
+  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
+  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:
+
+```bash
+curl -s -H "Authorization: Bearer $WIX_AUTH_TOKEN" -H "wix-site-id: $WIX_SITE_ID" \
+  https://www.wixapis.com/stores/v3/provision/version
+```
+
+`catalogVersion` is `V3_CATALOG` (proceed), `STORES_NOT_INSTALLED` (install Stores, re-check),
+or `V1_CATALOG` (**stop — write nothing, and see the one-site rule above**). Record the
+result in `setup/setup-verification.json`. Do not skip this check on the assumption that
+every Stores install is V3.
+
+**Wipe the default demo catalog before importing — in BOTH modes.** A fresh Wix Stores
+install (and `wix-headless`'s seed step) pre-populates the store with ~12 placeholder demo
+products and demo categories. Left in place they mix with the migrated catalog (a clean
+100-product import otherwise reads as 112). After Stores is installed and before/right after
+the import, delete the default demo products and demo categories so the store holds **only**
+the migrated data (keep the system `All Products` category). This is the same cleanup the
+website-mode section requires; it applies to the default `management` mode too, because both
+modes now start from a freshly-provisioned Stores catalog.
+
+**Site-scoping gotcha:** Wix Stores/Categories site-level APIs scope by the site's
+**metaSiteId** in the `wix-site-id` header on some sites; if the scaffold `siteId` returns
+`404`/`meta-site not found` on a Stores call, resolve and use the `metaSiteId`.
+
+## Website mode: build the storefront with `wix-headless`
+
+Run this only when the delivery mode is `website` (the user explicitly asked for a
+storefront/website/frontend). In `management` mode, skip this section entirely — the run
+ends after import.
+
+`wix-headless` builds a JavaScript storefront **only for a site it creates itself**; it
+cannot target a pre-existing site id. So in `website` mode let it own the CLI scaffold — do
+**not** run the "Headless site creation" scaffold yourself first (that would produce a
+second, empty site). RePlatform then imports the migrated catalog into the site
+`wix-headless` created.
+
+Sequence:
+
+1. **Read-only migration prep first.** Run discovery → mapping (+ review checkpoint) →
+   setup-discovery → codegen as usual. Do **not** create a site yet, and leave
+   `WIX_SITE_ID` blank.
+2. **Hand off site creation + storefront to `wix-headless`.** Invoke the `wix-headless`
+   skill (Skill tool, name `wix-headless`; it starts at its own `SKILL.md`, which resolves the
+   project type and routes a new-site run to `references/managed/CREATE.md`) with the store
+   intent and brand. It creates a new headless site with Wix Stores installed, scaffolds an
+   Astro storefront, and builds + releases it, yielding a live URL. Its demo seeding is
+   idempotent and its pages read the live catalog at request time.
+   **Tell it to scaffold `--site-template commerce`.** Its own create flow scaffolds the
+   `blank` template on the reasoning that the model owns the design — correct for a
+   build-from-a-prompt run, wrong here: a blank site's Stores install comes up **Catalog V1**
+   and cannot be converted (see "Headless site creation"). Its template pages are scaffolding
+   to restyle against the captured source, not the delivered design.
+3. **Adopt that site as the migration destination.** Read `siteId` from the `wix-headless`
+   project's `wix.config.json`, persist it into `config/wix.env` as `WIX_SITE_ID`, and keep
+   `WIX_SITE_STRATEGY=new`. The Wix auth used for import must be able to write to that site.
+   Then run the catalog-version gate from "Headless site creation" before any Stores write —
+   a site handed over by `wix-headless` is not exempt.
+4. **Import into it — after removing the demo catalog.** Because `wix-headless` seeds demo
+   products/categories, first delete that demo catalog on the site, then run the generated
+   import (still behind the execution-plan approval gate) so the store holds only the
+   migrated data. Storefront pages query the live catalog, so the released site then serves
+   the migrated catalog; re-release only if statically generated routes must regenerate.
+5. **Report both layers.** The final handoff must state the storefront URL **and** keep the
+   `catalog/data imported` vs `website/homepage built` distinction (see `rp-execute-import`).
+
+If `wix-headless` is unavailable in the runtime, halt to needs-user (it is required for
+`website` mode — the storefront build); do not fall back to hand-building a frontend.
+
+## Recovery
+
+- **Resume is the default.** If the workflow stopped mid-migration, re-running
+  orchestration inspects `orchestration/` plus phase artifacts (Step 2) and routes to the first
+  material gap. No work is repeated unnecessarily.
+- **Never auto-delete.** Existing artifacts are preserved unless the user asks
+  otherwise.
+- **From scratch is explicit and whole-project.** Only when the user explicitly
+  asks to start over, delete the entire `migrations/<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
+  without a verified mute — a failed mute halts to needs-user, with no
+  continue-anyway path. Never report a site as muted from strategy/config inference;
+  only from recorded verification state. Never unmute unless the owner explicitly
+  asks.