---
name: rp-setup-discovery
description: >-
  Derives Wix environment prerequisites (apps, collections, schemas) from an approved
  mapping plan. Use after mapping review and before import code generation.
---

# rp-setup-discovery

Determine the Wix-side setup required before import can run safely.

## Declaring user-defined extended fields

When a mapping needs a source-only value on a native Wix record, declare it as a setup
requirement rather than letting a writer improvise one. The requirement and the step that
executes it are a fixed pair:

- the requirement is `kind: "extendedFieldSchema"` in `setup/setup-requirements.json`, carrying
  `schemaKind`, `targetRef`, `fqdn`, `namespace: "_user_fields"`, and its `fields`;
- the plan step that provisions it is **`provision-extended-fields`** in `setup/setup-plan.json`.

Emit both or neither. A requirement with no matching step provisions nothing, and every writer
that needs those fields then refuses its write — correct, but the run fails late and for a
confusing reason. `rp-execute-setup` fails closed on that mismatch rather than proceeding.

Supported targets, and nothing else:

| Target | `schemaKind` | `fqdn` / surface | Types |
| --- | --- | --- | --- |
| eCommerce Order | `data-extension-schema` | `wix.ecom.*.order` | `string` (needs `maxLength`) |
| Product | `data-extension-schema` | `wix.stores.catalog.*.product` (filterable) | `string` |
| Contact (default) | `data-extension-schema` | `wix.contacts.*.contact`, `contactWriteSurface: "contacts-v5"` | `string` |
| Contact (legacy, explicit opt-in only) | `crm-contact-extended-field` | `contactWriteSurface: "contacts-v4"`, no `fqdn`/`namespace`; fields carry `displayName` + `dataType` | `TEXT` |

Checkout, Bookings, Booking Services and nested order subrecords (`extensionPoint`) are refused
before any network call — route such fields to CMS. Use `permissionsPreset: "migration-internal"`
(Wix users and apps read, Wix users write, no visitor access); visitor exposure is a manual
dashboard change by the site owner afterwards, never a setup default. Never emit both contact
surfaces for one field, and never plan a V4 fallback for a V5 contact field.

## Purpose

This skill analyzes the approved mapping artifacts and derives environment prerequisites
such as installed apps, SMC collections, extended-fields schemas, references,
permissions, and any other target-system configuration dependencies.

## Required inputs

- `migrations/<project>/mapping/mapping-plan.json`
- `migrations/<project>/mapping/review/mapping-gaps.json`
- `migrations/<project>/mapping/review/mapping-summary.md`
- `migrations/<project>/orchestration/approvals.json`
- any Wix environment constraints or destination account details provided by the user

For `managementImportMode=quick`, replace the mapping inputs above with
`migrations/<project>/quick-mode/plan.json`. Its `requiredWixCapabilities` and entity graph are
the setup authority. Generate the same setup artifacts and standing notification/Catalog-V3
requirements; do not demand a mapping plan or ask an agent to infer additional quick entities.
When the plan includes blog posts, add an automatable dedicated fallback Blog author member,
persist its ID as `WIX_BLOG_FALLBACK_MEMBER_ID`, and disclose the attribution policy in the
setup summary. This is mandatory setup, never a user decision or import blocker.

Generate the quick-mode setup artifacts deterministically:

```bash
node skills/wix-replatform/resources/rp-setup-discovery/scripts/quick-setup-plan.js <projectDir>
```

The adapter declares its entity graph and capabilities; this shared generator owns universal
destination setup policy and must not infer additional import entities.

## Workflow

1. Confirm the mapping review checkpoint has been accepted, then read the mapping plan and
   mapping summary and identify every non-native requirement.
2. For mapped entities with `targetRef`, load compact domain/entity summaries through
   `rp-target-wix/scripts/domain-knowledge.js summarize-entities` and include
   `wixAppsRequired`, `setupRequirements`, target classification, and write verification
   level in setup analysis.
