@wix/agent-skills 1.33.1 → 1.35.0

package/skills/wix-replatform/SKILL.md

@@ -1,693 +1,238 @@
 ---
-name: replatform
+name: wix-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.
+  Routes RePlatform source-to-Wix migrations to the next required workflow module by
+  inspecting authoritative migration artifacts. Use when starting, resuming, 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
+# wix-replatform
+
+`wix-replatform` is the compact supervisor for a resumable source-to-Wix migration. It
+selects one internal module for the active stage; it does not carry every stage procedure
+in its own context.
+
+## Always-active contract
+
+- Resolve the active project under `migrations/<project>/` (or `REPLATFORM_MIGRATIONS_DIR`)
+  before inspecting or creating anything. Only that project's artifacts are authoritative.
+- Preserve `EXPECTATIONS.md` at that project root. It is the user's free-form record of
+  how they expected the run to behave; initialization creates it once and never overwrites it.
+- Start/resume `resources/rp-telemetry/` at the beginning of every run and finalize it at
+  a terminal state. Never hand-write telemetry events.
+- Use orchestration JSON plus validated stage artifacts as resume authority. Logs and chat
+  history are diagnostic context only.
+- Preserve user data: write idempotently, dedupe by source identity, resume rather than
+  restart, and never create a second destination site for a migration.
+- Never print secrets, secret-bearing config contents, tokens, or credentials. Report only
+  key names and present/blank/missing status.
+- Do not declare a migration complete from prose or a single artifact. The deterministic
+  router and aggregate completion artifact own terminal completion.
+
+## CLI-launched runs and human actions
+
+When a migration is started through `replatform`, the terminal is deliberately
+non-interactive: do not use an agent question UI, ask for stdin, or wait for a person in the
+current agent turn. The runner owns process lifecycle and emits only observed events; it does
+not replace this skill's router or completion receipts.
+
+When a human choice, review, approval, or manual prerequisite is needed, create a durable
+request with `node skills/wix-replatform/scripts/user-action.js create --project <projectDir>
+--request-file <request.json>`, then end the turn. Put only reviewed artifact paths in the
+request. The person can later use `replatform requests`, `replatform show`, and
+`replatform answer`; a resumed agent reads the answered request from
+`orchestration/user-actions/`, never from reconstructed chat context.
+
+Cancellation is not completion. If the runner has recorded `cancel_requested`, `canceled`, or
+`interrupted`, preserve partial/recovery artifacts and let a later explicit `replatform resume`
+route recovery. Never create aggregate migration completion from an aborted execution report.
+
+## Pipeline
+
+```text
+intake → destination → source inputs → preflight → (standard: discovery → mapping → codegen;
+quick: adapter preflight → quick plan) → setup discovery → website handoff
+→ safety review/approval → setup → import
+→ storefront continuation (website only) → aggregate finalization
 ```
 
