> **rp-execute-setup** — chapter 11 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-execute-setup/SKILL.md @ `main` > Raw bytes, no header: https://raw.githubusercontent.com/wix/skills/main/skills/wix-replatform/resources/rp-execute-setup/SKILL.md > Base for relative paths: https://raw.githubusercontent.com/wix/skills/main/skills/wix-replatform/resources/rp-execute-setup/ > Licence: MIT — https://spdx.org/licenses/MIT.html > > Bundled files (1), referenced from this skill's directory: > - `scripts/mint-token.sh` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-replatform/resources/rp-execute-setup/scripts/mint-token.sh > > Content © its authors, served unmodified. Takedown: https://github.com/DreambaseAI/skillsdocs/issues/new?labels=takedown&title=Takedown+request --- name: rp-execute-setup description: >- Verifies and provisions Wix-side setup required before import. Use after codegen when machine-readable setup artifacts must be validated or executed against the target site. --- # rp-execute-setup Verify that required Wix-side setup exists and is ready for import. ## Purpose This skill validates the prerequisites discovered by `rp-setup-discovery`. It can also drive the setup work when the environment and permissions allow it. ## Required inputs - `migrations//setup/setup-plan.json` - `migrations//setup/setup-requirements.json` - `migrations//execution/execution-manifest.json` - `migrations//config/wix.env` or equivalent environment values - access to the target Wix environment or to exported evidence from that environment Prefer the machine-readable setup artifacts above. Markdown setup summaries are secondary renderings for humans, not the primary execution contract. ## Config Prefer project-local config over ad hoc shell state. `config/wix.env` should exist before setup verification/provisioning and contain: ```bash WIX_SITE_STRATEGY= WIX_SITE_ID= WIX_AUTH_TOKEN= ``` `WIX_SITE_STRATEGY` is always required. `WIX_SITE_ID` is required before setup verification/provisioning begins. If the strategy is `new` and no site has been created yet, halt to needs-user and route back to the site-creation step rather than asking for an existing site ID. `WIX_AUTH_TOKEN` is the canonical Wix credential key for this project flow; for CLI-scaffolded headless sites it holds the site write credential (a CLI token sent as a Bearer token). **Never print secret values.** Mint the token without printing it to the transcript by running `scripts/mint-token.sh` from the migration project root: ```bash bash migrations//scripts/mint-token.sh ``` The canonical copy lives at `skills/replatform/resources/rp-execute-setup/scripts/mint-token.sh`. `rp-import-codegen` copies it into `migrations//scripts/` at scaffolding time — do not write it from scratch. The script reads `WIX_SITE_ID` from `config/wix.env`, calls `npx @wix/cli@latest token --site "$WIX_SITE_ID"`, captures stdout (token shape: `OauthNG.JWS...`), writes it directly into `config/wix.env` as `WIX_AUTH_TOKEN`, and prints only a char-count confirmation. Do NOT run the token command raw in a Bash tool call — it prints the credential to transcript. If `WIX_SITE_ID` is missing for a RePlatform `new site` + `headless` flow, the recovery path is the **Wix CLI headless scaffold** step defined in `replatform` → "Headless site creation" (`npm create @wix/new@latest headless`). The account-level Projects API is deprecated for this workflow. **Note:** the scaffold does not install Wix Stores — this skill (setup) is where Wix Stores and other required apps get installed (via the `wix-manage` skill / app-install path), then verified, before import. Treat `migrations//config/*.env` as secret-bearing once they may contain real values. Do not verify them with whole-file reads that echo contents into tool output. Only check existence plus `present` / `blank` / `missing` status for required keys. ## Workflow 1. Resolve the active project. 2. Read the machine-readable setup artifacts. 3. Verify each required app, collection, schema, field, and permission through the shared setup runtime contract. If setup requirements came from domain knowledge, preserve the originating `targetRef` in verification output so later execution warnings can be traced back to the selected entity guidance. 4. Record pass, fail, or blocked status for each item. 5. If execution is allowed, perform missing setup steps through the shared setup runtime and re-verify. 6. Save the verification results and setup execution artifacts. ## Execute the setup artifacts — do not re-derive setup from prose Setup execution should follow the approved machine artifacts and the shared setup runtime. It should not rebuild setup decisions from markdown or ad hoc reasoning when `setup/setup-plan.json`, `setup/setup-requirements.json`, and `execution/execution-manifest.json` already exist. This skill owns execution of those artifacts. It does not own redefining the setup plan or creating a separate setup approval checkpoint. Dry-run setup uses the same setup plan and setup executor as live setup. When `DRY_RUN` is enabled by config or `--dry-run`, every setup step must first be reduced to a structured intent describing the REST request, SDK operation, MCP tool call, or CLI command that live setup would use. The shared setup runtime then captures that intent, marks the step `planned_dry_run`, and must not invoke Wix MCP tools, Wix CLI commands, SDK calls, or fetch calls that access or mutate Wix account/site state. Do not override `DRY_RUN=true` with `--no-dry-run` for setup verification or provisioning unless the user has explicitly approved leaving dry-run for setup. Prefer to avoid that override entirely when a dry-run or plan/report can answer the question. The one allowed live action while a project otherwise remains in dry-run mode is the separate new-site creation step handled upstream by `replatform`; this skill must not treat that exception as permission to run live setup writes or live setup verification probes. Dry-run setup must not update `setup/setup-verification.json` in a way that claims a Wix capability, app installation, collection, or site exists. Write a separate dry-run setup report or clearly dry-run-scoped observations instead. ## Provisioning — exhaust programmatic options before declaring anything "manual" Default to provisioning via API. Do **not** label a requirement "manual" or "owner action" until you have confirmed no API can do it. The preferred contract is a **shared setup runtime** owned by `rp-target-wix`, executed against the machine setup artifacts produced upstream. This skill may use available Wix API/MCP surfaces as the transport beneath that runtime, but the contract at the RePlatform level is: - setup execution consumes machine setup artifacts - setup execution follows shared runtime behavior - setup provisioning is not re-planned live by the agent The approval gate is unchanged: no setup write before the user accepts the execution plan. If a helpful Wix tool surface is available in the runtime, it may be used beneath the shared setup runtime for verification or transport. If no such surface is available, do not treat that alone as a blocker; continue with the shared setup/runtime contract and verified `rp-target-wix` behavior, marking unverified items where needed. Only proceed in a docs-only/read-only posture when the MCP is genuinely unavailable and the step can still produce useful non-destructive output. Concrete mechanisms: - **Mute site notifications FIRST (spec 0012).** When the setup artifacts carry the `mute-site-notifications` requirement (always for `WIX_SITE_STRATEGY=new`; opt-in for existing sites), execute it **before every other setup write** — immediately after the target site is available and `WIX_AUTH_TOKEN` is minted, and before app installs, collection creation, or any other provisioning — so setup writes themselves cannot fire notifications. Use the `muteSiteNotifications` primitive from `rp-target-wix/lib/wix-writers.js` (VERIFIED 2026-08-04) with a project-identifying reason (`RePlatform migration — `); verify via `getSiteMuteState` → `muted: true` (verification method `status-read`; an idempotent re-mute is only a documented fallback, method `idempotent-recall`). Record the result in `setup/setup-verification.json` on the requirement at call time — status (`pass`/`fail`/`blocked`), timestamp, and verification method — like any other verified item; downstream reports read this recorded state, never infer it. **AUTH TRAP:** the endpoints accept user tokens only — the CLI-minted `OauthNG` site token works; an account API key gets an empty-body 403. **A failed mute is a blocker, not a warning:** the run halts to needs-user and never proceeds to import writes — no degraded mode, no continue-anyway. Never call `unmuteSiteNotifications` from this skill — unmute is an explicit owner request handled at the orchestrator level. Record the provision outcome through the standard `rp-telemetry` recorder like any other notable boundary (an `error` event with `error_code` on failure; the existing-site opt-in surfaces via the approval gate's `user_decision` event) — no new telemetry surface. - **Installing / enabling Wix apps (Blog, Members, etc.) IS automatable.** Use the App Installation API: 1. Pre-check with `POST /apps-installer-service/v1/app-instance/is-permitted-to-install` (read-only) to see whether the identity may install the app. 2. If permitted, install with `POST /apps-installer-service/v1/app-instance/install`. Body (all fields required — confirmed by live 400s): `{ appInstance: { appDefId, enabled: true }, tenant: { tenantType: "SITE", id: }, installType: "INSTALL_TYPE_SITE", appsInstallOptions: {} }`. (The `is-permitted-to-install` pre-check uses a *different*, oneof-based body and is informational only — if its validation fights you, skip it and rely on `/install`.) 3. List current state with `GET /apps-installer-service/v1/app-instances`. - **Ground `appDefId` from the official "Apps Created by Wix" table** (`/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix`), NOT from a docs *example* — e.g. the install-app example uses `1380b703-…`, which is **Wix eCommerce**, not Blog. Installing the wrong app on a live site is a real hazard; verify the ID maps to the app you intend. - **After installing Wix Stores, verify the catalog is V3 — before any Stores write.** Installing Stores does **not** guarantee Catalog V3: on a site scaffolded from the `blank` headless template, the install comes up **`V1_CATALOG`**, which the V3 Stores primitives cannot write to (verified the hard way on a live migration, 2026-07-30). Catalog version is fixed at provisioning — there is no in-place V1 → V3 switch. Check it with 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, re-check), or `V1_CATALOG` — record it as a **blocker** in `setup/setup-verification.json`, write nothing to Stores, and halt to needs-user. The prevention lives upstream of this skill (`replatform` → "Headless site creation": scaffold with `--site-template commerce`); the recovery is a user-approved replacement site, **never** a silently created one, and never a throwaway probe site. - **Wix Data / CMS collections (the `WDE0110: Wix Code not enabled` case).** Enable Wix Data by **installing the Wix Data app `appDefId e593b0bd-b783-45b8-97c2-873d42aacaf4`** via the App Installation API (same `/install` body shape as any other app; it also auto-installs a dependency app `1a711f05-2040-47df-a9f0-4f9cddb4c3c6`). Once installed, plain REST `POST /wix-data/v2/collections` creates **NATIVE** collections with no `WDE0110` — no code editor toggle, no custom app needed. **Verified live 2026-06-10** on a fresh free site (install → 200; collection create → 200 `collectionType: NATIVE`). - This is the preferred path. The older data-collections-extension app (authoring a custom app that declares collections) is now a **fallback** — only needed if you must declare collection schemas at install time, and it still can't express `REFERENCE` fields (add those after install via `create-field`). - Note: the standalone "Wix CMS" app (`appDefId 675bbcef-…`) is **not** installable (`is-permitted-to-install` → `false`) — do **not** use it; use `e593b0bd-…`. - **Optional import crosswalk CMS mirror.** Native Wix entities use local crosswalk state under `migrations//state/crosswalk/` for idempotency. Provision a native **`ImportCrosswalk`** collection only when the approved setup artifacts explicitly request a CMS mirror for existing-site seeding or site-local reference. After enabling Wix Data, create it with `POST /wix-data/v2/collections` and fields such as `entityType` (TEXT), `sourceId` (TEXT), `sourceStableKey` (TEXT), `targetId` (TEXT), `targetType` (TEXT), and `updatedAt` (DATETIME/TEXT). Do not provision this collection as the default native-entity idempotency mechanism. If upstream artifacts still call the optional mirror `MigrationRefs`, normalize them here rather than creating both collections. - **Genuinely manual (no API exists):** upgrading the storage plan, generating external-system credentials (e.g. a WordPress Application Password), and account-level billing. These are the only categories that may be reported as manual — and only after confirming no API covers them. ## Artifact to create or update - `migrations//setup/setup-verification.json` - `migrations//setup/review/setup-verification.md` - audit/report artifacts emitted by the shared setup runtime - dry-run request captures in `migrations//state/attempts/wix-request-captures.ndjson` when setup is run with dry-run enabled Stores live setup checks that require a probe record must use the shared rp-target-wix verification CLI, not ad hoc snippets. For subscription support, run: ```bash node skills/replatform/resources/rp-target-wix/scripts/verify-stores.js stores subscription-create \ --artifact migrations//setup/stores-subscription-verification.json \ --proposal-artifact migrations//setup/contract-ledger-proposal.json ``` Keep the JSON verification artifact and contract-ledger proposal alongside setup verification. The proposal is not itself shared product knowledge; the orchestrator must promote accepted proposal data into `rp-target-wix/domains/**/entities/*.json` in the same session or record a deferral reason. If cleanup fails, do not mark the probe as clean; preserve the warning and run the emitted `stores delete-probe` recovery command after permissions or target state are fixed. ## Verification output format For each requirement capture: - requirement name - expected state - observed state - status: passed, failed, blocked - remediation needed The machine-readable verification artifact should also preserve: - stable requirement ID - checkpoint/provisioning step ID when applicable - verification evidence reference - automation mode: `automatable | manual | blocked | unverified` ## Optional media reachability verification When the migration includes media import by source URL, check whether discovered media URLs are publicly reachable by Wix. If the source URL is `localhost`, `127.0.0.1`, or a private-only host, mark **media import** as `blocked` or `deferred`, but do not block unrelated non-media entities. This is optional setup and, as far as we know today, affects only Wix Media import. Record the user's chosen path in `setup/setup-verification.json` and render it into the review markdown: - **Tunnel media URLs:** ask the user to expose the source through a public HTTPS tunnel, then use that URL for `WP_BASE_URL` / `SOURCE_URL` or rewrite media URLs to that base. - **Skip/defer media:** proceed only if the execution plan clearly says media and any media-dependent references (hero images, galleries, downloads) will be skipped or deferred. Ngrok quick setup for macOS: ```bash brew install ngrok ngrok config add-authtoken "" ngrok http 8090 export WP_BASE_URL=https://.ngrok-free.app ``` ## Runtime policy Split this skill's work by side effect: - **Verification is read-only** — checking what's installed, what's missing, and what's genuinely manual. It runs **before** the execution-plan acceptance gate and feeds the plan. - **Provisioning writes** — installing apps, enabling Wix Data (via the data-collections enabler), creating collections, adding fields — happen **only after** the user accepts the execution plan. **No site write before acceptance.** Once accepted, the "Migrate" consent covers the individual writes, so don't re-prompt per app/collection. Halt to needs-user only for genuinely manual items (storage-plan upgrade) or a missing/invalid credential. The execution behavior itself should come from the shared setup runtime and approved setup artifacts, not from improvised per-run logic in this skill. ## Guardrails - Never report setup as complete without evidence. - Prefer machine-readable setup verification artifacts over prose-only reporting. - Before marking an item blocked or manual, confirm no API can perform it (see Provisioning above). Reserve "manual" for storage/billing/external-credential steps. - If credentials or permissions are genuinely missing, mark the item blocked and state the exact API that was refused and why. - Do not start import execution from this skill. - Do not reinterpret setup requirements from markdown when machine artifacts exist.