@wix/agent-skills 1.33.1 → 1.35.0

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

@@ -19,6 +19,7 @@ This skill translates source entities and fields into Wix targets. It should def
 - `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
@@ -46,15 +47,60 @@ before:
 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 `replatform/resources/rp-source-<platform>/SKILL.md`
-- Wix target constraints and domain behavior from `replatform/resources/rp-target-wix/SKILL.md`
+- 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
-  `replatform/resources/rp-target-wix/scripts/domain-knowledge.js`
+  `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
@@ -122,9 +168,17 @@ overcharges every discounted product.
 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.
-7. Save the mapping plan.
-8. Write a concise user-review summary after the plan is complete.
-9. Pause for a mapping review checkpoint before downstream setup/codegen work begins.
+   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
 
@@ -135,9 +189,83 @@ overcharges every discounted product.
 - `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:
@@ -149,6 +277,10 @@ Include for each source entity:
 - 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
@@ -224,6 +356,31 @@ Do not leave safe-mode contact replacement coverage implicit in field tables or
 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**.
@@ -243,6 +400,35 @@ Be explicit about the difference between a **source ID** and a **Wix target ID**
   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
@@ -266,6 +452,16 @@ Minimum `urlPolicy` fields:
   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
@@ -277,6 +473,24 @@ Mapping review artifacts must include a short `URL preservation` section listing
 - 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
 
@@ -291,16 +505,18 @@ 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/replatform/resources/rp-target-wix/scripts/domain-knowledge.js summarize-entities --refs <domain/entity,...>
+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. (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.)
+  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
@@ -336,6 +552,174 @@ will not migrate cleanly, including:
   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**
@@ -354,6 +738,46 @@ Every selected entity whose domain knowledge includes `IMPORT_UNRELIABLE` must c
 `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,
@@ -377,6 +801,9 @@ 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
@@ -396,7 +823,11 @@ shape" from this file alone, then consult `mapping/review/mapping-plan.md` only
 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`
@@ -406,6 +837,65 @@ Recommended structure:
 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
@@ -414,10 +904,27 @@ Once both mapping artifacts exist, reset `orchestration/approvals.json` so
 
 - 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.
+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
 
@@ -428,3 +935,13 @@ mapping review checkpoint, unless the user explicitly asks to continue provision
 - 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.