3. Determine which Wix apps must be installed or enabled.
4. Determine which SMC collections must exist.
5. Determine which extended-fields schemas, references, enums, or validation rules must exist.
6. Capture dependency ordering where setup steps depend on each other. Every setup step
   declares its canonical `entityRefs`. Where imports consume a setup-produced value,
   declare optional `referenceKeys: [{ ref, sourceStableKey, paths: string[] }]` for that
   step. Each ref must be in its `entityRefs`; keys come from the reviewed source mapping,
   and paths name the exact dependent payload fields. Never invent a target ID in the plan.
   Keep every setup-produced dependency `task-complete`, even when its target value is
   used on individual records. List a ref only when this setup step writes it. An entity an
   import task writes (for example the delivery profile, when the mapping imports shipping
   zones) is owned by that import: a read-only prerequisite check on it, such as
   "the default delivery profile exists", declares `entityRefs: []`. Codegen refuses a
   step that claims an import-owned ref (`setup_step_claims_import_entity`). A step that runs
   a named executor lists what that executor writes: `create-cms-collections` declares
   `entityRefs: ["cms/collection"]`. Setup refuses the plan otherwise
   (`plan_step_entity_refs_missing`).
7. Write a setup artifact that downstream execution can verify.
8. Bind `setup/setup-plan.json` to the mapping plan it was derived from (a no-op when the
   project has no plugin coverage):

   ```bash
   node skills/wix-replatform/scripts/cms-fallback.js stamp-plan --project-dir <project> --plan setup
   ```

   It copies `mapping-plan.json` `inputs.cmsFallbackDigest` into `setup-plan.json`
   `inputs.cmsFallbackDigest`. With no plugin coverage it prints `stamped: false` and exits 0;
   a plugin-covered project whose mapping plan lacks the digest still fails. The router treats a setup plan without it, or with a different
   one, as stale (`setup_plan_stale_cms_fallback`) and routes back here before any setup or
   import step. Create CMS collections only for capabilities the mapping plan maps to CMS: a
   recognized capability whose CMS fallback is pending or declined gets no collection.

## Artifact to create or update

- `migrations/<project>/setup/run.json`
- `migrations/<project>/setup/setup-plan.json`
- `migrations/<project>/setup/setup-requirements.json`
- `migrations/<project>/setup/setup-blockers.json`
- `migrations/<project>/setup/llm-handoff.json`
- `migrations/<project>/setup/review/setup-summary.md`
- `migrations/<project>/orchestration/checkpoints.json`

Treat `mapping/review/mapping-summary.md` as the user-facing statement of intent and
`mapping/mapping-plan.json` as
the detailed contract. If they materially disagree, halt and send the workflow back to
`rp-mapper` to correct them before deriving setup requirements.

## Minimum contents

- required Wix apps
- local crosswalk authority and optional CMS mirror requirements
- required collections and schemas
- required field definitions
- permissions or access prerequisites
- setup order
- manual steps vs. steps that can be automated
- verification criteria for each requirement

## Optional source reachability setup for media

If the mapping imports media by URL and the source profile shows `localhost`,
`127.0.0.1`, or another private-only source URL, add an optional setup note for media
reachability. This is **not** a blocker for non-media entities and should not be framed as
a required Wix-side app/setup item. As far as we know today, it only affects Wix Media
import because Wix's import-from-URL API fetches files from Wix servers.

Offer two options in `setup/review/setup-summary.md` and preserve the machine-readable
effect in `setup/setup-blockers.json` or `setup/setup-requirements.json`:

- Expose the local source through a public HTTPS tunnel before live media import.
- Skip/defer media import for the first live run and continue non-media entities.

For ngrok, include:

```bash
brew install ngrok
ngrok config add-authtoken "<YOUR_AUTHTOKEN>"
ngrok http 8090
export WP_BASE_URL=https://<id>.ngrok-free.app
```

Tell the user to use the HTTPS forwarding URL as `WP_BASE_URL` / `SOURCE_URL`, or ensure
generated code rewrites source media URLs from the local base URL to the tunnel base URL.

## Verifying Wix APIs

Confirm that the apps, collections, field types, and references you require actually
exist in Wix with the names/types you state — never invent them.

