> **rp-setup-discovery** — chapter 14 of 20 in [wix/skills](https://skillsdocs.com/wix/skills). > > Book (all chapters, one file): https://skillsdocs.com/wix/skills.md > Machine manifest: https://skillsdocs.com/wix/skills/.well-known/agent-skills/index.json > Install the book: `npx skills add wix/skills` > Upstream: https://github.com/wix/skills/blob/main/skills/wix-replatform/resources/rp-setup-discovery/SKILL.md @ `main` > Raw bytes, no header: https://raw.githubusercontent.com/wix/skills/main/skills/wix-replatform/resources/rp-setup-discovery/SKILL.md > Base for relative paths: https://raw.githubusercontent.com/wix/skills/main/skills/wix-replatform/resources/rp-setup-discovery/ > Licence: MIT — https://spdx.org/licenses/MIT.html > > Content © its authors, served unmodified. Takedown: https://github.com/kyleledbetter/skillsdocs/issues/new?labels=takedown&title=Takedown+request --- 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. ## 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//mapping/mapping-plan.json` - `migrations//mapping/review/mapping-gaps.json` - `migrations//mapping/review/mapping-summary.md` - `migrations//orchestration/approvals.json` - any Wix environment constraints or destination account details provided by the user ## 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. 7. Write a setup artifact that downstream execution can verify. ## Artifact to create or update - `migrations//setup/run.json` - `migrations//setup/setup-plan.json` - `migrations//setup/setup-requirements.json` - `migrations//setup/setup-blockers.json` - `migrations//setup/llm-handoff.json` - `migrations//setup/review/setup-summary.md` - `migrations//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 "" ngrok http 8090 export WP_BASE_URL=https://.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. (Common trap: there is no `SLUG` type — a Wix slug is a `TEXT` field.) - 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 (spec 0012) 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 owner explicitly opted in with `WIX_MUTE_NOTIFICATIONS=on`. Under the existing-site default (`off`), emit no requirement. 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 — `). 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.) ## Crosswalk authority and CMS mirror Local files under `migrations//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. - 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.) - When the migration carries a product catalog, emit a **`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` (it is provisioned by scaffolding the site from the `commerce` template — see `replatform` → "Headless site creation"). A Stores install alone does not imply V3; a `blank`-scaffolded site comes up `V1_CATALOG` and cannot be converted, so this must be a first-class requirement rather than an assumption. - 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.