-`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
+Delivery modes are `management` (backend only), `website` (frontend only), and
+`management_and_website` (the integrated flow above). Accept user input `both` as
+`management_and_website` and persist the canonical value.
+
+For `deliveryMode=management`, aggregate finalization requires valid backend import
+accounting. For `deliveryMode=management_and_website`, it additionally requires a current
+`website/completion.json` with completed screenshot review, no unresolved critical/high
+gaps, and release evidence. `execution/completion-report.json` is backend accounting,
+never website-migration completion by itself.
+
+## Route before acting
+
+On every new or resumed turn:
+
+1. Resolve the project and initialize/load its orchestration artifacts.
+2. Run `node skills/wix-replatform/scripts/orchestration-route.js <projectDir>`.
+3. Dispatch the `nextResource` to a Developer subagent instead of loading and following it
+   yourself. Give it the project directory and the resource to run; it follows that
+   resource's contract exactly as written, unchanged. Read back only its result — never its
+   transcript, tool output, or logs.
+   - A Developer subagent may fan out to its own sub-subagents, only when it is certain
+     doing so is harmless — read-only work with no shared state and no write to anything
+     durable — and only if the host agent happens to support it. It must never fan out for
+     anything that writes shared state; that stays one write at a time, exactly as each
+     resource's own contract already does today. If the host agent doesn't support nested
+     dispatch, the Developer just does the work itself, sequentially.
+4. Dispatch a QA subagent to check the Developer's result against that resource's own
+   stated required outputs (its own "artifacts to create or update" or "## Output"
+   section, and any review/gap documents it defines). QA is read-only — it never writes or
+   calls Wix. If something's missing, dispatch a new Developer for the same resource with
+   QA's findings; otherwise the stage is done.
+5. At the end of each pipeline phase (discovery, mapping, setup discovery, import, and so
+   on — see the pipeline above; a phase spans several resource-level stages), dispatch a QA
+   subagent to review that phase's documents as a whole (for example
+   `mapping/review/mapping-summary.md` and `mapping-gaps.json`, or
+   `execution/completion-report.json`) before routing to the next phase. This catches
+   anything a single per-task check could miss. For the import phase specifically, this
+   review must be entity-by-entity against the accepted mapping plan, not a skim of the
+   top-level status string — see `rp-execute-import`'s "Entity-by-entity QA" section. Any
+   run-fixing dispatch mid-phase (a crash fix, a slowness fix, a resumed pass) does not
+   itself satisfy this; run the phase-level QA again once the fix lands, since fixing one
+   entity's defect certifies nothing about its neighbors.
+6. Route again after every stage boundary. Never decide the next stage from memory.
+
+The router (`lib/orchestration-router.js`) is the only routing and resume authority. It
+recomputes the route from decisions, approvals, preflight, `run.json` `status` and the phase
+outputs on every call; `run.json.currentState` is diagnostic only, never a routing input.
+
+- A recorded rejection stops the route in every mode, one-click included:
+  `execution_approval_rejected` is `blocked` before any setup or import write, and
+  `mapping_approval_rejected` returns to `rp-mapper` for a new plan.
+- A gated output that exists but is unusable (`source_schema_invalid`, `mapping_plan_invalid`,
+  `setup_plan_invalid`, `setup_requirements_invalid`, `execution_manifest_invalid`) is
+  `blocked` with `errors` and the producer as `nextResource`. Do not re-run the producer
+  automatically; report the errors to the Import Operator and stop.
+- The import routes (`missing_completion_report`, `quick_mode_import_required`) carry
+  `importProgress`. `interrupted` lists `recoveryArtifacts`: resume that import, which
+  reconciles before any create. Never start a second import.
+
+If an artifact is malformed, partial, stale, or fails its validator, treat its producing
+stage as incomplete and route to the producer. Do not make parallel replacement artifacts.
+
+A user action whose reviewed artifacts changed after it was created is refused with
+`user_action_stale` and stays pending. Create a new request from the current artifacts.
+
+**Catching up a finished migration is a rerun, not a new project.** When the user asks to pull
+in records that arrived or changed since the import — "the source kept selling", "these orders
+are missing", "re-run it" — reuse the same project, destination, mapping, generated importer
+and crosswalk, and route to `rp-execute-import` → "Rerunning an import for new and modified
+records". Do not scaffold a second project or re-approve an unchanged mapping; a
+mapping or scope *change* does go back through the existing gates. A rerun's revision conflicts
+are user decisions even in 1-click mode.
+
+## Demand-loaded module map
+
+| Router situation | Dispatch |
+|---|---|
+| project, delivery mode, source mode, or grouped intake is unresolved | `resources/rp-project-intake/` |
+| destination is absent, conflicting, or needs creation/adoption | `resources/rp-destination/` |
+| source URL/files/config/acquisition mode/credentials are required, including source credentials said to exist already on another site | `resources/rp-source-inputs/` |
+| deterministic preflight is missing or blocked | `resources/rp-preflight/` |
+| quick mode needs platform resolution, endpoint preflight, plan, extraction, or import | selected `resources/rp-quick-<platform>/` |
+| source schema is missing | `resources/rp-discovery/` and its selected source adapter |
+| mapping is missing or needs review | `resources/rp-mapper/` |
+| Wix requirements are missing | `resources/rp-setup-discovery/` |
+| import code/review is missing or stale | `resources/rp-import-codegen/` |
+| setup verification is missing | `resources/rp-execute-setup/` |
+| backend completion report is missing | `resources/rp-execute-import/` |
+| frontend-only work, or integrated website handoff/build/gap loop/release receipt is incomplete | `resources/rp-website-continuation/` |
+| aggregate completion is missing | `resources/rp-execution-policy/` |
+
+The resource named by the route is the complete stage contract, dispatched as described in
+"Route before acting" — the main session itself never loads it directly. Only the
+dispatched Developer loads source-file, secret, scaffolding, or storefront procedures, and
+only for the stage that actually needs them; nothing about a stage where they're irrelevant
+is loaded, by the main session or the Developer.
+
+## Interaction policy
+
+Normal mode asks only for a missing required input, a genuinely ambiguous active project,
+or a mandatory write approval. Ask one question at a time unless a module says otherwise.
+
+When the user says `add to expectations: <note>` (or an unambiguous natural-language
+equivalent), append the note to the active project's `EXPECTATIONS.md` before continuing.
+Use `scripts/expectations-ledger.js` so the entry retains the supplied statement plus safe
+current context (stage/state, relevant project-relative artifacts, and known entity/field
+labels). Do not treat this as approval or silently change a mapping. Never record secrets,
+tokens, raw customer data, or raw source records; redact them if supplied and say so.
+
+Before writes, preserve the mandatory execution-plan approval gate. Read-only discovery,
+mapping, setup verification, code generation, and review happen before it.
+
+## Quick management import mode
+
+When `managementImportMode=quick`, select the platform adapter only after the deterministic
+source probe identifies a compatible platform. Quick mode is a bounded public-data import:
+the adapter's versioned `quick-mode.json` owns its source routes, entity graph, field matrix,
+and exclusions. Do not run agentic discovery, mapping, or project-specific code generation for
+the quick backend branch. Still run destination setup, application installation, Catalog-V3 and
+notification safety checks, execution approval, shared write runtime, crosswalks, and completion
+accounting. If no adapter qualifies, persist the unsupported-mode result and ask the user to
+select standard mode; never silently fall back.
+
+Halt only for missing/invalid required input, a manual action with no API, or a systemic
+failure/data-loss risk. A halt must persist the code, evidence, owner, and exact unblock
+action; never silently stop.
+
+## 1-click mode
+
+When explicitly requested by the user, record `automationMode=one_click` with
+`source=user` and apply the following. A missing mode or a `one_click` value recorded as
+`deterministic_inference`/`prior_artifact` is normal interactive mode and must not skip a
+checkpoint:
+
+- collect all still-missing intake values in one grouped request; then do not pause for
+  routine approvals;
+- record mapping and execution approvals as `approved`, `decidedBy=agent`; skipping a
+  pause without state is invalid;
+- for CSV/file-only runs, validate and accept the required sample preview as the agent;
+  without explicit user-authored one-click, pause for the normal mapping review, sample
+  preview validation, and execution approval;
+- default to a new isolated site unless an existing destination is explicitly supplied or
+  already pinned, but never default the new site's type (Headless, Studio or Harmony): ask it
+  in the grouped intake; choose website scope deterministically from discovered route families;
+- retry PATH/tool-resolution failures under the operator's compatible interactive login shell;
+  request required browser/network sandbox escalation and retry before calling it blocked;
+- retry the obvious recovery before stopping: aligned shell first for PATH/tool failures,
+  then the required escalation retry for sandboxed browser or network/API failures;
+- continue through the complete selected deliverable. In `management_and_website` mode that includes
+  frontend build, post-build gap analysis, bounded fix loop, and release receipt; when the
+  user selected facelift at intake, it also includes the separate post-clone facelift review;
+- before yielding, re-route. A 1-click run is only `completed` with
+  `completion/migration-completion.json`, or `blocked` with a typed durable blocker.
+
+Use the operator's compatible local Node/Yarn shell when recovering from a PATH or tool
+resolution failure. Machine-specific shell paths belong only in local, git-excluded agent
+instructions.
+
+**Repo-local interactive shell contract:** a PATH/tool-resolution failure on first attempt may
+mean the command ran under a plain, non-interactive shell that never sourced the operator's
+Node/Yarn profile. Resolve the operator's compatible login shell from the local environment or
+git-excluded agent instructions, verify that it is executable, and retry the exact same command
+through that shell in interactive login mode so the profile that resolves `node`/`yarn`/`npx`
+loads. Do not hardcode a machine-specific shell path in this public skill. Only escalate to a
+durable blocker if the compatible-shell retry itself fails.
 
 ## 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.
+- Never bypass a validator, approval-state update, verified notification mute, or
+  Catalog-V3 gate to make a stage appear finished.
+- `website` means frontend only; `management_and_website` means the integrated backend and
+  frontend migration. Never hand the integrated migration destination to the frontend skill
+  or create a second frontend site in that mode.
+- A Studio or Harmony destination (`targetSiteType`) is created and verified by
+  `rp-destination`'s coordinator and is never published, unpublished or handed to
+  `wix-headless-replatform`; its website and publication remain operator handoff items.
+- Do not implement a storefront manually when `wix-headless-replatform` is unavailable;
+  persist a blocker with the exact required runtime capability.
+- In management mode, still generate `website/handoff.*` after setup discovery so a later
+  storefront can start without repeating backend discovery.