- Verify at the moment you write the requirement; do not defer it. Verify **enum
  values**, not just names: confirm each `Field.type` against the Create Data Collection
  schema. (`SLUG` **does** exist in that enum, documented for dynamic page URLs. Use `TEXT` for
  a preserved source slug held as identity/SEO data and `SLUG` when the target generates the
  dynamic-page URL from it — never record `SLUG` as a type that does not exist.)
- If a Wix tool surface such as Wix MCP is available, use it as a fast verification aid.
- If no Wix tool surface is available, rely on `rp-target-wix`'s verified contracts plus
  published Wix REST/SDK documentation and conservative, known-good names, and mark the
  requirement `unverified` so a human confirms it before `rp-execute-setup` runs.

## Standing requirement: mute site notifications

Emit a **`mute-site-notifications`** requirement into `setup/setup-plan.json` and
`setup/setup-requirements.json` whenever mute is in effect:

- `WIX_SITE_STRATEGY=new` — **always**, as a standing rule keyed on the strategy value
  alone. Not derived from mapping decisions, domain knowledge, or agent judgment, and not
  conditional on `WIX_MUTE_NOTIFICATIONS` (for new sites the mute is unconditional).
- `WIX_SITE_STRATEGY=existing` — only when the operator answered **mute** at intake
  (`notificationMute=on` in `orchestration/decisions.json`, mirrored as
  `WIX_MUTE_NOTIFICATIONS=on`). For `off`, emit no requirement. There is no default: an
  unanswered existing site is an intake gap, so stop and route back to intake rather than
  emitting artifacts. Read the answer through `lib/notification-mute.js`
  `readNotificationMute`; the router refuses a plan whose mute step disagrees with it.

Requirement contents: severity **blocker**, automation mode `automatable`, ordered
**first among setup writes** (before app installs, collection creation, and any other
provisioning), executed via the `muteSiteNotifications` primitive in
`rp-target-wix/lib/wix-writers.js` (VERIFIED 2026-08-04) with a project-identifying
`reason` (`RePlatform migration — <project>`). Verification criterion:
`getSiteMuteState` returns `muted: true`. Auth note for the requirement: the call must
use the CLI-minted site token (`WIX_AUTH_TOKEN`) — an account API key gets 403.

**Config validation (fail fast):** `WIX_MUTE_NOTIFICATIONS=off` together with
`WIX_SITE_STRATEGY=new` is a validation error — halt with the config conflict recorded
rather than emitting artifacts. (`rp-import-codegen` re-validates the same rule.)

## Wix site locale (currency, time zone, language, locale)

Any migration into Wix needs the destination site's payment currency, time zone and language to match the
business (a Wix price carries no currency of its own). Emit the **`import-site-locale`** requirement and
step as a pair by running, after you
write `setup/setup-plan.json` and `setup/setup-requirements.json` and **before** `cms-fallback.js stamp-plan`:

```bash
node skills/wix-replatform/scripts/site-regional.js emit <project>
```

It places the entity after notification safety and before every app install or other setup write, and copies
all planned entity refs plus their audited money/wall-clock/neutral classifications into the requirement.
Missing source locale data remains a blocker rather than an exemption. Never hand-write either half;
`rp-execute-setup` fails closed when only one exists. `quick-setup-plan.js` does the same for quick runs. What
the entity may write, and when it asks the owner, is decided at execution time. Every import task builds on it.

## Crosswalk authority and CMS mirror

Local files under `migrations/<project>/state/crosswalk/` are the durable
`sourceId -> targetId` authority for native Wix entities. Do not make CMS setup a minimum
requirement for native-entity idempotency.

Create/provision CMS **`ImportCrosswalk`** only when the approved mapping plan explicitly
requests a CMS mirror (`cmsMirror: "download" | "upload" | "download-and-upload"`). The
mirror is compact site-local reference data and a pre-execution seed source for
existing-site flows when valid local crosswalk state does not already exist. Add a CMS
quota warning whenever a mirror is requested.

If older artifacts call the optional mirror `MigrationRefs`, normalize it to
`ImportCrosswalk` and call out the rename in the artifact so downstream setup/codegen
share one contract.

## Classifying manual vs. automatable

Do not assert "manual" / "cannot self-provision" by assumption — check the API surface.

