@wix/agent-skills 1.33.1 → 1.35.0

package/skills/wix-replatform/resources/rp-mapper/lib/structure-bridge-planning.js

@@ -0,0 +1,303 @@
+'use strict';
+
+// Mapping-stage planning for structure-bridge-plugin entities .
+//
+// A plugin entity whose only read path is wix-wp-plugin-v2's /query is two different things,
+// and this module keeps them apart:
+//
+//   - A PLANNED ENTITY: the profile proposes a Wix target (`candidateTargetRefs[]`), so the table
+//     becomes a migration entity in its own right. It gets `mapping/entity-decisions/<entity>.json`
+//     and a row in `mapping/mapping-plan.json`, under the same mapping-review gate as a REST
+//     entity, and rp-import-codegen generates a normal incremental reader for it
+//     (rp-source-wordpress/lib/structure-bridge-reader.js).
+//   - A BLOCKED-FIELD SOURCE: no candidate target; the data only fills a field on a target that
+//     is planned through another source (for example gift-card balance). That stays on the
+//     blockedSourceDependencies / blocked-data-requests.js path, unchanged.
+//
+// A target entity may declare a blockedSourceDependency on a source that is ALSO planned here
+// as its own entity (ecom/discount-rule on discount-rule-definition). Routing it through both
+// paths would offer the same table as a one-shot blocked-data request that can never resolve,
+// so partitionBlockedSourceDependencies() removes that dependency before the blocked-data
+// builder runs and records it on the planned entity's decision instead.
+//
+// Readiness is the only thing checked through blocked-data-handlers.js; data is never resolved
+// through blocked-data-requests.js's snapshot mechanism.
+
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { fulfillmentReadiness } = require('../../rp-source-wordpress/lib/blocked-data-handlers.js');
+const { readEntityByRef } = require('../../rp-target-wix/lib/domain-knowledge.js');
+const { verifyEavReadPlanIntegrity } = require('../../rp-source-wordpress/lib/wix-wp-plugin-v2-client.js');
+
+const DEFAULT_DOMAINS_DIR = path.join(__dirname, '..', '..', 'rp-target-wix', 'domains');
+const REVIEW_GATE = Object.freeze({ artifact: 'orchestration/approvals.json', field: 'mapping.status' });
+const PLAN_ROW_KEYS = ['entityMappings', 'entityDecisions', 'mappings', 'entities'];
+
+function slugify(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'entity';
+}
+
+function sourceEntityRefOf(plugin, entity) {
+  return `plugin.${plugin}.${entity}`;
+}
+
+function structureBridgeFulfillment(entity) {
+  const blockers = [...(entity.blocked || []), ...((entity.pitfalls || []).flatMap((p) => p.blocked || []))];
+  const hit = blockers.find((b) => b.fulfillment && b.fulfillment.kind === 'structure-bridge-plugin');
+  return hit ? hit.fulfillment : null;
+}
+
+async function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(await fsp.readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+/** A discovery artifact that is not valid JSON is a pending reason, not a crashed mapping run. */
+async function readArtifact(filePath, fileName, pendingReasons) {
+  try {
+    return await readJsonIfExists(filePath);
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    pendingReasons.push(`discovery artifact ${fileName} is not valid JSON -- re-run discovery for this table`);
+    return null;
+  }
+}
+
+/** Why an EAV read plan cannot drive extraction, or null. Mirrors the reader's own checks. */
+function eavPlanIntegrityReason(plan, planFile) {
+  if (!plan || typeof plan !== 'object' || Array.isArray(plan)) return `read plan ${planFile} is not an object -- re-run discovery for this table`;
+  let problem;
+  try { problem = verifyEavReadPlanIntegrity(plan); } catch (error) { problem = error.message; }
+  if (!Array.isArray(plan.pairs)) problem = problem || 'it has no pairs array';
+  return problem ? `read plan ${planFile} fails its integrity check, so extraction would defer: ${problem}` : null;
+}
+
+function loadTarget(domainsDir, ref) {
+  try { return readEntityByRef(domainsDir, ref); } catch { return null; }
+}
+
+/**
+ * Classify every structure-bridge-plugin entity of the detected plugins.
+ *
+ * @param plugins   [{ plugin, entities: [...] }] -- profiles or wp-plugin-detect's detected list
+ * @param dataDir   the project's `data/` directory (discovery sidecars live in wp-discovery/)
+ * @param readiness optional override of blocked-data-handlers.js's fulfillmentReadiness
+ * @returns { decisions, blockedFieldSources }
+ */
+async function planStructureBridgeEntities({ plugins = [], sourceEntities = null, dataDir, readiness = fulfillmentReadiness, domainsDir = DEFAULT_DOMAINS_DIR } = {}) {
+  if (!dataDir) throw new Error('planStructureBridgeEntities needs dataDir');
+  if (sourceEntities === null) {
+    const schema = await readJsonIfExists(path.join(path.dirname(path.resolve(dataDir)), 'source-schema.json'));
+    sourceEntities = Array.isArray(schema?.entities) ? schema.entities
+      : Object.entries(schema?.entities || {}).map(([key, row]) => ({ sourceEntityRef: key, ...row }));
+  }
+  const decisions = [];
+  const blockedFieldSources = [];
+  const boundRefs = new Set();
+  const bound = require('../../rp-source-wordpress/lib/plugin-entity-read-plan.js');
+  for (const entity of sourceEntities) {
+    const planRef = entity.sourceMeta?.extractionPlan;
+    if (!planRef && !entity.bridgeDesignated) continue;
+    const sourceEntityRef = entity.sourceEntityRef;
+    boundRefs.add(sourceEntityRef);
+    const pendingReasons = [];
+    let plan;
+    try { plan = bound.loadPlan({ projectDir: path.dirname(dataDir), sourceEntityRef, planRef }); }
+    catch (error) {
+      pendingReasons.push(error.message);
+      bound.recordPluginExtractionDeferral({ projectDir: path.dirname(dataDir), sourceEntityRef, planRef, code: error.code || 'plan-invalid', reason: error.message });
+    }
+    const candidates = entity.candidateTargetRefs || entity.sourceMeta?.candidateTargetRefs || [];
+    if (!candidates.length) {
+      blockedFieldSources.push({ sourceEntityRef, sourceEntity: entity.entity || sourceEntityRef, table: plan?.components.length === 1 ? plan.components[0].table : null, route: 'blocked-source-dependency' });
+      continue;
+    }
+    const targetRef = candidates[0];
+    const target = loadTarget(domainsDir, targetRef);
+    if (!target) pendingReasons.push(`candidate target ${targetRef} is not in the Wix domain knowledge`);
+    decisions.push({ schemaVersion: 1, sourceEntityRef, sourceEntity: sourceEntityRef,
+      sourcePlugin: sourceEntityRef.split('.')[1], sourceMeta: { ...entity.sourceMeta }, bridgeDesignated: true,
+      sourceType: entity.sourceType || null, sourcePrerequisites: entity.sourcePrerequisites || [],
+      resolution: 'structure-bridge-reader', fulfillment: { kind: 'structure-bridge-plugin', handlerId: 'wix-wp-plugin-v2' },
+      targetRef, targetDomain: targetRef.split('/')[0], targetEntity: targetRef.split('/')[1], targetClassification: target?.target?.classification || null, candidateTargetRefs: candidates,
+      confidence: 'proposed', status: pendingReasons.length ? 'pending' : 'migration-planned', pendingReasons,
+      readiness: { ready: Boolean(plan), reason: pendingReasons.join('; ') || null }, readVariant: 'entity-plan',
+      readArtifacts: { extractionPlan: planRef || null },
+      sourceExtract: { ndjson: `data/source-extract/${sourceEntityRef}.ndjson`, manifest: `data/source-extract/${sourceEntityRef}.manifest.json` },
+      supersedesBlockedDependencies: [], reviewGate: { ...REVIEW_GATE } });
+  }
+  for (const plugin of plugins) {
+    for (const entity of plugin.entities || []) {
+      const fulfillment = structureBridgeFulfillment(entity);
+      if (!fulfillment) continue;
+      const sourceEntityRef = sourceEntityRefOf(plugin.plugin, entity.entity);
+      if (boundRefs.has(sourceEntityRef)) continue;
+      const candidateTargetRefs = [...(entity.candidateTargetRefs || [])];
+      if (candidateTargetRefs.length === 0) {
+        blockedFieldSources.push({ sourceEntityRef, sourceEntity: entity.entity, table: fulfillment.table, route: 'blocked-source-dependency' });
+        continue;
+      }
+
+      const requestFile = `wix-wp-plugin-v2--${slugify(fulfillment.table)}.structure-request.json`;
+      const planFile = `wix-wp-plugin-v2--${slugify(fulfillment.table)}.eav-read-plan.json`;
+      const artifactReasons = [];
+      // eslint-disable-next-line no-await-in-loop
+      const [request, plan, ready] = await Promise.all([
+        readArtifact(path.join(dataDir, 'wp-discovery', requestFile), requestFile, artifactReasons),
+        readArtifact(path.join(dataDir, 'wp-discovery', planFile), planFile, artifactReasons),
+        readiness(fulfillment),
+      ]);
+      const targetRef = candidateTargetRefs[0];
+      const target = loadTarget(domainsDir, targetRef);
+      const pendingReasons = [...artifactReasons];
+      if (!ready || ready.ready !== true) pendingReasons.push(`handler not ready: ${(ready && ready.reason) || 'unknown'}`);
+      if (!target) pendingReasons.push(`candidate target ${targetRef} is not in the Wix domain knowledge`);
+      if (!request && !plan && artifactReasons.length === 0) pendingReasons.push(`discovery produced no read artifact (${requestFile}) -- the table was not sampled successfully`);
+      const integrity = plan ? eavPlanIntegrityReason(plan, planFile) : null;
+      if (integrity) pendingReasons.push(integrity);
+      if (plan && Array.isArray(plan.droppedIdentityColumns) && plan.droppedIdentityColumns.length > 0) {
+        pendingReasons.push(`read plan drops identity column(s) ${plan.droppedIdentityColumns.join(', ')}; complete identity is required -- narrow the mapping or redesign the read plan`);
+      }
+      if (plan && plan.keysTruncated) pendingReasons.push('read plan key list is truncated, so the extraction cannot be whole-table');
+
+      decisions.push({
+        schemaVersion: 1,
+        sourceEntity: entity.entity,
+        sourceEntityRef,
+        sourcePlugin: plugin.plugin,
+        capability: entity.capability || null,
+        channel: entity.channel || null,
+        resolution: 'structure-bridge-reader',
+        fulfillment: { kind: fulfillment.kind, handlerId: fulfillment.handlerId, table: fulfillment.table },
+        readiness: { ready: Boolean(ready && ready.ready), reason: (ready && ready.reason) || null },
+        targetRef,
+        targetDomain: targetRef.split('/')[0],
+        targetEntity: targetRef.split('/')[1],
+        targetClassification: target && target.target ? target.target.classification : null,
+        candidateTargetRefs,
+        confidence: 'proposed',
+        status: pendingReasons.length === 0 ? 'migration-planned' : 'pending',
+        pendingReasons,
+        readVariant: plan ? 'eav' : 'single-request',
+        readArtifacts: {
+          structureRequest: request ? `data/wp-discovery/${requestFile}` : null,
+          eavReadPlan: plan ? `data/wp-discovery/${planFile}` : null,
+        },
+        sourceExtract: {
+          ndjson: `data/source-extract/${entity.entity}.ndjson`,
+          manifest: `data/source-extract/${entity.entity}.manifest.json`,
+        },
+        supersedesBlockedDependencies: [],
+        reviewGate: { ...REVIEW_GATE },
+      });
+    }
+  }
+  return { decisions, blockedFieldSources };
+}
+
+/**
+ * Remove blockedSourceDependencies whose source is planned as its own entity, so the
+ * blocked-data builder never also requests it. Returns new target objects (inputs untouched) and
+ * records each removed dependency on the matching decision.
+ */
+function partitionBlockedSourceDependencies(targetEntities = [], decisions = []) {
+  const byRef = new Map(decisions.map((d) => [d.sourceEntityRef, d]));
+  const targets = targetEntities.map((target) => {
+    const deps = Array.isArray(target.blockedSourceDependencies) ? target.blockedSourceDependencies : [];
+    const kept = [];
+    for (const dep of deps) {
+      const decision = byRef.get(dep.sourceEntityRef);
+      if (!decision) { kept.push(dep); continue; }
+      const targetEntity = target.ref || `${target.domain}/${target.entity}`;
+      if (!decision.supersedesBlockedDependencies.some((s) => s.targetEntity === targetEntity && s.degradedField === dep.degradedField)) {
+        decision.supersedesBlockedDependencies.push({ targetEntity, degradedField: dep.degradedField, pitfallCode: dep.pitfallCode });
+      }
+    }
+    return { ...target, blockedSourceDependencies: kept };
+  });
+  return { targetEntities: targets, decisions };
+}
+
+// Fields rp-mapper or the operator may already have set on a row, which a planning rerun keeps.
+// Everything else planning emits is bridge-owned structure (target, readiness, read variant,
+// artifacts, planner-owned status) and is refreshed; fields planning never emits -- field mappings,
+// transformations, relationships, notes, operator edits -- are always preserved.
+const PRESERVED_WHEN_SET = ['confidence'];
+
+/** Merge a bridge decision into an existing row without erasing the mapping work on it. */
+function mergeBridgeRow(existing, decision) {
+  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) return { ...decision };
+  const merged = { ...existing, ...decision };
+  // Only the planner's own provisional states may refresh. Reviewed exclusions,
+  // manual routing and other mapping decisions retain their status and reason.
+  if (existing.status && !['pending', 'migration-planned'].includes(existing.status)) merged.status = existing.status;
+  if (decision.readVariant === 'entity-plan' && existing.targetRef) {
+    for (const key of ['targetRef', 'targetDomain', 'targetEntity', 'targetClassification']) {
+      if (existing[key] !== undefined) merged[key] = existing[key];
+    }
+  }
+  for (const key of PRESERVED_WHEN_SET) {
+    if (existing[key] !== undefined && existing[key] !== null) merged[key] = existing[key];
+  }
+  return merged;
+}
+
+function upsertPlanRows(plan, decisions) {
+  if (plan.entities && typeof plan.entities === 'object' && !Array.isArray(plan.entities)
+    && !PLAN_ROW_KEYS.some((k) => Array.isArray(plan[k]))) {
+    for (const d of decisions) plan.entities[d.sourceEntity] = mergeBridgeRow(plan.entities[d.sourceEntity], d);
+    return plan;
+  }
+  const key = PLAN_ROW_KEYS.find((k) => Array.isArray(plan[k])) || 'entityDecisions';
+  const rows = Array.isArray(plan[key]) ? plan[key] : [];
+  for (const d of decisions) {
+    const index = rows.findIndex((row) => row && (row.sourceEntityRef === d.sourceEntityRef || (row.sourceEntity || row.entityName || row.entityKey) === d.sourceEntity));
+    const decision = key === 'entities' ? { entityKey: index >= 0 ? rows[index].entityKey || d.sourceEntity : d.sourceEntity, ...d } : d;
+    if (index >= 0) rows[index] = mergeBridgeRow(rows[index], decision); else rows.push(mergeBridgeRow(null, decision));
+  }
+  plan[key] = rows;
+  return plan;
+}
+
+async function writeJson(filePath, value) {
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  const staging = `${filePath}.writing`;
+  await fsp.writeFile(staging, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  await fsp.rename(staging, filePath);
+}
+
+/**
+ * Write the planned entities into the mapping artifacts. Refuses once the mapping review has
+ * been approved: adding an entity after the gate would skip the review it depends on.
+ */
+async function writeStructureBridgePlanning(projectDir, decisions) {
+  if (!projectDir) throw new Error('writeStructureBridgePlanning needs projectDir');
+  const approvals = await readJsonIfExists(path.join(projectDir, 'orchestration', 'approvals.json'));
+  const gate = approvals && approvals.mapping && approvals.mapping.status;
+  if (gate === 'approved' || gate === 'provisional') {
+    throw new Error(`mapping review is already ${gate}; re-open the mapping review before adding structure-bridge-plugin entities`);
+  }
+  const decisionPaths = [];
+  for (const decision of decisions) {
+    const filePath = path.join(projectDir, 'mapping', 'entity-decisions', `${slugify(decision.sourceEntity)}.json`);
+    // eslint-disable-next-line no-await-in-loop
+    await writeJson(filePath, mergeBridgeRow(await readJsonIfExists(filePath), decision));
+    decisionPaths.push(filePath);
+  }
+  const planPath = path.join(projectDir, 'mapping', 'mapping-plan.json');
+  const plan = (await readJsonIfExists(planPath)) || {};
+  await writeJson(planPath, upsertPlanRows(plan, decisions));
+  return { decisionPaths, planPath };
+}
+
+module.exports = {
+  REVIEW_GATE,
+  planStructureBridgeEntities,
+  partitionBlockedSourceDependencies,
+  writeStructureBridgePlanning,
+  sourceEntityRefOf,
+};

package/skills/wix-replatform/resources/rp-mapper/scripts/coverage-reconcile.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+'use strict';
+
+// Source-coverage reconcile check and decision writer.
+//
+//   node scripts/coverage-reconcile.js check <projectDir> [--json]
+//   node scripts/coverage-reconcile.js decide <projectDir> --coverage-id <id> --value provided|declined [--rationale <text>]
+//
+// `check` joins discovery/source-coverage.json, mapping/review/mapping-gaps.json and
+// orchestration/decisions.json by coverageId. Every coverage row needs exactly one valid
+// disposition: a mapping-gaps.json entry carrying its coverageId, a `sourceCoverage:<coverageId>`
+// decision, or (quick mode only) its declared exclusion.
+//
+// `decide` records a `sourceCoverage:<coverageId>` decision and removes that row's gap entries in
+// the same write, so the normal recovery path never creates a disposition conflict.
+//
+// Exit codes: 0 every row reconciles; 2 a row has no, two, a stale or a mismatched disposition, a
+// gap/decision names an unknown coverageId, or the coverage file is missing or malformed;
+// 1 usage error.
+
+const path = require('node:path');
+const {
+  reconcileProject,
+  recordCoverageDecision,
+  SourceCoverageError,
+} = require('../../../lib/source-coverage.js');
+
+function parseArgs(argv) {
+  const args = { command: null, projectDir: null, coverageId: null, value: null, rationale: null, json: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--coverage-id') { args.coverageId = argv[i + 1]; i += 1; }
+    else if (arg === '--value') { args.value = argv[i + 1]; i += 1; }
+    else if (arg === '--rationale') { args.rationale = argv[i + 1]; i += 1; }
+    else if (arg === '--json') args.json = true;
+    else positional.push(arg);
+  }
+  [args.command, args.projectDir] = positional;
+  return args;
+}
+
+function usage() {
+  return 'Usage: coverage-reconcile.js check <projectDir> [--json]\n'
+    + '       coverage-reconcile.js decide <projectDir> --coverage-id <id> --value provided|declined [--rationale <text>]\n';
+}
+
+function report(failures, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ ok: failures.length === 0, failures }, null, 2)}\n`);
+    return;
+  }
+  if (!failures.length) {
+    process.stdout.write('source coverage reconciles: every row has exactly one valid disposition\n');
+    return;
+  }
+  for (const item of failures) process.stderr.write(`${item.code}: ${item.message}\n`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!['check', 'decide'].includes(args.command) || !args.projectDir) {
+    process.stderr.write(usage());
+    return 1;
+  }
+  const projectDir = path.resolve(args.projectDir);
+  try {
+    if (args.command === 'decide') {
+      const result = await recordCoverageDecision(projectDir, { coverageId: args.coverageId, value: args.value, rationale: args.rationale });
+      process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
+    }
+    const result = await reconcileProject(projectDir);
+    report(result.failures, args.json);
+    return result.ok ? 0 : 2;
+  } catch (error) {
+    if (error instanceof SourceCoverageError) {
+      const failures = error.failures.length ? error.failures : [{ code: 'invalid_coverage', coverageId: null, message: error.message, sources: [] }];
+      report(failures, args.json);
+      return 2;
+    }
+    throw error;
+  }
+}
+
+main().then((code) => { process.exitCode = code; }).catch((error) => {
+  process.stderr.write(`${error.stack || error.message}\n`);
+  process.exitCode = 1;
+});

package/skills/wix-replatform/resources/rp-mapper/wix-business-solutions-taxonomy.md

@@ -25,7 +25,8 @@ This distinction must stay explicit in mapper output.
 It owns the purchase flow and operational commerce entities that are reused across multiple vertical apps.
 
 Typical `eCommerce` entities:
-- carts (the unified cart + checkout entity)
+- carts
+- checkouts
 - orders
 - order billing / refunds
 - payment and fulfillment state tied to orders
@@ -89,19 +90,19 @@ Main page:
 - [Integrating with Wix's Business Solutions](https://dev.wix.com/docs/build-apps/get-started/overview/integrating-with-wix-s-business-solutions)
 
 Short description:
-- Shared commerce platform for purchase flow and order operations. It is the canonical target for carts (Cart V2, which now also covers checkout) and orders, even when catalog data originates in a vertical app such as Stores or Bookings.
+- Shared commerce platform for purchase flow and order operations. It is the canonical target for carts, checkouts, and orders, even when catalog data originates in a vertical app such as Stores or Bookings.
 
 Primary entities:
 
 | Entity | What it does | Docs |
 | --- | --- | --- |
-| `cart` | The unified purchase-flow entity — holds line items, buyer/contact info, discounts, delivery, billing, and payment context all the way through placing the order. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
-| `current-cart` | The current cart for a visitor/member session — the same entity as `cart`, addressed by the shopper's session rather than a cart id. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
+| `cart` | First phase of the purchase flow; holds line items, buyer references, discounts, and pricing context before checkout | [About the eCommerce Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart/cart/introduction) |
+| `current-cart` | Visitor/member scoped cart used in live purchase flows | [About the eCommerce Current Cart API](https://dev.wix.com/docs/sdk/backend-modules/ecom/current-cart/introduction) |
+| `checkout` | Second phase of purchase flow; holds calculated prices, tax, billing, shipping, and discount state before order creation | [About the eCommerce Checkout API](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction) |
 | `order` | Final commerce record for completed or externally recorded purchases | [About the Orders API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/introduction) |
 | `order-billing` | Payment capture, void, and refund operations for eCommerce orders | [About the Order Billing API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-billing/introduction) |
 
 Mapper notes:
-- **A source system's separate "checkout" has no distinct Wix target.** The cart is the unified purchase-flow entity (there's no separate checkout), so map a source checkout's *input* state onto `cart`: billing → `paymentInfo.billingAddress`, shipping/delivery → `deliveryInfo`, applied coupons → cart `coupons`. **Calculated price *and* payment figures are NOT stored on the cart** — both the price totals (`summary.priceSummary`) and the payment breakdown (`summary.paymentSummary` — amount due, gift-card deductions, and the like) are computed on demand by Calculate/Estimate Cart (returned in a `CartSummary`), and the final figures live on the `order` after placement — so don't try to persist a source checkout's computed totals on the cart.
 - If the source platform exposes products and orders in one model, split catalog entities into the vertical app and transaction entities into `ecommerce`.
 - If the source has historical orders but no cart or checkout history, map directly to `order` and document missing pre-purchase state.
 

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

@@ -0,0 +1,40 @@
+---
+name: rp-preflight
+description: Validates the selected source and destination configuration before discovery.
+---
+
+# rp-preflight
+
+Run the deterministic preflight helper before discovery:
+
+```bash
+node skills/wix-replatform/scripts/orchestration-preflight.js <projectDir>
+```
+
+Use its structured result as authority. When it reports missing source configuration or
+credentials, route to `rp-source-inputs`; when it reports a destination issue, route to
+`rp-destination`. Do not begin discovery with a blocked preflight.
+
+## The recording line
+
+The result also carries a `telemetry_journal` check reporting whether this project is
+recording: `active`, `absent`, `finalized_only` or `unreadable`. Its status is always
+`info`, and `info` never affects the overall verdict — a run with no telemetry journal
+still passes preflight and still proceeds.
+
+The check only looks; the script then recovers. When the reading is `absent`,
+`finalized_only`, or an `unreadable` journal that replays to no run start, the preflight
+script starts recording itself (a damaged journal is first moved aside to
+`telemetry/events.unreadable-<timestamp>.jsonl`, every byte kept). The check keeps the
+original `journal` reading and adds `recovery` — `not_needed`, `started`,
+`set_aside_and_started` or `failed` — plus `recoveredRunId`/`recoveredAttempt`,
+`setAsideFile` or `recoveryError`. You do not need to act on this line.
+
+`recovery: failed` never changes the verdict or exit code, and is team-only evidence: do
+not relay it to the person running the migration (the `rp-telemetry` "never mention"
+rule). Call `rp-telemetry` `start` at run begin as before; preflight is the safety net.
+
+## Output
+
+`orchestration/preflight.json` — the script's structured result (`status: pass | blocked |
+failed` plus per-check detail). This is what a dispatched run must produce.

package/skills/wix-replatform/resources/rp-project-intake/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: rp-project-intake
+description: Resolves the active migration project and the minimum intake decisions needed to route it.
+---
+
+# rp-project-intake
+
+Use when the router reports unresolved project, delivery mode, destination strategy, or
+source mode.
+
+Resolve project precedence: explicit user project, current project context, the sole
+project under the migrations root, otherwise ask the user to choose. Never infer from a
+sibling project.
+
+Project initialization also creates `EXPECTATIONS.md` at the project root when it is
+missing. Mention it as an optional place to record expectations; do not make it an intake
+question or replace a user's existing file.
+
+Resolve delivery mode before destination creation: default to `management`; choose
+`website` for frontend only; choose `management_and_website` when the user wants both a
+backend migration and a customer-facing storefront. Accept `both` as an input alias for
+`management_and_website`, then record the canonical value in `orchestration/decisions.json`.
+
+For a new destination site, the site type is an explicit operator choice with no
+default: Headless (a website developed in code), Wix Studio, or Wix Harmony. It decides
+where the imported data lives and cannot be changed later as a setting. A generic "Editor"
+answer is incomplete until Studio or Harmony is named; the classic Wix Editor is not offered.
+Ask it together with Harmony's business type as one combined question — store,
+bookings/services, another business, or "not sure, start blank" — never as two questions.
+Record it with `orchestration-state.js decide --key targetSiteType --value <type>
+[--business-type store|bookings|other]`; a Harmony answer that names no business type records
+`unknown`. A choice the operator already gave counts; do not ask again. `rp-destination` raises
+the durable request when it is still missing. Existing-site adoption needs no type.
+
+For delivery modes that include management, also record `managementImportMode`. Default to
+`standard`; accept an explicit user choice of `quick` at intake even before the source URL is
+probed. The later source-inputs/probe result validates whether a matching quick adapter exists;
+never promise quick support merely from the user's choice.
+
+Record `faceliftMode=requested` only when the user explicitly asks for a post-clone UI/UX
+facelift. It is optional, defaults to off, and is not a substitute for normal clone fidelity.
+In explicit user-requested 1-click mode include this choice in the initial grouped intake so the later, separate
+facelift stage is authorized without another routine approval.
+
+In normal mode ask only the current missing decision. In explicit user-requested 1-click mode
+record `automationMode=one_click` with `source=user`, collect every still missing intake value
+together, record the answers, and continue. Never infer one-click from an uploaded file or
+execution surface. Delegate all destination,
+source-file, and credential procedures to their dedicated modules.
+
+## Output
+
+The resolved project, plus `orchestration/decisions.json` entries for whichever of
+`deliveryMode`, `managementImportMode`, `targetSiteType` (with `targetSiteBusinessType` for
+Harmony), `faceliftMode`, and `automationMode` this run resolved. This is what a dispatched run must produce.

package/skills/wix-replatform/resources/rp-quick-runtime/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: rp-quick-runtime
+description: Shared deterministic target-limit recovery and final-report runtime every rp-quick-<platform> quick-mode adapter uses before a Wix Stores write.
+---
+
+# rp-quick-runtime
+
+Not invoked directly — this is a shared library (`lib/limit-recovery.js`), not a standalone
+adapter. Every `rp-quick-<platform>` quick-mode adapter (`rp-quick-shopify`, `rp-quick-woocommerce`)
+requires it from its own `scripts/quick-mode.js` and must use it from its first version. Platform adapters own source extraction and field semantics; this runtime owns
+target-limit enforcement, recovery-ledger aggregation, and the human-readable final report — so a
+Wix Stores validation limit never silently turns an otherwise-valid record into an opaque skip.
+
+```js
+const recovery = require('../rp-quick-runtime/lib/limit-recovery.js');
+
+const normalized = recovery.normalizeProduct({ sourceId, sku, tagIds });
+// normalized.sku / normalized.tagIds are the capped/trimmed values to write;
+// normalized.recoveries lists what was capped or trimmed, if anything.
+await writeProduct({ ...product, sku: normalized.sku, tagIds: normalized.tagIds });
+// Record written_with_loss only after the target write succeeds, and never in a dry run.
+if (normalized.recoveries.length) {
+  if (!dryRun) await recovery.appendRecoveries(projectDir, adapterName, sourceId, normalized.recoveries);
+  recovery.recordRecoveredRecord(summary, normalized.recoveries);
+}
+// ...after the run:
+await recovery.writeFinalReport(projectDir, summary, { dryRun });
+```
+
+`normalizeProduct` applies the two verified Stores limits deterministically: caps `tagIds` at
+`STORES_PRODUCT_TAGS_MAX` (first-seen source order, extras omitted) and trims `sku` to
+`STORES_SKU_MAX` Unicode-safe characters with a stable source-ID-derived suffix so a trimmed SKU
+stays unique. Every cap/trim is reported back in `recoveries[]`, never applied silently.
+
+`appendRecoveries` ledgers each recovery to `execution/quick-limit-recoveries.ndjson` under the
+adapter's own name, tagged `outcome: written_with_loss` — the durable record of what was
+preserved versus lost, per source record. Call it only after the target write succeeds.
+
+`recordRecoveredRecord` increments `summary.recovered` once for the written source record and
+increments `summary.recoveryCounts` once for each recovery event on that record.
+
+`writeFinalReport` renders `execution/quick-mode-final-report.md`: a count of records imported
+with deterministic recovery plus a per-recovery-code breakdown, so the operator gets a compact,
+actionable account instead of a bare skip count. It adds a "Collections not migrated" section
+from `summary.excludedCollections`, a "Products to check" section from
+`summary.writtenUnverified.product`, and an inventory pointer when `summary.inventory` is set.
+With `{ dryRun: true }` it writes `execution/dry-run-final-report.md` instead and sets
+`summary.finalReport` to that path, so a dry run can never overwrite or stand in for the live
+report. A dry run must write no live artifact at all (report, ledger, audit log, crosswalk or
+marker); adapters skip those writes when `dryRun` is true. `writeFileAtomic` (temp file, then
+rename) is the shared way to publish a report that a crash must not leave half-written.
+
+`lib/import-progress.js` holds three more shared pieces. Each adapter's `import` first calls
+`assertQuickImportAdapter`, which fails unless the plan and extract manifest both carry exactly
+the loaded contract's `{ id, version, fingerprint }`. It then calls
+`writeQuickImportStartedMarker(projectDir, plan.adapter)` before its first destination write.
+It is skipped on a dry run and never rewritten on resume; concurrent first attempts publish
+one marker (temp file, then a no-replace hard link). It writes
+`state/quick-import-started.json`, which the router reads as evidence of an interrupted import.
+`validateQuickExecutionManifest` is the router's check of the manifest that `plan` writes.