@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-replatform/resources/rp-mapper/SKILL.md

@@ -1,947 +0,0 @@
----
-name: rp-mapper
-description: >-
-  Maps discovered source entities and fields to Wix targets and documents lossiness. Use
-  when creating machine-readable mapping artifacts and review markdown 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/<project>/source-schema.json`
-- `migrations/<project>/source-profile.md` when available
-- `migrations/<project>/orchestration/checkpoints.json`
-- `migrations/<project>/orchestration/decisions.json`
-- `migrations/<project>/discovery/source-coverage.json` (capabilities discovery could not capture)
-- 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/<project>/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).
-
-### Adapter-supplied hints in `sourceMeta`
-
-A source adapter may pre-fill part of the mapping when it recognizes the source format. Two
-`sourceMeta` keys carry that, and both are optional — a schema without them maps exactly as
-before:
-
-- **`sourceMeta.mappingHints[]`** (`{ column, wixTarget, matchedAlias }`) — an **advisory**
-  pre-fill, e.g. from a recognized vendor's CSV profile. Seed the corresponding
-  `fieldMappings[]` entries from it so the user reviews and corrects instead of authoring from
-  scratch, and record `decisionProvenance: source_platform_rule`. It is never authoritative:
-  the source's own field list still governs, and every hint still passes through the mapping
-  review checkpoint.
-- **`sourceMeta.drift.unmappedColumns[]`** — real source columns the adapter's profile did not
-  recognize. Each one must be explicitly mapped or explicitly recorded as skipped; leaving
-  them unaddressed is how a stale profile turns into silently dropped data.
-
-In addition to the project artifacts above, consult the relevant bundled adapter resource
-when the mapping depends on platform behavior that should not be guessed:
-
-- source-side read/entity semantics from `wix-replatform/resources/rp-source-<platform>/SKILL.md`
-- Wix target constraints and domain behavior from `wix-replatform/resources/rp-target-wix/SKILL.md`
-- Wix target entity suitability from
-  `wix-replatform/resources/rp-target-wix/scripts/domain-knowledge.js`
-
-Treat those adapter resources as the authoritative home for platform knowledge. Do not
-copy source/Wix behavioral rules into the mapping plan as if they originated there; cite
-and apply them there.
-
-## Read-back field contract before mapping approval
-
-For the gated Wix targets `order`, `member`, `contact` and `product`, every field-mapping row
-must declare the exact `sourcePaths[]` it reads, canonical `writePath`, and `readPath` or a
-specific `unverifiableReason`. Write array positions as `[]`. A populated `false` or `0` is
-real data. In `mapping/entity-decisions/<entity>.json`, account for every populated source leaf
-and intended target path with `fieldDispositions[]`: `{ kind: source | intended, path,
-status: mapped | notMigrated, mappingRef }`. A mapped disposition names the actual mapping-row
-ID or index; it cannot claim a path that row does not read or write.
-
-Prepare a pure project-local module exporting `buildWrite(record)` from the mapping transforms;
-it makes no request or write and is the same builder the generated importer will reuse.
-Use an existing complete extract, or obtain it through the source adapter's read-only extraction
-path before the review. These commands run from the installed skill directory:
-
-```sh
-node scripts/read-back-gate.js contract <projectDir> --entity <entity>
-node scripts/read-back-gate.js inventory <projectDir> --entity <entity> --extract <extractPath> --builder <builderModule> --source-key id
-node scripts/read-back-gate.js validate <projectDir> --entity <entity>
-```
-
-`contract` merges the checked-in intended fields, projection and domain digest into the same
-entity decision's `readBackContract`; do not invent or relax that contract. `inventory` streams
-NDJSON or a JSON array once and stores only source IDs, paths and counts in
-`execution/read-back-inventory/<entity>.json`. A dotted source key is supported. Missing extracts
-report `not-run`, never a pass. Exit `2` requires correction; before approval the only permissible
-unresolved validation item is the missing identified approval for an explicitly reviewed
-`notMigrated` path. All other contract, mapping, history and inventory failures must be fixed.
-
-Before any Wix write, request mapping approval with the exact current SHA-256 references from
-`lib/read-back-contract.js` `bindings(projectDir, entity)` for **all four** artifacts:
-`mapping/mapping-plan.json`, `mapping/entity-decisions/<entity>.json`,
-`mapping/mapping-resolution.json` and `execution/read-back-inventory/<entity>.json`.
-The review shows left-out paths and affected record counts, never source values. Record approval
-through the existing mapping user action so both answer entrypoints use the shared identified
-approval writer. Populated omissions require a named signed-in human; explicit 1-click mode
-cannot approve them automatically. After approval, rerun validation; it must pass before writes
-and on every resume. Changes to any pinned artifact require fresh review. A previously attempted
-unresolved path or observed loss cannot become an approved omission. Approved omissions produce
-a separate merchant-acknowledgement action that must be completed before launch.
-
-For every other target entity, declare `verificationKind` and a concrete `reason` through
-`lib/read-back-gate.js`'s `declaration`; it is outside these four field gates and must never
-be described as having passed them.
-
-## Deterministic first — resolve before you reason
-
-**Do not author field mappings by hand when a vendor overlay already knows them.** Run the
-deterministic resolver first and let it do the mechanical join; your judgement is needed only for
-what it cannot decide.
-
-```
-node scripts/resolve-mapping.js --fileset <migrations-root>/<project>/data/csv-discovery/fileset.json \
-  --out <migrations-root>/<project>/mapping
-```
-
-It joins three inputs that are all already data — the header set discovery actually observed, the
-vendor overlay's `columnMap`, and `rp-target-wix`'s `lib/wix-target-spec.js` — and writes
-`mapping/mapping-resolution.json` plus `mapping/mapping-residue.json`. Exit code `2` means blocked:
-a required Wix input is unfilled, or an overlay names a canonical field that does not exist.
-
-What it decides, so you don't:
-
-- **which column feeds which canonical field**, and via which alias (recorded for review)
-- **which columns nothing claims** → `residue.unmappedColumns`
-- **which mapped columns have no Wix home**, with the declared reason → `residue.unsupportedTargets`
-- **which required Wix inputs nothing feeds** → `residue.unfilledRequired` (a blocker)
-- **which overlay entries reference an absent column** → `overlayDrift` (the profile is stale)
-- **which entities arrive by derivation** rather than by a column → `derivedEntities`, including
-  `requiresFaithfulnessLedgerEntry` when the source taxonomy is hierarchical
-
-**Your job is `residue`, and only `residue`.** Each entry needs an explicit decision — map it to a
-canonical field, or record it as intentionally skipped with a reason. Leaving an entry undecided is
-how a stale overlay turns into silently dropped data.
-
-Two rules keep this honest:
-
-- **The header row read at discovery time is authoritative, not the overlay.** An overlay can only
-  claim columns that actually exist; a column it does not know is surfaced, never dropped.
-- **When you resolve a residue entry that the overlay *should* have known, fix the overlay** —
-  `rp-source-csv/vendors/<vendor>.json` plus a header fixture in `tests/fixtures/csv/headers/`. That
-  is a data edit with no skill-logic change, and it means the next run resolves it deterministically
-  instead of asking a model again. A mapping decision made twice is a missing overlay entry.
-
-### Do not regenerate the payload builder
-
-`rp-target-wix/lib/wix-build.js` turns a canonical record into a Wix Stores V3 create body
-deterministically, and `lib/wix-target-spec.js` declares every field, constant and trap it relies
-on. This layer is **vendor-independent** — Shopify, WooCommerce, Magento and BigCommerce all
-converge on it — so codegen must **vendor and call it**, exactly as the reader vendors `csv-parse.js`.
-Do not emit a per-project `to-wix.js` re-deriving money objects, slug sanitization, choice-by-name
-variant references, or the empty `physicalProperties` trap. Those are settled, tested, and
-regression-locked against 220 payloads from two live-verified imports
-(`tests/mapping/wix-build-oracle-test.js`).
-
-The spec also settles the one price decision that recurs on every vendor: see
-`STORES_V3_TARGET.priceResolution`. A (regular, sale) pair is **resolved** into Wix's
-`actualPrice`/`compareAtPrice`, not mapped field-for-field — getting it backwards silently
-overcharges every discounted product.
-
-## Workflow
-
-1. Read the source discovery artifacts.
-2. **Run the deterministic resolver** (above) and read its residue.
-3. Identify the target Wix entities for each source entity using the domain knowledge
-   reader first. Start from `sourceMeta.candidateTargetRefs[]` when discovery supplied it;
-   otherwise run `domain-knowledge.js resolve-source`; use semantic reasoning only when no
-   candidate exists and record `unverified` confidence.
-4. Decide the resolver residue only, then define any remaining transformations and defaults.
-5. Mark gaps where native Wix entities are insufficient — the resolver's `unsupportedTargets`
-   already names them with reasons; carry those into the faithfulness ledger rather than restating.
-6. Identify requirements for custom collections, extended fields, references, media handling, and rich content normalization.
-   Every `extendedFields` write needs a matching `kind: "extendedFieldSchema"` setup requirement
-   with compact field intents (`key`, `fieldType`, `maxLength`, `permissionsPreset:
-   "migration-internal"`), never hand-written JSON Schema. Migration-owned fields use
-   `_user_fields`. Admitted targets: orders, products, and contacts (default `contacts-v5`; legacy
-   `contacts-v4` only by explicit choice). Other objects and nested subrecords go to CMS. Provisioning
-   a field does not decide whether a source field may be kept; that is a separate retention decision.
-7. Save the mapping plan, including the reviewed dependency associations below.
-8. Detect authored `blockedSourceDependencies` on the selected target entities, aggregate them
-   by `sourceEntityRef`, and write the blocked-data request state and review artifact below.
-9. Write a concise user-review summary after the plan is complete.
-10. Pause for a mapping review checkpoint before downstream setup/codegen work begins.
-
-## Artifacts to create or update
-
-- `migrations/<project>/mapping/run.json`
-- `migrations/<project>/mapping/mapping-plan.json`
-- `migrations/<project>/mapping/entity-decisions/<entity>.json`
-- `migrations/<project>/mapping/llm-handoff.json`
-- `migrations/<project>/mapping/review/mapping-gaps.json`
-- `migrations/<project>/mapping/review/mapping-plan.md`
-- `migrations/<project>/mapping/review/mapping-summary.md`
-- `migrations/<project>/mapping/review/blocked-data-requests.md`
-- `migrations/<project>/state/blocked-data-requests/<sourceEntityRef-slug>.json`
-- `migrations/<project>/orchestration/checkpoints.json`
-- `migrations/<project>/orchestration/approvals.json`
-
-## Target dependency associations
-
-For every target dependency consumed by an import, emit
-`dependencyBindings: [{ ref, censusIds: string[] }]` in `mapping/mapping-plan.json`.
-Use canonical `domain/entity` refs and every contributing decision row in the current
-discovered census, including excluded rows. Entity decisions retain their explicit
-`targetRef` and `censusIds`, or the census's implicit `entity:<sourceEntity>` link.
-Show these associations in the mapping review. Missing, ambiguous, duplicate or incomplete
-associations return to mapping; never infer a target from a plugin name or a comment.
-
-An excluded dependency is not ready merely because its entity was omitted from the plan.
-Readiness uses the existing census reconciliation and its current identified human approval.
-Every contributing row must be excluded and owner-approved for a whole target ref to be
-`excluded-approved`. Mixed planned/excluded contributions remain mixed. Agent/provisional
-acceptance and finalized-run review do not authorize new writes.
-
-When a specific dependent field may be omitted or must defer for an excluded contribution,
-put `dependencyFieldRules: [{ dependentRef, dependencyRef, path, action: "omit" | "defer" }]`
-on that contribution's existing census-linked mapping gap. Render the exact rules in the
-existing review and bind them to its existing hash-based approval. Entity exclusion alone
-never authorizes dropping a field; absent or stale approval defers the affected record.
-
-Shipping/tax setup prerequisites remain whole-task prerequisites. Map a single source
-shipping line's title, cost and available delivery details. More than one line defers the
-order with `order-multiple-shipping-lines` and a blocker gap. Select reference omission or
-verified setup references only from the bundled field-level verification conclusions;
-unverified shipping/tax fidelity keeps the affected order deferred. Never invent target
-IDs, combine source lines without an approved disposition, or backfill existing orders.
-
-## Blocked source dependencies
-
-Read only authored `blockedSourceDependencies[]` from selected target entity knowledge; never
-infer a request from `db-only`, `admin-page-only`, or another channel by itself. Use the shared
-`lib/blocked-data-requests.js` builder to aggregate one request per `sourceEntityRef`, appending
-all dependent target entity/field rows. Resolve each source entity's `blocked[].fulfillment`
-through `rp-source-wordpress/lib/blocked-data-handlers.js`; offer it only when its fixture
-self-test passes. `structure-bridge-plugin` (wix-wp-plugin-v2) has no
-manifest or readiness flag to check beyond that -- authorization is live (denylist +
-`DESCRIBE`) at request time, not a build-time gate. This readiness check is the only
-thing this stage does with a `structure-bridge-plugin` fulfillment: unlike `csv-upload`,
-its actual data is never resolved through this file's `attemptFulfillment()`/snapshot
-mechanism (that path is for a small, static, one-shot document) -- `rp-import-codegen`
-generates a normal incremental reader for it instead, reusing the same `table`/
-`sampleStructureRequest` metadata. See `rp-import-codegen`'s "`structure-bridge-plugin`
-entities" section. Which credential that reader authenticates with depends on whether the
-source site has WooCommerce (Application Password requires it; the migration key does not)
-— `rp-source-wordpress/plugins/README.md`'s "Resolving a db-only capability" section.
-
-**Plan structure-bridge-plugin entities with `lib/structure-bridge-planning.js`** before building blocked-data requests. Pass the canonical source entities as
-`sourceEntities` as well as profiles to `planStructureBridgeEntities({ plugins, sourceEntities,
-dataDir })`. Bound entities do not need a profile. Preserve their canonical reference and
-`sourceMeta.extractionPlan` unchanged; do not reconstruct bindings from legacy sidecars.
-For object-shaped source entities retain each object's key/reference while making the array.
-`planStructureBridgeEntities({ plugins, sourceEntities, dataDir })`
-turns each such entity that has `candidateTargetRefs[]` into an entity decision (target,
-readiness, read variant, discovery artifacts). An entity without a candidate target is
-returned in `blockedFieldSources` and stays on the blocked-data path above. Pass the selected
-target entities through `partitionBlockedSourceDependencies(targets, decisions)` and give its
-`targetEntities` to the blocked-data builder, so a planned entity is never also requested as
-a blocked field. Then `writeStructureBridgePlanning(projectDir, decisions)` writes
-`mapping/entity-decisions/<entity>.json` and the `mapping/mapping-plan.json` row. It refuses
-after the mapping review is approved. A rerun refreshes only the fields planning owns and
-keeps field mappings, transformations, relationships and other edits already on the row. An
-EAV read plan that fails its integrity check is a pending reason. A `pending` decision goes to
-the review gate like any other pending row.
-
-Persist the request under `state/` as the authority and render
-`mapping/review/blocked-data-requests.md` as a passive review section. This adds no new blocking
-prompt. At an interactive mapping pause, set `askedInteractively: true` only if the request is
-actually shown and a human can decline it. In 1-click mode set it to `false`; an unanswered
-request remains `missing`, never `declined`, because the run did not pause to ask.
-
-## 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
-- selected `targetRef`, `targetDomain`, `targetEntity`, `targetClassification`,
-  `importReliability`, `preferredWrite`, and `knowledgeEvidence` when the decision uses a
-  bundled domain entity record
-- when `targetClassification` is `manual-mapping`: the entity's `manualSteps`
-  verbatim (prerequisite, actor-tagged steps, mechanism, evidence) instead of field
-  mappings/transformation/validation rules below — there is no transform to author, only a
-  runbook to carry over unchanged
-- primary key and deduplication strategy
-- field mapping table
-- transformation rules
-- validation rules
-- URL preservation policy for public routed entities
-- unresolved questions
-- setup implications for Wix-side configuration
-- media policy when the entity carries media: whether only referenced media is in scope,
-  whether the target accepts external URLs directly, and whether media must exist in Wix
-  before create/update
-- `safeModeReplacements[]` when safe mode is enabled, listing every mapped email or phone
-  field that enters an outbound Wix payload. Write the same array in both
-  `mapping/mapping-plan.json` for the entity decision and
-  `mapping/entity-decisions/<entity>.json`.
-- a human-visible safe-mode note in the review markdown whenever any entity has
-  `safeModeReplacements[]`, so email/phone replacement coverage is visible without opening
-  the JSON artifacts
-
-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.
-
-## Safe-mode contact replacement metadata
-
-Safe mode is enabled by default through `config/wix.env` unless the user explicitly sets
-`SAFE_MODE=false` before mapping. When enabled, mapping artifacts must emit semantic
-contact-channel metadata so generated imports can replace outbound email and phone values
-through deterministic shared writer code.
-
-For every mapped entity, mark fields for safe-mode replacement when source evidence,
-target-Wix domain knowledge, target field semantics, user-directed mappings, CMS/custom
-fields, extended fields, form submissions, metadata, or plugin fields indicate an email or
-phone contact channel.
-
-Each `safeModeReplacements[]` entry must include:
-
-```json
-{
-  "kind": "email",
-  "sourcePath": "billing.email",
-  "targetPath": "billingInfo.email",
-  "required": true,
-  "reason": "source and target are email fields"
-}
-```
-
-`targetPath` is relative to the Wix-shaped object or request body defined by the mapping
-decision. Use the shared safe-mode path grammar: object fields (`billingInfo.email`,
-`contact.email.email`) and array wildcards (`lineItems[].buyerInfo.email`,
-`contact.additionalEmails[].email`). When the same source value is copied to multiple
-Wix fields, list each target path.
-
-Load target-side hints from selected `rp-target-wix` entity records'
-`safeModeContactFields[]` and merge them with source-side evidence and user mapping
-decisions. If `SAFE_MODE=false` before mapping, do not require this metadata for execution.
-
-This metadata must be surfaced in **both** machine and human mapping artifacts:
-
-- write `safeModeReplacements[]` into `mapping/mapping-plan.json`
-- write the same `safeModeReplacements[]` into `mapping/entity-decisions/<entity>.json`
-- render a per-entity safe-mode line in `mapping/review/mapping-plan.md`
-- when any replacements exist, include a short `Safe mode replacements` section in
-  `mapping/review/mapping-summary.md` listing the affected entities and the mapped
-  email/phone paths
-
-Do not leave safe-mode contact replacement coverage implicit in field tables or only in
-JSON. A reviewer should be able to confirm from the review markdown which outbound
-email/phone fields will be replaced in safe mode.
-
-## Variant inventory is part of the catalog plan
-
-For each source variant, plan either explicit stock (`inventoryTracked`, `inventoryQuantity`,
-`inStock` canonical fields) or a named inventory gap. Use the source adapter's stock mapper;
-stock flags, quantities, and backorders are different policies. Count every intended variant
-before filtering gaps or failed product mappings. Carry that denominator into inventory
-verification as `expectedCount`. A product count never stands in for inventory coverage.
-Default-location stock is supported; any shared pool, multi-location allocation, preorder,
-or fallback availability needs an explicit mapping decision. The target builder has no
-implicit in-stock default. A legacy explicit `inStock` fallback must not override known
-variant stock. Inventory verification remains required for deliberately excluded stock:
-record the expected destination state and the gap rather than exempting the catalog audit.
-
-## Shipping delivery estimate from the merchant
-
-When the merchant states a delivery time for a shipping zone in their own words, record it:
-
-```bash
-node skills/wix-replatform/scripts/orchestration-state.js decide --project-dir <projectDir> --key shipping-delivery-estimate:<zoneId> --value "<text>" --source user
-```
-
-Record it only from the merchant's own words. Never infer it, and never record it with
-`deterministic_inference` or `prior_artifact`: the shipping stage ignores those and lists them,
-so an inferred value can never become a checkout promise.
-
-## 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, local crosswalk
-  state, and any optional CMS mirror collections needed for site-local traceability.
-- 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 **local crosswalk strategy**:
-  `crosswalkAuthority: "local"`, a per-entity `crosswalkStrategy`, and a
-  `reconciliationStrategy` used for dedupe, resume, and relationship resolution.
-- CMS `ImportCrosswalk` is optional. Use `cmsMirror: "none" | "download" | "upload" |
-  "download-and-upload"` to request it explicitly. It is a copy/seed adapter for
-  existing-site or handoff reference flows, not the required resume authority.
-- 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**.
-
-### When the destination already exists, map against its LIVE schema
-
-`WIX_SITE_STRATEGY=existing` means the target is not an empty site provisioned to this
-mapping's shape — it is a site in use, with its own collections, fields and records. Map
-against what is actually there:
-
-- **Read the destination's current schema before proposing a target shape.** A collection
-  the site already has, with fields the owner added, is the target — not a new collection
-  that happens to fit the source better. Two collections holding the same entity is the
-  failure mode here, and it is one the owner has to untangle by hand.
-- **A field that exists but does not match is a GAP, not a migration.** Record it in the
-  faithfulness ledger and surface it in the mapping summary; do not plan a schema change
-  to a live site, and never plan to drop or retype an existing field.
-- **Every entity needs a natural key, not just a crosswalk entry.** The local crosswalk is
-  empty on the first import into a site that already has data, so dedupe has to fall back
-  to something the site itself carries — SKU, handle, slug, email. State that key per
-  entity in the mapping plan; without it the import cannot tell "already there" from "new"
-  and will duplicate the owner's catalog.
-- **Ask whether to set `cmsMirror: "download-and-upload"`; do not set it unconditionally.**
-  CMS `ImportCrosswalk` stays optional even on an existing destination — it
-  requires the user to opt into site-local reference data, because Wix CMS quotas are
-  plan-based and shared across every custom collection on the site, and a mirror the size of
-  a large migration's crosswalk can consume a meaningful share of a lower-tier plan's quota.
-  When the user does opt in, note that the on-site `ImportCrosswalk` becomes the only record
-  of prior imports visible to a run that does not share this project's local state — that is
-  the reason to offer it, not a reason to default to it.
-- **Say so in the mapping summary.** The user reviewing the plan must see that it targets a
-  site they already own, and which of their existing entities it expects to match.
-
-## URL preservation policy
-
-For every in-scope source entity that appears on the public website, include an explicit
-`urlPolicy` in `mapping/mapping-plan.json` and the relevant
-`mapping/entity-decisions/<entity>.json` artifact.
-
-Minimum `urlPolicy` fields:
-
-- `public`: `true` for public routed entities; `false` for entities intentionally outside
-  URL preservation.
-- `sourceBasePath`: the observed source base path, such as `/shop/products`; use `null`
-  only when the source URL cannot be derived and record that risk.
-- `sourceSlugField`: source field holding the slug, when present.
-- `sourceUrlField`: source field holding the full/permalink URL, when present.
-- `targetBasePath`: known Wix destination base path, or `null` when website-builder route
-  selection is deferred.
-- `targetSlugField`: planned target slug field, when applicable.
-- `preserveBasePath`: whether the future website-builder phase should try to preserve the
-  source base path.
-- `preserveSlug`: whether generated code should preserve the source slug unless target
-  validation or collision handling forces a change.
-- `redirectMode`: `record-if-different`, `manual-review`, or `none`.
-
-When recording a base-path `manual_review` outcome, persist its concrete `reasonCodes`
-and evidence in the existing base-path state, not only the status or an unexplained note.
-If the sole issue is waiting for a destination route, use `target_route_unknown` (or the
-existing `target_url_missing`, `pending_target_route`, `final_route_missing` reason).
-The redirect planner can settle that uncertainty per exact source entity/final route.
-Keep privacy, explicit operator restrictions and other causes distinct; a final destination
-does not clear those. Include every applicable reason. Do not reclassify an unexplained
-historical hold as routing-only merely because a convenient target exists; establish the
-original reason from evidence or report the missing explanation for review.
-
-If the same source entity type has multiple public route shapes, record each observed
-route class separately instead of guessing one base path. Slugs are identity and SEO data,
-but slug preservation alone is not URL preservation; route/base-path intent must be
-captured as data for the future website-builder phase.
-
-Mapping review artifacts must include a short `URL preservation` section listing:
-
-- public entity types with source base paths
-- whether base paths should be preserved
-- entities whose target route is deferred to the website-builder phase
-- known slug normalization, collision, route, or redirect risks
-- detected redirect providers (Redirection, Rank Math, Yoast Premium, server/CDN rules) with
-  their coverage status from `state/url-preservation/source-redirect-coverage.json`; an
-  `unreadable` or `unsupported` provider is an extraction gap the operator must see, never
-  an empty map
-
-Source-authored redirect rules are URL obligations in their own right: an old address can
-still receive traffic without being the address of any current page. Do not drop them
-because they have no current entity, and do not reactivate disabled ones.
-
-## Product SEO
-
-Map WooCommerce/Yoast product SEO to `product.seoEvidence` (per-field `override` / `inherit` /
-`unknown`), never to `product.seoTitle`/`seoDescription`. Rendered `yoast_head_json`, `og_*`
-and excerpts are not evidence and are never a fallback. Title and description are decided
-separately. Unknown evidence is held for an explicit owner choice (acquire evidence, omit, or
-materialize); the mapping never picks one. Canonical, robots, schema, social tags and focus
-keyphrases are not written; list them in the mapping review as not migrated. SEO patterns are
-never inferred from repeated rendered output.
-
-## 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 mapping depends on Wix runtime behavior rather than just field names, verify and
-follow the relevant `rp-target-wix` contract as well. Examples include create ordering,
-native tag handling, category assignment requirements, member prerequisites, and whether a
-product/media field should be sent as an external URL for Wix-side ingestion.
-
-For entity suitability, do not grep or paste whole domain files into the plan. Use:
-
-```bash
-node skills/wix-replatform/resources/rp-target-wix/scripts/domain-knowledge.js summarize-entities --refs <domain/entity,...>
-```
-
-Load full entity records only for selected candidates that materially affect the current
-project.
-
-- Verify enum **values**, not just names: every `Field.type` you assign must be a real
-  member of the Create Data Collection `Type` enum. Never assign a guessed enum value and
-  flag it `unverified`; resolve it or omit it. (`SLUG` **does** exist in that enum — it is
-  documented for dynamic page URLs. Prefer `TEXT` when the field carries a *preserved source*
-  slug as identity/SEO data, and `SLUG` only when the target itself generates the dynamic-page
-  URL from it; both are real choices, so do not record `SLUG` as unavailable.)
-- If a Wix tool surface such as Wix MCP is available in the runtime, use it as a fast
-  verification aid for entity, field, enum, app, and setup names.
-- 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. Mark anything
-  you could not verify directly as `unverified` in the mapping plan so it is surfaced
-  before execution.
-
-## Runtime policy
-
-Resolve ambiguous mappings using the documented default, record the decision and rationale
-under the machine mapping artifacts and render them into `mapping/review/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 source entity name is generic but the observed data disambiguates it, record that
-disambiguation explicitly in the machine mapping artifacts and review 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/review/mapping-gaps.json` and render it
-into `mapping/review/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 — plugin coverage.** Every row in `discovery/plugin-coverage.json` whose
-status is not `migration-planned` must produce a `mapping/review/mapping-gaps.json` entry
-carrying the capability, the status, and the row's user-facing impact line — and so must a
-`migration-planned` row that is lossy or carries `blocked[]` entries. This is what makes
-plugin loss visible: a capability the pipeline discovered but could not deliver has to reach
-the execution-plan report, and the ledger is the only path there.
-
-Each such entry must also carry a `severity`, because a plugin-heavy site produces far more
-rows than it has real problems — on a 55-plugin store, 26 rows were "we don't recognise this
-plugin", which would bury the entries that matter if they all read alike. Use the same
-vocabulary as profile pitfalls:
-
-| `severity` | Means | Typical rows |
-| --- | --- | --- |
-| `blocker` | data the user would care about is not coming across | `requires-development`; a `blocked[]` entry still unresolved or declined |
-| `warning` | it migrates lossily, or we are not sure yet | `pending` (including `cannot-tell`); `migration-planned · via cms` where the source is semantically richer |
-| `info` | accounted for, nothing lost that we know of | `no-need-to-migrate` with `basis: proposed`; `migration-planned · proposed` with no known loss |
-
-The execution-plan report leads with `blocker` and `warning` and summarizes `info` as a count
-with a pointer. Severity is a **rendering** aid, not permission to omit: every row still gets
-an entry, so the audit trail stays complete and a mis-severitied row can be found later.
-
-**Mandatory trigger — source coverage.** Every row in `discovery/source-coverage.json` needs
-**exactly one** disposition, and `scripts/coverage-reconcile.js check <project>` exits 2 until it
-has one (the router holds the run at mapping meanwhile):
-
-- a `mapping/review/mapping-gaps.json` entry carrying the row's `coverageId` (the usual case:
-  severity `blocker` for an in-scope capability, with `recommendedHandling`); or
-- a `sourceCoverage:<coverageId>` decision — `provided` when discovery was re-run and the entity
-  now exists in `source-schema.json`, `declined` when the user skipped it. Record it only with
-  `scripts/coverage-reconcile.js decide <project> --coverage-id <id> --value provided|declined`,
-  which also removes that row's gap entry in the same write; or
-- for a quick adapter only, its own declared exclusion (already on the row).
-
-Two dispositions for one row (two gap entries, a gap plus a decision, a declared exclusion plus
-anything) fail as `disposition_conflict`; there is no precedence rule. A `provided` decision whose
-entity is not in `source-schema.json` fails as `disposition_stale`. A gap may cite an existing
-human gate, never create one: `gate: "exclusion"` with `gateEvidence: { register:
-"no-migration-needed", capability }` only on an `adapter-excluded` row whose signed register entry
-names that row's own capability, or `gate: "loss-accepted"` with `gateEvidence` naming a signed
-register entry (`register`, `capability`) or the approved mapping review (`approval: "mapping"`).
-Any other pairing fails as `gate_reason_mismatch`; a cited gate that does not exist fails as
-`gate_missing`. Every outcome reaches the completion report; see `rp-execute-import`.
-
-Additional plugin rules:
-
-- Resolve targets from `sourceMeta.candidateTargetRefs[]` first, then
-  `domain-knowledge.js resolve-source`, then the target knowledge base's capability index
-  keyed on `sourceMeta.capability`.
-- **Derived entities (`sourceMeta.recognized: false`) may only be mapped to a native Wix
-  entity when the domain knowledge confirms the capability.** Otherwise map them to CMS. The
-  proposed capability from discovery is recorded with `confidence: proposed`, never a
-  target decision — treating a guess as native is how a silent, lossy write happens.
-- **Every capability, recognized or derived, needs its pairing written down: plugin details
-  against Wix details.** In `mapping/review/mapping-plan.md`, per capability: the source
-  entity and the fields it actually carries, the target entity and the fields it expects,
-  which source field lands in which target field, and which carry nowhere. In
-  `mapping/review/mapping-summary.md`, one line naming the source, the target, and the single
-  consequence that matters. For a derived capability, say in both that the mapping is
-  **proposed** rather than confirmed — a reviewer must be able to tell a guess from an
-  authored match. Without the pairing the user is approving a target name, not a mapping.
-- A `no-need-to-migrate` row with `basis: proposed` (the agent's own reading, not a list
-  entry) is also listed in `mapping-summary.md` — automation deciding there is nothing to
-  move is a decision worth seeing.
-- Carry each plugin entity's profile `pitfalls[]` into the plan, and surface `blocker`
-  severities in `mapping/review/mapping-summary.md`.
-- **A capability read through a plugin-specific credential is disclosed up front.** When a
-  profile declares `credentials[]` (a plugin's own API key or secret, beyond the platform
-  admin credential — e.g. Subscriptions For WooCommerce's plugin-generated
-  `consumer_secret`), the capability's row in `mapping/review/mapping-plan.md` states the
-  credential prerequisite (what key, where the user finds or enables it in the source
-  admin), and `mapping-summary.md` carries one line listing every capability that will ask
-  for such a key. The user learns this at the mapping review, not first as a surprise
-  `blocked: credential` ask mid-run; the run-time collection still goes through the
-  standard batched blocked-and-recoverable ask.
-- Any capability landing in CMS adds two setup implications to the summary: the **Wix Data app
-  install**, and **creating each collection** (no verified writer yet, so it is manual). A CMS
-  row presented without them reads as more automatic than it is.
-- `requires-development` and `pending` rows belong in the summary's gaps section in plain
-  language, even though there is no mapping to make for them.
-- A `targetClassification: "manual-mapping"` entity becomes a checklist item in
-  `mapping-summary.md`'s `Manual steps you need to complete` section (see "The manual-steps
-  section"), not a section of its own — one consolidated list is what makes the handover
-  readable, and a per-entity section splits it. Carry over its `manualSteps.steps[]` as a
-  numbered list under that item, not a one-line summary; the point is to hand over a runbook,
-  not to compress it. **Do not** put these rows in the pending/gaps section: unlike `pending`,
-  a manual-mapping row is a complete, decided mapping the moment it is authored with real
-  evidence — there is nothing left for a human to decide, only steps for the merchant to
-  execute. It needs no verdict at the review gate below.
-
-**Mandatory step — pending rows are decided at the review gate.** The mapping review is the
-single human gate and **the only exit from Pending**: every `pending` row is put to the user
-for a decision, none may survive the gate undecided. Four verdicts, each with a producer:
-
-- **"We can migrate it"** — record the chosen target and move the row to *Migration planned*
-  in the plan (its `confidence` stays `proposed` until a profile is authored) — when the
-  capability has no REST route, follow `rp-source-wordpress/plugins/README.md`'s "Resolving
-  a db-only capability" order (try wix-wp-plugin-v2's structure-bridge-plugin before
-  defaulting to a `user-file`/csv-upload ask) before authoring the profile.
-- **"Nothing to move"** — the row becomes *No need to migrate* with `basis: decision` and the
-  user's stated reason as its `rationale`.
-- **"Wix has no surface — build it first"** — the row becomes *Requires development*: write it
-  to `mapping/review/mapping-gaps.json` with severity `blocker`, emit an `api_gap` telemetry
-  event, and record the verdict in the human-signed register
-  (`plugins/requires-development.json`, `decidedBy` = the user) citing the recorded search.
-- **"The surface exists, we did not know it"** — telemetry only (`source_plugin_coverage`
-  carries the decision); the profile or domain entity is authored between runs, never during
-  this one.
-
-Record each decision in `orchestration/decisions.json`; blocked-row asks batched at discovery
-use the key `pluginBlocker:<capability>:<kind>` with value `provided` or `declined`.
-
-**Mandatory step — the CMS-fallback ask (recognized capabilities).** A profile never names a
-CMS target. CMS is reachable for a recognized capability only when a human signed it as an
-*eligible* fallback (`plugins/cms-fallback-eligible.json`) **and** this migration's merchant
-approves it. Such a row arrives `pending` with `cmsFallback.eligible: true` and one of these
-reasons; each is one more closed question on that pending row at the same review:
-
-- `cms-fallback-awaiting-approval` / `cms-fallback-decision-stale` — ask: *approve archiving
-  these records in Wix CMS*, or *decline*. Show the row's record counts, the proposed
-  collection(s) (`cmsFallback.proposedTargetRefsByEntity`) and the `cmsFallback.featureLoss`
-  sentence **verbatim**. Never present CMS archival as restoring the plugin's feature. A stale
-  row's earlier answer (`cmsFallback.staleDecision`, or `invalidDecision` for a hand-edited or
-  malformed entry) no longer applies; ask again.
-- `cms-fallback-declined` — already answered; nothing goes to CMS. It stays `pending`: offer
-  the ordinary pending verdicts above if the merchant wants to settle it another way.
-  Declining CMS is never recorded as accepted data loss, `no-need-to-migrate` or
-  `requires-development`.
-- `cms-fallback-target-knowledge-unavailable` — not askable: Wix target knowledge failed to
-  load, so "nothing native fits" is unproven. Report it; rerun once it loads.
-
-Record the answer only with the dedicated writer (the generic `decide` rejects the key):
-
-```bash
-node skills/wix-replatform/scripts/orchestration-state.js decide-cms-fallback \
-  --project-dir <project> --capability <capability> --value approved|declined \
-  --approved-by "<the name or role the person gave>"
-```
-
-It writes `pluginCmsFallback:<capability>` bound to the proposal on the coverage row
-(`proposalDigest`), resets the mapping approval to pending, and the router then reclassifies
-coverage and sends you back here to regenerate the plan. **One-click and unattended runs never
-record this answer**: an agent-accepted mapping checkpoint leaves these rows pending, nothing is
-written to CMS for them, and completion reports them. The writer itself refuses (exits
-non-zero) whenever `automationMode` is `one_click`; do not work around it. A row that is `migration-planned · via cms`
-with `cmsFallback.functionalityRestored: false` is CMS-by-approval; map it to exactly
-`targetRefs` (the register's refs), and add the CMS setup implications below plus one
-`mapping-summary.md` line with the `featureLoss` sentence.
-
-`mapping-gaps.json` severities for these rows: every pending CMS-fallback row (awaiting, stale,
-declined, target knowledge unavailable) is `warning`; an approved row is also `warning` (lossy by
-definition) and carries the `featureLoss` sentence. Each `plugin-coverage.json`
-`cmsFallbackDecisionIssues[]` entry (a malformed answer for a capability with no row) is one
-`info` item. A row carrying `cmsFallbackDecisionIgnored` (a native target now resolves, or the
-eligibility was removed) is reported with that reason so the earlier answer is visibly retired.
-
-**Mandatory step — bind the plan to the coverage it was built from.** After writing
-`mapping/mapping-plan.json`, stamp it (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 mapping
-```
-
-This copies `discovery/plugin-coverage.json` `inputs.cmsFallbackDigest` into
-`mapping-plan.json` `inputs.cmsFallbackDigest`. The router treats a plan without it, or with a
-different one, as stale (`mapping_plan_stale_cms_fallback`) and routes back here, including on
-one-click runs.
-
-**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 (the Wix Blog category target is flat — it has no parent/child relationship). 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.
-
-Every selected entity whose domain knowledge includes `IMPORT_UNRELIABLE` must create a
-`mapping/review/mapping-gaps.json` entry with the same fixed flag string, the selected
-`targetRef`, a project-specific summary, and the chosen fallback or review action.
-
-**Mandatory check — every in-scope entity's dependencies are also in scope.** Run it directly, do
-not re-derive it by reading prose:
-
-```bash
-node skills/wix-replatform/resources/rp-target-wix/scripts/domain-knowledge-validate.js \
-  --check-scope <comma-separated domain/entity refs in the mapping plan>
-```
-
-Pass only the plan's own selected refs — `checkScope` walks the `dependsOn` transitive closure
-itself starting from that list, so do not pre-expand it by hand. It fails closed on three distinct,
-named problems, any one of which is a gap the user must resolve at the gate before proceeding:
-
-- **Unknown ref** — something in your selected list doesn't resolve to a real `domain/entity`
-  file (typo, stale ref). Fix the ref.
-- **Missing dependency** — a reachable `dependsOn` has no selected producer. Resolve it
-  through an import task, bound setup steps, or the reviewed census exclusion path above. The structural scope checker must receive the full canonical dependency inventory, including refs assigned to setup or exclusion; including a ref in that inventory does not select an import entity or approve a disposition. Producer binding and current owner approval are checked separately before codegen/run.
-  Record the association and exact field rule where needed; a prose best-effort exception
-  cannot make an unresolved reference writable.
-- **Unreviewed** — an entity reachable from your selection has never had `dependsOn` authored at
-  all (distinct from "reviewed, no dependencies"). `--list-missing-deps` shows the same backlog
-  outside the context of any one plan.
-
-A clean `--check-scope` result means only this plan's own reachable set is fully reviewed and
-in scope — it says nothing about entities outside that reachable set. `checkScope` walks from
-your selected refs, not from the whole domain tree, so an unrelated entity with no `dependsOn`
-authored at all stays invisible to this gate until some plan actually reaches it. Run
-`--list-missing-deps` (unscoped, whole-repo) separately to see the standing backlog.
-
-**As of this pass, only 19 of 62 entities in this repo have `dependsOn` authored** — expect to hit
-**Unreviewed** on most real plans today, not just as an edge case. That is not this gate failing;
-it is the gate doing its job on a knowledge base that is still mid-backfill. When it happens:
-author `dependsOn` on the reachable entity now, as part of the mapping work you are already
-doing — deciding a mapping plan already means knowing what that entity depends on, so this is
-recording that decision, not new research — then re-run `--check-scope`. Do not treat Unreviewed as
-a reason to skip the gate or fall back to reading prose by hand for that entity.
-
-Do not expand the selection to the full transitively-reachable set by hand before calling
-`--check-scope`. `checkScope` performs the walk itself; pass it your plan's actual selection and
-nothing more.
-
-## Default media scope
-
-Default to importing only media referenced by in-scope entities such as posts, products,
-collections, categories, or CMS rows that are actually being migrated. Unattached
-source-library media is out of scope by default unless the user explicitly asks for a
-library/archive migration.
-
-When an entity carries media, consult `rp-target-wix` for the target behavior:
-
-- if the target accepts external URLs and ingests them in the background, prefer that
-  path
-- otherwise require media import to Wix first, then attach the resulting Wix media id
-
-## Mapping summary for user review
-
-After `mapping/mapping-plan.json` is written, create
-`migrations/<project>/mapping/review/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/review/mapping-plan.md`
-- **carry a `Manual steps you need to complete` section — required, always present, placed
-  immediately after the opening and ahead of the entity mappings.** See "The manual-steps
-  section" below; it is the one place the user learns what stays their job
-- 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
-- summarize public URL preservation: source base paths, deferred target routes, and slug
-  or redirect risks that affect approval
-- mention the biggest setup implications the user should know now (for example: required
-  Wix apps, required CMS collections, optional CMS crosswalk mirror, media reachability
-  caveat)
-- when safe mode is enabled and any replacements exist, include a short summary of which
-  entities have outbound email/phone replacements and where they apply
-- 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/review/mapping-plan.md` only when they want detail.
-
-Recommended structure:
-
-- one-sentence purpose / pointer to `mapping/review/mapping-plan.md`
-- **`Manual steps you need to complete`** — required, in this position, never further down
-- `Source -> Wix targets`
-- `Plugin coverage` (when the source reported plugins): one line per capability that is not
-  `migration-planned · confirmed`, in the user's terms, plus anything they must supply or
-  accept losing
-- `URL preservation`
-- `Main gaps / lossiness`
-- `Important setup implications`
-- `Safe mode replacements` when applicable
-- `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.
-
-## The manual-steps section
-
-The user can otherwise approve a migration without understanding what they still have to do
-themselves. Payment setup, a domain/DNS cutover, add-on work, app installs and permissions
-are scattered across setup notes, gaps and per-entity runbooks — or missing altogether. This
-section is the single consolidated list, and it is **not** optional.
-
-Write it as a **numbered checklist**, each item carrying:
-
-- a clear **action title** and short instructions — what to do and where to do it
-- **who must act**, when that is someone other than the user
-- any **prerequisite**
-- **what stays unavailable until it is done**
-- **when it is needed**, which is also the sort order: before import → before launch →
-  optional follow-up
-
-Mark an item optional only when skipping it genuinely is acceptable. Necessary redirect work
-is not optional by default.
-
-**Where the items come from.** Gather from the plan and the mapping inputs already in hand —
-`manualSteps` on target entities, `setupRequirements`, `reconfigure-in-wix` hints in
-`no-migration-needed.json`, actionable rows in the faithfulness ledger, and known
-domain/launch requirements. Notification, consent and redirect follow-up belong here when it
-is known at mapping time and needs the user to act.
-
-**Coverage prompts, not a checklist to copy.** Include only work actually still needed for
-this source, destination and plan:
-
-| Manual action | What the user needs to know |
-| --- | --- |
-| Set up payments | Connect and activate the payment provider in Wix before taking payments. Payment setup is currently manual. |
-| Connect the domain / change DNS | Follow the destination's domain-connection instructions at the domain provider when ready to switch the live site. Say that this changes where visitors go — never present it as an immediate pre-import task. |
-| Finish product add-ons | Name the actual add-on behaviour that stays manual, the affected products or groups, and the agreed work to make it available. "Configure the add-on plugin" alone is not an instruction. |
-| Complete other required setup | Applicable app installs, permission scopes, plans, CMS collections, sales-channel connections and other reconfiguration found during mapping. |
-
-Where an action's details are not yet known, say what must be confirmed. Never invent a
-setting, a screen or a step.
-
-**Keep every step of an existing runbook.** A `manual-mapping` entity's `manualSteps.steps[]`
-is carried in full under its checklist item — `prerequisite` as its own "before you start"
-line, `mechanism` as "how it behaves once connected". A compressed runbook is not actionable.
-List a shared setup action **once**, naming every capability it covers.
-
-**Manual actions are not unresolved gaps.** A known manual procedure belongs here. An
-unsupported feature, or an approach nobody has agreed yet, stays in the gaps/questions
-section until there is an agreed action — detecting a plugin does not prove its behaviour can
-be recreated by hand in Wix. If it needs development, say so in the gaps section; list a
-manual workaround only once it is agreed. A gap that does have an actionable workaround may
-link to its checklist item.
-
-**Check the list before the summary goes to the user.** Reconcile it against the mapping plan,
-the manual runbooks, `setupRequirements`, the actionable gaps and the known launch
-requirements. Work the agent will perform automatically is **not** a user task and must not
-appear. Refresh the section whenever the mapping changes.
-
-**An empty list still gets the heading**, followed by exactly: `No manual steps identified for
-this mapping.` A summary that omits the section, or leaves a known manual action only in
-scattered setup or gap notes, fails review.
-
-## Mapping review checkpoint
-
-Once both mapping artifacts exist, reset `orchestration/approvals.json` so
-`mapping.status=pending`, then stop and ask the user to review
-`migrations/<project>/mapping/review/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/review/mapping-plan.md`
-- **what the user will still have to do by hand**, pointing at the summary's
-  `Manual steps you need to complete` section
-- downstream setup discovery and code generation will wait for acceptance
-
-**Before presenting the checkpoint, run `scripts/coverage-reconcile.js check <project>`** and
-resolve every failure it names; do not ask for approval of a plan it rejects.
-
-**Before presenting the checkpoint, run the manual-steps coverage check** described in "The
-manual-steps section": the section exists, every applicable manual action from the plan, the
-runbooks, `setupRequirements` and the actionable gaps appears in it, nothing the agent
-automates appears in it, and an empty set carries the explicit empty statement. A summary
-presented for approval without that section is not ready for review, and this applies in
-`1-click mode` too — the checkpoint is recorded as agent-accepted there, but the section is
-still written.
-
-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. In
-explicit user-requested `1-click mode` (`automationMode=one_click`, `source=user`), still
-write the same review artifacts, but record the checkpoint as accepted by the agent and
-continue immediately. A missing mode or a non-user-authored `one_click` value is normal
-interactive mode and must pause here; file upload does not imply one-click.
-
-## 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 guess Wix field, enum, or app names when you cannot verify them. Mark them
-  `unverified` and surface the risk before execution.
-
-## Discovered-set review and legacy approvals
-
-Before presenting a standard-mode mapping review, run `node scripts/discovered-census.js build <projectDir>` and `node scripts/census-reconciliation.js build <projectDir>`. Fix structural errors only for the named census IDs. Each discovered entity, registered sub-part, capability and unlinked plugin needs exactly one assignment: plan `censusIds[]` or a gap `censusId` plus `disposition`. A parent entity never silently covers its sub-parts. Show the generated **Discovered set** section, including its unknown counts, exclusions and pending questions. Ask the owner each pending question; record answers as closed states, rebuild, and present that rebuilt review. Approving this review approves the listed exclusions; provisional and explicit 1-click agent approvals do not establish owner approval of exclusions.
-
-The mapping approval user action must reference `{ "kind": "census-reconciliation", "path": "mapping/review/census-reconciliation.json", "sha256": "<current file SHA-256>" }` along with the summary. Let the approval scripts bind and persist the reference; never write a digest or approval directly. A stale answer must produce a fresh request. In explicit 1-click mode use `auto-approve`, leave cannot-tell rows pending, and report them as not decided after import.
-
-For `mapping_approval_missing_census` or `mapping_approval_stale_census`, reset with `node scripts/orchestration-state.js approve --project-dir <projectDir> --type mapping --status pending`, rebuild from the existing discovery files, and present again. Explain once that this fresh review accounts for the complete discovered set; do not rerun discovery or imported records.
-
-**When the router returns `reviewOnly: true`, the site must not change.** Keep the plan, gap list and `decisions.json` frozen, including on rejection; never run `coverage-reconcile.js decide`. Write assignments only in `mapping/review/finalized-census-assignments.json` (`planLinks` names existing plan rows; `gaps` names new decisions), then rebuild the census/reconciliation and approve through the normal scripts. A request to import newly discovered scope is `pending` with `reasonCode: import-after-finalization`; it stays open for a separate human decision and performs no import. Do not create a new plan version. Any `review_only_*` or `finalized_receipt_unverified` hold requires the Import Operator to inspect the named input; never route around it.