- Any task that writes, adopts or depends on a `stores/*` entity (and so every order, which
  depends on `stores/product` and `stores/coupon`) needs an `install-wix-stores` step in the
  setup plan, even when the products themselves are adopt-only. `lib/app-requirements.js` is
  the machine-readable list; dependency readiness blocks those tasks with
  `app_install_step_missing:wix-stores` when the step is absent.
  A passed receipt is not enough: the step's check must be an `installed-apps-read` of the
  Stores app id with `installed: true`, otherwise the task is blocked with
  `app_install_not_read_back:wix-stores` and setup reruns (a receipt from an older installer
  that recorded an install response, or another app, never satisfies it).
- A task that writes `stores/review` also needs an **`install-wix-reviews`** step, and one
  that writes `stores/back-in-stock-request` needs **`install-wix-back-in-stock`** followed by
  **`start-back-in-stock-collection`** (turns on "Notify When Available"; emit it only when
  the source has requests). `lib/app-requirements.js` lists both apps; the collection step is
  read back from the Back in Stock settings. Both are automatable.
- Any other Wix app the source needs is a step `{ "id": "<unique id>", "kind": "installApp", "appDefId": "<app id>" }`;
  no executor change is needed. On a Harmony site two apps that add the same pages (Stores and
  Bookings) cannot both install: the earlier step wins and the later one is deferred (see
  rp-execute-setup), so list the more important app first.
- Enabling a Wix app (Blog, Members, etc.) **is** automatable via the App Installation
  API; classify it automatable and cite the method. (Common trap: do not mark Blog or
  Members "cannot self-provision" — both are installable via the API.)
- Catalog V3 is guaranteed at provisioning regardless of scaffold template
  so a Wix Stores install on a site this
  run created needs no separate catalog-version requirement — do not emit one. This
  guarantee does not extend to an existing site this run did not create: when
  `WIX_SITE_STRATEGY=existing` and the migration carries a product catalog, still emit the
  **`stores-catalog-v3` requirement** alongside the Wix Stores app install — expected state
  `catalogVersion: V3_CATALOG`, verified read-only via
  `GET https://www.wixapis.com/stores/v3/provision/version`, severity **blocker**,
  automation mode `automatable`. A pre-existing site's catalog version predates this
  guarantee, so it must still be confirmed rather than assumed (see `rp-execute-setup` →
  "A `V1_CATALOG` verdict is terminal here").
- Creating CMS collections is automatable; enabling Wix Data itself is automatable by
  installing the **Wix Data app `appDefId e593b0bd-b783-45b8-97c2-873d42aacaf4`** via the
  App Installation API, after which `POST /wix-data/v2/collections` creates NATIVE
  collections with no `WDE0110` (verified live 2026-06-10; see `rp-execute-setup`).
- Only storage-plan upgrades, external-system credentials, and account billing are
  genuinely manual. Mark something manual only after confirming no API covers it.

## Runtime policy

This phase is deterministic planning work. It does not create a second approval gate.
`setup/review/setup-summary.md` is supporting execution-planning context, not a separate
user approval checkpoint.

Verify names and enums rather than emitting `unverified` by default. Classify
automatability by checking the API surface (see above), not by assumption. If a direct
verification aid is unavailable, use the documented fallback and mark the requirement
`unverified` so downstream steps surface it before execution.

## Guardrails

- Separate required setup from optional optimizations.
- Avoid embedding import logic here; this file is about prerequisites.
- Be explicit about which requirements come from which mapping decision.
- Do not guess setup names or enum values when you cannot verify them. Mark them
  `unverified` and surface the risk before execution.

## Field-preservation compatibility

Resolved custom-field decisions specify concrete types, limits, permissions and source/parent linkage. Admit extended fields only under the existing Orders/Products/Contacts string/TEXT predicates; root-entity storage, `_user_fields`, migration-internal permissions, contacts-v5 default and explicit contacts-v4 choice still apply. Unsupported types/entities/subrecords use precisely bound CMS. Use the automated create-cms-collections requirement. Read compatible existing field types, reference metadata and permissions before reuse; an ID hit or 409 is insufficient. Conflicts return to mapping/setup recovery without delete/recreate or visitor exposure. Preserve absent-source and retention rules.
