--- name: rp-mapper description: >- Maps discovered source entities and fields to Wix targets and documents lossiness. Use when creating mapping-plan.md and mapping-summary.md after discovery. --- # rp-mapper Create a mapping plan from the discovered source schema into Wix entities and Wix data structures. ## Purpose This skill translates source entities and fields into Wix targets. It should define what each source record becomes in Wix, how fields transform, and where custom schemas or extended fields are required. ## Required inputs - `migrations//source-schema.json` - `migrations//source-profile.md` when available - any existing Wix target-model constraints supplied by the user Read **only** these canonical artifacts by default. Do not ingest the raw discovery dump (`migrations//data/...`) wholesale — it is platform-specific and large. Instead, when an entity's mapping is ambiguous, follow that entity's `rawFile` pointer in `source-schema.json` to open just that one raw file for verification. Skip entities whose `inUse` is `false` (advertised by the source but holding no records). ## Workflow 1. Read the source discovery artifacts. 2. Identify the target Wix entities for each source entity. 3. Define field-by-field mappings, including transformations and defaults. 4. Mark gaps where native Wix entities are insufficient. 5. Identify requirements for custom collections, extended fields, references, media handling, and rich content normalization. 6. Save the mapping plan. 7. Write a concise user-review summary after the plan is complete. 8. Pause for a mapping review checkpoint before downstream setup/codegen work begins. ## Artifact to create or update - `migrations//mapping-plan.md` - `migrations//mapping-summary.md` ## Minimum contents of the mapping plan Include for each source entity: - source semantics in this project, especially when the entity name is generic (`comment`, `item`, `entry`, `record`, `media`, `user`, etc.). State what the entity actually contains here, based on the discovered data, not just the route name. - target Wix entity or collection - primary key and deduplication strategy - field mapping table - transformation rules - validation rules - unresolved questions - setup implications for Wix-side configuration When a source entity is generic or overloaded, the mapping plan must name the concrete subtypes or usage contexts it observed. Examples: - `comment`: blog post comments, product reviews, page comments - `item`: order line items, catalog items, CMS rows - `media`: blog hero images, product gallery assets, downloadable files Do not leave a generic entity label unexplained if the discovered data shows multiple real-world meanings. ## Identity and deduplication rules Be explicit about the difference between a **source ID** and a **Wix target ID**. - Preserve the **source ID** in the migration artifacts, generated code, and any custom CMS collections needed for traceability and resume. - Do **not** assume native Wix entity IDs can be client-assigned or preserved. For most Wix APIs, the target ID is server-assigned. - When a target is a native Wix entity whose ID cannot be controlled by the client, the mapping plan must define a **crosswalk strategy**: store `sourceId -> targetId` in a dedicated CMS collection or equivalent durable artifact used for dedupe, resume, and relationship resolution. - The canonical collection name for that crosswalk is **`ImportCrosswalk`**. If older notes or mappings call it `MigrationRefs`, normalize them to `ImportCrosswalk` rather than inventing a second side table. - Only say an ID is "preserved" when the destination actually has a client-controlled field that stores the source ID. Otherwise say the source ID is **tracked** or **crosswalked**. ## Verifying Wix APIs Confirm exact Wix entity/collection/field names before mapping a source field onto them — never invent a Wix API or field name. - **When the Wix MCP is available, verifying at write-time is mandatory.** Verify enum **values**, not just names: every `Field.type` you assign must be a real member of the Create Data Collection `Type` enum. (Common trap: there is no `SLUG` type — a slug maps to a `TEXT` field. Never assign a guessed enum value and flag it `unverified`; resolve it or omit it.) - **When the Wix MCP is expected but missing, do not silently downgrade first.** First try to ensure the Wix MCP is installed/connected in the current runtime. If the environment supports connector/plugin install flows, use them. Otherwise halt to needs-user with exact instructions: install/connect the Wix MCP for Wix API docs/schema access, then resume this step. - **Fallback when no Wix MCP is available is degraded mode, not the default path.** Use it only when the user explicitly asks for a provisional draft without the Wix MCP, or when an upstream orchestrator explicitly routed this step in provisional mode. In that mode, rely on published Wix REST/SDK documentation and conservative, known-good names. Mark anything you could not verify as `unverified` in the mapping plan so a human confirms it before execution. ## Runtime policy Resolve ambiguous mappings using the documented default, record the decision and rationale under "Unresolved questions" in `mapping-plan.md`, and keep going. Known fidelity forks (e.g. comments anonymize vs. skip) should already be answered by the submission intake; apply those answers rather than re-asking. If a required input is truly missing, surface it as a blocker rather than silently guessing. If the Wix MCP is missing and this run was **not** explicitly authorized as provisional, halt instead of writing a lower-confidence mapping artifact. If the source entity name is generic but the observed data disambiguates it, record that disambiguation explicitly in the mapping plan. Do not force later stages to infer what "comments", "items", or similarly broad labels meant in this specific migration. ## Faithfulness ledger (detect lossiness here, early) The mapping stage is where lossiness and coverage gaps are *discovered*, so it is where they must be *recorded* — not at execute time, which is too late to do anything but report. Maintain a **faithfulness ledger** in `mapping-plan.md` listing everything that will not migrate cleanly, including: - fields/relationships flattened or dropped (e.g. hierarchy → flat), - entities skipped (e.g. gated PII), - **targets with no verified Wix primitive** — if Wix has a native entity, record that codegen must use an `unverified` native REST path and notify the RePlatform team about the missing writer. Use CMS only when no suitable native Wix entity exists, or when the native entity is rejected for fidelity/side-effect reasons. **Mandatory trigger — hierarchical source taxonomy → flat Wix target.** When a source entity carries `"hierarchical": true` (or any `parent` self-relation) in `source-schema.json` and maps to a flat Wix target such as Blog categories, you **must** write a faithfulness-ledger entry recording that the parent/child hierarchy is dropped on import, citing **FR-006**. This is not optional discipline: the flag exists precisely so the warning is data-driven. Do not map such a taxonomy without the ledger entry. (If hierarchy must be preserved, the alternative is a CMS-collection taxonomy with a `parent` reference field — note that trade-off in the ledger instead.) This ledger is the source the execution-plan report draws from to surface "what we won't do" to the user **before** consent (`rp-execute-import`). If it isn't recorded here, the user can't be warned there. ## Mapping summary for user review After `mapping-plan.md` is written, create `migrations//mapping-summary.md` as a short review artifact for the user. Its purpose is to make the mapping decision easy to review without forcing the user through the full plan. The summary should: - explicitly say that full details live in `mapping-plan.md` - list each in-scope source entity and its planned Wix target - call out the main gaps, lossy transformations, skipped entities, and `unverified` target paths from the faithfulness ledger - mention the biggest setup implications the user should know now (for example: required Wix apps, required CMS collections, crosswalk collection, media reachability caveat) - surface unresolved questions only when they materially affect whether the user should approve the mapping Keep it concise. The user should be able to decide "yes, this is the right migration shape" from this file alone, then consult `mapping-plan.md` only when they want detail. Recommended structure: - one-sentence purpose / pointer to `mapping-plan.md` - `Source -> Wix targets` - `Main gaps / lossiness` - `Important setup implications` - `Questions or risks to confirm` Do not restate full field tables or detailed transformation rules here unless a specific field-level issue is central to the approval decision. ## Mapping review checkpoint Once both mapping artifacts exist, stop and ask the user to review `migrations//mapping-summary.md`. The checkpoint should make clear: - this is a semantic review of what will be migrated where - the full technical detail remains in `mapping-plan.md` - downstream setup discovery and code generation will wait for acceptance Do not proceed to `rp-setup-discovery` or `rp-import-codegen` until the user accepts this mapping review checkpoint, unless the user explicitly asks to continue provisionally. ## Guardrails - Do not collapse multiple source concepts into one Wix field without documenting lossiness. - Call out data that cannot be migrated faithfully — record it in the faithfulness ledger above. - Do not describe a source entity only by a generic label when the observed data is more specific; name the concrete subtype(s) present in the project. - Keep business rules explicit so `rp-import-codegen` can implement them deterministically. - Do not produce a docs-only mapping artifact as the normal path when the Wix MCP prerequisite is missing. That mode must be explicitly marked provisional.