@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-replatform/resources/rp-setup-discovery/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: rp-setup-discovery
+description: >-
+  Derives Wix environment prerequisites (apps, collections, schemas) from an approved
+  mapping plan. Use after mapping review and before import code generation.
+---
+
+# rp-setup-discovery
+
+Determine the Wix-side setup required before import can run safely.
+
+## Purpose
+
+This skill analyzes the approved mapping artifacts and derives environment prerequisites
+such as installed apps, SMC collections, extended-fields schemas, references,
+permissions, and any other target-system configuration dependencies.
+
+## Required inputs
+
+- `migrations/<project>/mapping/mapping-plan.json`
+- `migrations/<project>/mapping/review/mapping-gaps.json`
+- `migrations/<project>/mapping/review/mapping-summary.md`
+- `migrations/<project>/orchestration/approvals.json`
+- any Wix environment constraints or destination account details provided by the user
+
+## Workflow
+
+1. Confirm the mapping review checkpoint has been accepted, then read the mapping plan and
+   mapping summary and identify every non-native requirement.
+2. For mapped entities with `targetRef`, load compact domain/entity summaries through
+   `rp-target-wix/scripts/domain-knowledge.js summarize-entities` and include
+   `wixAppsRequired`, `setupRequirements`, target classification, and write verification
+   level in setup analysis.
+3. Determine which Wix apps must be installed or enabled.
+4. Determine which SMC collections must exist.
+5. Determine which extended-fields schemas, references, enums, or validation rules must exist.
+6. Capture dependency ordering where setup steps depend on each other.
+7. Write a setup artifact that downstream execution can verify.
+
+## Artifact to create or update
+
+- `migrations/<project>/setup/run.json`
+- `migrations/<project>/setup/setup-plan.json`
+- `migrations/<project>/setup/setup-requirements.json`
+- `migrations/<project>/setup/setup-blockers.json`
+- `migrations/<project>/setup/llm-handoff.json`
+- `migrations/<project>/setup/review/setup-summary.md`
+- `migrations/<project>/orchestration/checkpoints.json`
+
+Treat `mapping/review/mapping-summary.md` as the user-facing statement of intent and
+`mapping/mapping-plan.json` as
+the detailed contract. If they materially disagree, halt and send the workflow back to
+`rp-mapper` to correct them before deriving setup requirements.
+
+## Minimum contents
+
+- required Wix apps
+- local crosswalk authority and optional CMS mirror requirements
+- required collections and schemas
+- required field definitions
+- permissions or access prerequisites
+- setup order
+- manual steps vs. steps that can be automated
+- verification criteria for each requirement
+
+## Optional source reachability setup for media
+
+If the mapping imports media by URL and the source profile shows `localhost`,
+`127.0.0.1`, or another private-only source URL, add an optional setup note for media
+reachability. This is **not** a blocker for non-media entities and should not be framed as
+a required Wix-side app/setup item. As far as we know today, it only affects Wix Media
+import because Wix's import-from-URL API fetches files from Wix servers.
+
+Offer two options in `setup/review/setup-summary.md` and preserve the machine-readable
+effect in `setup/setup-blockers.json` or `setup/setup-requirements.json`:
+
+- Expose the local source through a public HTTPS tunnel before live media import.
+- Skip/defer media import for the first live run and continue non-media entities.
+
+For ngrok, include:
+
+```bash
+brew install ngrok
+ngrok config add-authtoken "<YOUR_AUTHTOKEN>"
+ngrok http 8090
+export WP_BASE_URL=https://<id>.ngrok-free.app
+```
+
+Tell the user to use the HTTPS forwarding URL as `WP_BASE_URL` / `SOURCE_URL`, or ensure
+generated code rewrites source media URLs from the local base URL to the tunnel base URL.
+
+## Verifying Wix APIs
+
+Confirm that the apps, collections, field types, and references you require actually
+exist in Wix with the names/types you state — never invent them.
+
+- Verify at the moment you write the requirement; do not defer it. Verify **enum
+  values**, not just names: confirm each `Field.type` against the Create Data Collection
+  schema. (Common trap: there is no `SLUG` type — a Wix slug is a `TEXT` field.)
+- If a Wix tool surface such as Wix MCP is available, use it as a fast verification aid.
+- 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, and mark the
+  requirement `unverified` so a human confirms it before `rp-execute-setup` runs.
+
+## Standing requirement: mute site notifications (spec 0012)
+
+Emit a **`mute-site-notifications`** requirement into `setup/setup-plan.json` and
+`setup/setup-requirements.json` whenever mute is in effect:
+
+- `WIX_SITE_STRATEGY=new` — **always**, as a standing rule keyed on the strategy value
+  alone. Not derived from mapping decisions, domain knowledge, or agent judgment, and not
+  conditional on `WIX_MUTE_NOTIFICATIONS` (for new sites the mute is unconditional).
+- `WIX_SITE_STRATEGY=existing` — only when the owner explicitly opted in with
+  `WIX_MUTE_NOTIFICATIONS=on`. Under the existing-site default (`off`), emit no
+  requirement.
+
+Requirement contents: severity **blocker**, automation mode `automatable`, ordered
+**first among setup writes** (before app installs, collection creation, and any other
+provisioning), executed via the `muteSiteNotifications` primitive in
+`rp-target-wix/lib/wix-writers.js` (VERIFIED 2026-08-04) with a project-identifying
+`reason` (`RePlatform migration — <project>`). Verification criterion:
+`getSiteMuteState` returns `muted: true`. Auth note for the requirement: the call must
+use the CLI-minted site token (`WIX_AUTH_TOKEN`) — an account API key gets 403.
+
+**Config validation (fail fast):** `WIX_MUTE_NOTIFICATIONS=off` together with
+`WIX_SITE_STRATEGY=new` is a validation error — halt with the config conflict recorded
+rather than emitting artifacts. (`rp-import-codegen` re-validates the same rule.)
+
+## Crosswalk authority and CMS mirror
+
+Local files under `migrations/<project>/state/crosswalk/` are the durable
+`sourceId -> targetId` authority for native Wix entities. Do not make CMS setup a minimum
+requirement for native-entity idempotency.
+
+Create/provision CMS **`ImportCrosswalk`** only when the approved mapping plan explicitly
+requests a CMS mirror (`cmsMirror: "download" | "upload" | "download-and-upload"`). The
+mirror is compact site-local reference data and a pre-execution seed source for
+existing-site flows when valid local crosswalk state does not already exist. Add a CMS
+quota warning whenever a mirror is requested.
+
+If older artifacts call the optional mirror `MigrationRefs`, normalize it to
+`ImportCrosswalk` and call out the rename in the artifact so downstream setup/codegen
+share one contract.
+
+## Classifying manual vs. automatable
+
+Do not assert "manual" / "cannot self-provision" by assumption — check the API surface.
+
+- Enabling a Wix app (Blog, Members, etc.) **is** automatable via the App Installation
+  API; classify it automatable and cite the method. (Common trap: do not mark Blog or
+  Members "cannot self-provision" — both are installable via the API.)
+- When the migration carries a product catalog, emit a **`stores-catalog-v3` requirement**
+  alongside the Wix Stores app install: expected state `catalogVersion: V3_CATALOG`, verified
+  read-only via `GET https://www.wixapis.com/stores/v3/provision/version`, severity
+  **blocker**, automation mode `automatable` (it is provisioned by scaffolding the site from
+  the `commerce` template — see `replatform` → "Headless site creation"). A Stores install
+  alone does not imply V3; a `blank`-scaffolded site comes up `V1_CATALOG` and cannot be
+  converted, so this must be a first-class requirement rather than an assumption.
+- Creating CMS collections is automatable; enabling Wix Data itself is automatable by
+  installing the **Wix Data app `appDefId e593b0bd-b783-45b8-97c2-873d42aacaf4`** via the
+  App Installation API, after which `POST /wix-data/v2/collections` creates NATIVE
+  collections with no `WDE0110` (verified live 2026-06-10; see `rp-execute-setup`).
+- Only storage-plan upgrades, external-system credentials, and account billing are
+  genuinely manual. Mark something manual only after confirming no API covers it.
+
+## Runtime policy
+
+This phase is deterministic planning work. It does not create a second approval gate.
+`setup/review/setup-summary.md` is supporting execution-planning context, not a separate
+user approval checkpoint.
+
+Verify names and enums rather than emitting `unverified` by default. Classify
+automatability by checking the API surface (see above), not by assumption. If a direct
+verification aid is unavailable, use the documented fallback and mark the requirement
+`unverified` so downstream steps surface it before execution.
+
+## Guardrails
+
+- Separate required setup from optional optimizations.
+- Avoid embedding import logic here; this file is about prerequisites.
+- Be explicit about which requirements come from which mapping decision.
+- Do not guess setup names or enum values when you cannot verify them. Mark them
+  `unverified` and surface the risk before execution.

package/skills/wix-replatform/resources/rp-source-csv/SKILL.md

@@ -0,0 +1,478 @@
+---
+name: rp-source-csv
+description: >-
+  CSV file source adapter: parse core, vendor fingerprinting (Shopify, WooCommerce, Magento,
+  BigCommerce), layout inference, file-set handling, and read contract for codegen. Use when
+  the migration starts from one or more CSV/export files instead of a live source URL.
+---
+
+# rp-source-csv
+
+CSV **source adapter**. Owns every CSV-specific detail the platform-agnostic skills must not
+hardcode: how to parse a file, how to identify which vendor produced it, how its rows group
+into entities, how a set of files resolves into entity streams, and what a generated reader
+must get right.
+
+## When this skill is used
+
+This is not a stage in the migration flow — it is a reference consulted by two stages:
+
+- **`rp-discovery`** consults the *Capture* section to sample the files and produce the
+  canonical `source-profile.md` + `source-schema.json`.
+- **`rp-import-codegen`** consults the *Read contract* section to generate a reader that
+  extracts CSV data correctly (grouping, derived entities, empty-vs-absent) into durable
+  project-local files for the later import step.
+
+`rp-execute-import` never consults this skill — by the time execution runs, the CSV-specific
+knowledge is already baked into the generated reader.
+
+## Platform identity
+
+- Source platform: `csv` — a **file-provided** flow, not a URL probe.
+- Set `"platform": "csv"` in the emitted `source-schema.json`, and record the detected
+  vendor per file in `sourceMeta.vendor` / `sourceMeta.sourceFiles[]`.
+- Record `sourcePlatform=csv`, `sourceMode=files_only`, and **every** input file in
+  `fileInputPaths` in `orchestration/decisions.json`. Preflight requires no source env keys
+  for `csv`; the `files_only` branch enforces a non-empty `fileInputPaths` instead.
+
+## Three layers
+
+1. **A generic core** — `lib/csv-parse.js` (parse, dialect detection, type sniffing) and
+   `lib/csv-layout.js` (layout inference, derived entities). Knows nothing about commerce and
+   handles any CSV, including hand-rolled ones.
+2. **Per-vendor overlays** — declarative JSON profiles under `vendors/` that specialize the
+   core with a vendor's fingerprint anchors, known layout, column→Wix pre-map, and quirks.
+   v1 ships **shopify, woocommerce, magento, bigcommerce**.
+3. **A fingerprint detector** — `lib/csv-fingerprint.js` picks the overlay from the header
+   set, or honors a user-stated vendor, and falls back to `custom` below the threshold.
+
+**The overlay is advisory, never authoritative.** The authoritative record of which columns a
+file contains is always the header row read at discovery time. The overlay only (a)
+*identifies* the vendor and (b) *pre-fills* mappings the LLM would otherwise propose.
+
+## Capture (discovery-time)
+
+Sampling the files to learn their shape — **not** a bulk load.
+
+Before capture, verify `migrations/<project>/config/source.csv.env`. Create it if missing,
+using empty values for the user to fill:
+
+```bash
+CSV_INPUT_ROOT=            # optional; directory the input paths are recorded relative to
+CSV_DELIMITER=             # optional; blank = auto-detect , ; \t |
+CSV_ENCODING=              # optional; blank = auto-detect (UTF-8 / BOM)
+CSV_VENDOR=                # optional; user-stated vendor overrides fingerprint detection
+CSV_MEDIA_URL_REWRITE_FROM=
+CSV_MEDIA_URL_REWRITE_TO=
+```
+
+Unlike `source.wordpress.env`, **`source.csv.env` is not secret-bearing** — it holds
+delimiter/encoding/vendor/rewrite hints only, no credentials. Regular file handling applies.
+There is **no acquisition-mode fork and no credentials request** for a CSV run.
+
+1. Run the deterministic capture script **from this skill's directory** (the folder
+   containing this `SKILL.md`; see `CONVENTIONS.md`):
+
+   ```
+   node scripts/csv-discovery.js --file <path> [--file <path> ...] \
+     --out-dir <migrations-root>/<project>/data/csv-discovery
+   ```
+
+   `--file` is repeatable; pass the **whole file set in one run** so roles and split files
+   are resolved together. For long runs, pass `--progress-log <path>` and poll it per
+   `CONVENTIONS.md#progress-log-polling`.
+
+   Useful options: `--vendor` (override detection), `--delimiter` / `--encoding` (override
+   detection), `--role <path>:<role>` (name a file's entity when the script cannot),
+   `--allow-header-superset` (union split files whose headers differ), `--scan-rows`.
+
+2. Per run the script: reads each header → detects the dialect → fingerprints the vendor per
+   file → assigns a role per file and concatenates split files → resolves the layout (overlay
+   or generic classifier) → derives `column-values` entities → diffs the real header against
+   the matched profile → samples head and tail rows → infers per-column
+   type/cardinality/requiredness/examples → writes the raw dump. Because headers are read
+   fresh every run, discovered fields are never limited to what the profiles know.
+
+3. It writes into `--out-dir`:
+   - `README.md` — the index: files, vendor detection with evidence, layout, entities,
+     profile drift, warnings.
+   - `fileset.json` — machine-readable `sourceFiles[]`, streams, vendor, dialect, layout,
+     drift, mapping hints, entities and relations. **This is what `rp-discovery` synthesizes
+     `source-schema.json` from.**
+   - `raw-capture.json` — per-column detail plus head/tail samples.
+   - `<role>--<entity>.md` — one per entity.
+
+4. **Honor the halt.** When the capture reports `halt: true` (ambiguous layout, unknown file
+   role, conflicting split-file headers, mixed vendors for one role), stop and ask the user
+   the question named in the warning rather than synthesizing a schema from a guess.
+
+5. **Record counts are scan-based.** The script streams each file in full for its row count
+   and retains the first `--scan-rows` rows (default 5000) for inference. When
+   `raw-capture.json` reports `scan.truncated`, say so in `source-profile.md` instead of
+   presenting a sampled count as exact.
+
+The raw capture is evidence, not a hand-off artifact. `rp-discovery` synthesizes it into the
+canonical artifacts and records traceability pointers (`rawDiscovery`, per-entity `rawFile`).
+
+## Layer 1 — the generic core
+
+`lib/csv-parse.js` is the CSV analogue of `rp-source-wordpress`'s `wp-http.js`: dependency-free
+and reused by **both** the capture script and the generated reader so the sampler and the
+importer parse identically. It handles what breaks a naive `split(',')`:
+
+- **delimiter detection** (`,` `;` `\t` `|`), scored by field-count consistency **and** field
+  count, since a semicolon file whose text fields each contain a comma splits perfectly
+  consistently on `,` too. `CSV_DELIMITER` always wins.
+- **RFC-4180 quoting**: embedded delimiters, embedded newlines, `""` escapes. A quote opens a
+  field only at field position 0; `a"b` is three literal characters.
+- **encoding / BOM**: the mark is stripped before the header is read. A UTF-16 BOM fails fast
+  naming `CSV_ENCODING` rather than producing mojibake — full transcoding is out of scope.
+- **line endings**: `\n`, `\r\n`, and lone `\r`, including a `\r\n` split across a chunk
+  boundary. A newline inside quotes is data and is preserved verbatim.
+- **empty vs absent** (below).
+- **streaming**: rows are yielded without loading the file.
+
+### Empty vs absent is detected, not assumed
+
+Whether an empty cell means "absent" is a property of the **writer's quoting policy**, not of
+the datum: exporters that quote every field (Excel, Magento) can only ever produce a quoted
+empty, and exporters that quote nothing unnecessary can only ever produce an unquoted one.
+
+So the parser returns **strings only, never `null`**, with an optional parallel `quoted[]`
+array, and `detectEmptyPolicy` decides once per file:
+
+- `present-if-quoted` — the file contains **both** forms, so it genuinely distinguishes them.
+- `always-empty` — it contains only one form, so the distinction carries no information.
+
+The policy is recorded in `sourceMeta.dialect.emptyPolicy` and applied through
+`coerceEmpty(value, isQuoted, policy)`. Generated readers must use it, so a required Wix field
+is never fed an empty string the source did not actually have. This also keeps split files
+(shape C) consistent when two parts were written by different tools.
+
+## Layer 2 — vendor overlays
+
+Each supported vendor is a declarative JSON profile under `vendors/`. Overlays are **data, not
+code**, because they are numerous, additive, and pure lookup: adding or updating a vendor is a
+data-file edit plus a header fixture, with no change to any skill logic.
+
+```jsonc
+{
+  "vendor": "shopify",
+  "profileVersion": "2026-07",              // provenance; bump when the format changes
+  "sourceOfTruth": "https://help.shopify.com/.../csv",
+  "anchors": {
+    "required": ["Handle", "Title"],        // a FEW STABLE columns — never the full schema
+    "strong":   ["Body (HTML)", "Variant SKU", "Variant Price", "Option1 Name", "Vendor"],
+    "negative": ["Attribute 1 value(s)"]    // presence disproves this vendor
+  },
+  "layout": {
+    "pattern": "grouped-by-key",
+    "groupKey": "Handle",
+    "continuation": "blank-key",
+    "parentEntity": "product",
+    "childEntity": "variant",
+    "columnGroups": [                       // which columns belong to which entity
+      { "entity": "variant", "prefixes": ["Variant ", "Option1 "], "columns": ["Cost per item"] },
+      { "entity": "image",   "prefixes": ["Image "] }
+    ]
+  },
+  "derived": [                              // entities synthesized from a column's values
+    { "entity": "category", "fromColumn": "Product Category",
+      "hierarchySeparator": ">", "hierarchical": true, "linkPolicy": "leaf" }
+  ],
+  "fileRoles": [{ "role": "product", "filenameHints": ["products_export", "products"] }],
+  "columnMap": [{ "wixTarget": "variant.sku", "aliases": ["Variant SKU", "SKU", "variant_sku"] }],
+  "quirks": ["Blank-Handle rows continue the previous product", "..."]
+}
+```
+
+Column matching is **normalized + alias-based**: lowercase, NFKC, strip punctuation and
+whitespace. `Body (HTML)` → `bodyhtml`, and `Option1 Name` ≡ `Option 1 Name`. This absorbs
+casing changes and renames without a code change.
+
+**`columnGroups` is the one thing the data cannot supply.** Shopify's `Image Src` and
+`Variant SKU` both vary within a product group, so only a declaration can say that one is a
+third collection and the other is the variant. Generic derivation still covers every column
+the overlay does not name — including new columns a vendor adds later.
+
+An overlay feeds two stages:
+
+- **Discovery** — `layout` + `quirks` resolve grouping deterministically, avoiding the generic
+  ambiguity halt. Layout traps are stable and hard to infer, which is what makes them worth
+  encoding.
+- **Mapping** — `columnMap` pre-fills `sourceMeta.mappingHints[]` so `rp-mapper` reviews and
+  corrects instead of authoring from scratch.
+
+A `custom` file has no overlay: it runs core-only, and the mapper leans more on the LLM and the
+user at the same review checkpoint. A fully stale overlay degrades to exactly that experience —
+the floor, not a failure.
+
+## Layer 3 — fingerprint detection
+
+`lib/csv-fingerprint.js` identifies the vendor from the header row:
+
+```
+requiredRatio = |required ∩ header| / |required|      (normalized EXACT match)
+strongRatio   = |strong   ∩ header| / |strong|
+score = requiredRatio === 1 ? 0.50 + 0.50·strongRatio
+                            : 0.60 · requiredRatio · (0.50 + 0.50·strongRatio)
+negative anchors present -> score *= 0.35
+match iff score >= 0.70 AND matchedStrong >= 2 AND (winner − runnerUp) >= 0.15
+```
+
+- **Anchors never alias-match.** Aliases are permissive for *mapping*; permissiveness is poison
+  for *identification* — Shopify's `variant.sku` aliases include a bare `SKU`, which every
+  WooCommerce and Magento export also has.
+- **Ratios, not counts.** Anchor ratios are bounded 0..1, so a wide CSV cannot inflate a match.
+  Do **not** reintroduce a header-count normalization: dividing by header count penalizes wide
+  files and inflates narrow ones, which is what lets a 6-column near-miss flip to a false match.
+- Ties, sub-threshold scores, and files with fewer than two strong anchors → `custom`.
+- A **near miss** (a drifted vendor export that lost a required anchor) is reported as
+  `nearMiss` so it becomes a user question, never silence.
+- `CSV_VENDOR` / `--vendor` **overrides** detection, but detection still runs: a disagreement
+  is recorded as `conflict: { stated, detected }` and surfaced.
+
+## Layout — how rows group
+
+`lib/csv-layout.js` resolves the layout: `flat`, `grouped-by-key` (blank-key or repeat-key
+continuation), or `sectioned`. It runs for **custom** files and as a **fallback** when a matched
+overlay does not pin the layout — including when the overlay's declared `groupKey` is missing
+from the header, which is recorded as `overlay-groupkey-missing` rather than crashing.
+
+### A pinned layout is verified, not believed
+
+An overlay's `continuation` is a **claim about the rows**, not a fact about the vendor, and it is
+checked against the sample before it is used. Shopify is the reason: most exports blank the
+`Handle` on continuation rows, but some repeat it on every row. Pinning `blank-key` against a
+repeating file fails *silently* — no key is ever blank, so no row ever continues a group, and a
+50-product file is captured as 82 single-row products with 32 blank titles.
+
+The check fires only when the two modes would group **differently**: with one row per group both
+readings produce the same boundaries, and reporting drift there would be noise.
+
+| Pinned | Rejected when | Then |
+| --- | --- | --- |
+| `blank-key` | the key column is never blank | continuation corrected to `repeat-key` |
+| `repeat-key` | the key column is blank on some row | continuation corrected to `blank-key` |
+
+On rejection the generic classifier is consulted about the **disputed field only**. Which column
+groups the rows is the part vendors do not change, and the overlay's `groupKey` has just been
+confirmed present in the header — so a generic candidate naming that same column corroborates the
+observed mode *even when the classifier as a whole halted*, because its halt is about **picking**
+a key, not about this one. When corroborated, the continuation is corrected and the rest of the
+overlay (entity names, `columnGroups`) is kept, with `source: overlay-continuation-corrected` and
+the classifier's confidence instead of the pin's `1`. When no candidate groups on the declared key
+either, nothing is trustworthy enough to pin and the whole inferred layout is used
+(`inferred-after-overlay-mismatch`).
+
+Both outcomes append to `layoutConflicts[]` and raise a warning — never a silent correction. Do
+**not** "fix" this by re-pinning `repeat-key` in the overlay: exports vary, so that only moves the
+same silent failure to the other half of them.
+
+Deterministic-first: when signals are clear it sets the pattern; when they are ambiguous it
+returns `pattern: 'unknown'` with `halt: true` and the ranked candidates, and discovery stops to
+ask the user.
+
+Signals worth knowing:
+
+- **blank-key** requires the key column's non-blank values to be unique — a key never reappears
+  after an intervening key. Two candidate columns that produce the **same** group boundaries
+  (Shopify's `Handle` and `Title` both go blank on continuation rows) are *equivalent labels*,
+  not an ambiguity; different boundaries are a genuine ambiguity and halt.
+- **repeat-key** additionally requires a supporting parent column — some other column constant
+  inside each run and different between runs. Without it, a flat product list merely *sorted* by
+  category is indistinguishable from a grouped one, and would be split into bogus parents and
+  children.
+- **sectioned** requires a column-population skew: partitioned by the discriminator, some other
+  column's blank rate must differ by ≥ 0.7 between partitions. Without that test every
+  `Published` or `Tax class` column is a false discriminator.
+- When a blank column's blankness is a pure function of the discriminator value, the blank-key
+  reading is already **explained by the sectioning** and does not compete with it — this is what
+  keeps a WooCommerce export from looking ambiguous.
+
+### Parent vs child columns
+
+A column belongs to the parent, to the child, or to a declared collection. The rule is
+**within-group variance**, not blankness:
+
+- A column that varies inside a group in ≥80% of multi-row groups is a **child** column.
+- A column blank on every continuation row and populated on the head row is a **parent** column.
+- Anything else is reported as `ambiguousColumns` rather than guessed.
+
+The naive rule — "child columns are the ones populated on continuation rows" — is **wrong** for
+the most important case: a Shopify product's first variant lives on its group head row, and a
+single-variant product has no continuation rows at all.
+
+Precedence: overlay `columnGroups` assigns the entity, generic derivation covers everything the
+overlay does not name, and a disagreement is recorded in `layoutConflicts[]` with the overlay
+kept. An overlay can never *lose* a column — that is what "advisory, never authoritative" means
+in practice.
+
+`layoutConflicts[]` carries both kinds of disagreement, because a reviewer asks the same question
+of both — *where did this capture stop believing the overlay?* Column-level entries name a
+`column`; layout-level entries (`overlay-continuation-mismatch`, `overlay-groupkey-missing`,
+`overlay-discriminator-missing`) carry a `kind` and a `resolution`.
+
+A child's `recordCount` is the number of rows that populate **at least one** child column, not the
+group's row count: a continuation row carrying only an extra image is an image, not a variant.
+
+## Entity origins — rows, row groups, and column values
+
+An entity in a CSV migration comes from one of three origins, recorded per entity so the reader
+knows how to materialize it:
+
+- **`file-rows`** — one row = one entity (a flat `categories.csv`; also a sectioned file's
+  parent or child rows, with `filter: { column, includeValues | excludeValues }`).
+- **`row-group`** — a group of rows = one entity (a Shopify product, its variants, its images),
+  with `groupKey`, `continuation`, and `columnGroup` where relevant.
+- **`column-values`** — the **distinct values of a column** = an entity set. This is how
+  categories and tags arrive in every named vendor's export.
+
+For `column-values`, capture records the source column, both separators, and the distinct-value
+count; the reader emits a synthetic entity file (one record per distinct path, ancestors
+included) plus the linking relation. Because the result is an ordinary entity from `rp-mapper`'s
+point of view, the mapper maps it with no special handling and the existing dependency ordering
+creates categories before products.
+
+Non-obvious rules the implementation depends on:
+
+- **Split the multi-value separator first, then the hierarchy separator.** WooCommerce's
+  `Clothing > Shirts, Sale` is two categories, one nested. The other order produces a category
+  literally named `Shirts, Sale`.
+- A separator inside a value is escaped by quoting **inside the cell**
+  (`"Home, Garden > Tools", Sale`), so the inner split is RFC-4180 aware too.
+- Records are emitted **depth-ascending**, so a parent is always created before its child.
+- Only the **leaf** is linked to the product (`linkPolicy: "leaf"`); whether ancestors are also
+  attached is a mapping decision.
+- Only **group-head rows** are read, so a Woo variation row does not double-count its product's
+  categories.
+- Generic detection for custom files is deliberately narrow: `>` is auto-detected but `/` is
+  not (it matches every URL column), markup-bearing columns are skipped, a multi-value split
+  must collapse the distinct count, and a column is only auto-derived when its **name** says it
+  is a taxonomy. Everything else is proposed to the user.
+
+Set **`hierarchical: true`** on a nested derived entity. A hierarchical source taxonomy mapped
+to a flat Wix target triggers the mapper's mandatory faithfulness-ledger entry; without the flag
+the flatten happens silently.
+
+## File sets — roles and concatenation
+
+`lib/csv-fileset.js` resolves a list of input paths into logical entity streams. Four shapes
+occur in practice; **A, B and C are v1**, D is v1.1:
+
+| Shape | Example | Handling |
+|---|---|---|
+| A. one file, grouped | Shopify `products_export.csv` | one stream, several entities |
+| B. many files, independent entities | `products.csv` + `customers.csv` | one stream per role |
+| C. many files, same entity split | `products-part1.csv` + `-part2.csv` | one stream, `partOf` recorded |
+| D. many files, related entities | FK columns across files | **v1.1** — schema designed, detection deferred |
+
+**Role assignment** walks a ladder, recording `roleSource` at each step: explicit `--role` →
+vendor `fileRoles.filenameHints` → generic filename tokens (whole tokens only, last token wins,
+so `product-images.csv` is media) → header anchors → `unknown` **with a halt**. A role is never
+invented from the filename stem; an entity map full of `weird-export` entities is worse than one
+honest question.
+
+**Same-entity concatenation (shape C)** requires the same *normalized column-name set*:
+
+- reordering, case, whitespace and BOM differences are tolerated — names are the identity, and
+  each part keeps its own `columnOrderMap`;
+- a subset/superset header does **not** silently concatenate. It is legitimate (a re-export
+  after the vendor added a column) but it changes what a blank cell means for half the rows, so
+  it halts with the exact diff; `--allow-header-superset` unions the parts and records
+  `driftAcrossParts`;
+- files sharing a role but only a small column overlap (Jaccard < 0.9) are a `role-collision`,
+  not two parts of one export;
+- part order is a numeric-suffix-aware natural sort, so `part10` follows `part2`;
+- `partOf` and `rowOffset` are recorded so any extract row traces back to its file.
+
+**Mixed vendors** are allowed *across* roles (Shopify products plus a hand-rolled
+`categories.csv` is a real bundle) but two files of the **same** role from different vendors
+halt.
+
+## Read contract (codegen-time)
+
+What a generated CSV reader must get right. Codegen selects it when
+`source-schema.json.platform === "csv"`.
+
+The reader is an **extractor**, not an in-memory loader: it parses with the shared parse core,
+applies the resolved layout to group rows into per-entity records, and writes **durable
+per-entity NDJSON record streams (`<entity>.ndjson`, one record per line) plus a
+`manifest.json`** into `data/source-extract/` that `rp-execute-import` reads.
+
+Emit records **as they are grouped**, streaming through `ndjson.js`'s writer — do not
+accumulate an entity's records in an array and serialise at the end. A 100k-row export must
+never require the whole entity in memory, and an interrupted extract should leave a valid
+readable prefix. See `rp-import-codegen` -> "Record streams are NDJSON".
+
+- **Emit canonical records, or convert with `lib/canonical-record.js` — never hand-write the
+  rename.** `rp-target-wix/lib/wix-build.js` consumes the vendor-neutral vocabulary declared in
+  `wix-target-spec.js` (`description`, `brand`, `weight`), while a reader naturally names fields the
+  way its vendor thinks (`bodyHtml`, `vendor`, `weightKg`). `lib/canonical-record.js` holds that
+  rename as **per-vendor data** (`READER_FIELD_MAPS`) and self-validates at require time, so a typo
+  is a load error instead of a field that silently never reaches Wix. Vendor it alongside
+  `csv-parse.js` and call it; do not re-derive the mapping in a project-local transform. It is
+  regression-locked with the builder against 220 payloads from two live-verified imports
+  (`tests/mapping/wix-build-oracle-test.js`).
+- **Reuse `lib/csv-parse.js` — do not regenerate it.** Vendor a copy into the project (e.g.
+  `src/lib/`) and import from it, exactly as the WordPress reader vendors `wp-http.js`. The
+  reader then carries only per-project orchestration: which entities to emit, the grouping loop,
+  type coercion, and transform glue. One tested parse core is what makes the sampler and the
+  reader agree.
+- **Grouping is the reader's core job.** Replay the resolved layout: a blank key extends the
+  current group; a discriminator column routes parent vs child rows, resolving
+  `parentRefColumn` (Woo's `Parent` carries `id:123` or a SKU, and does **not** guarantee that a
+  variation follows its parent).
+- **Iterate the file set** by role, treating `partOf` entries as continuations of the same
+  logical stream and honoring each part's own column order.
+- **Materialize derived entities**: collect the distinct values of a `column-values` column (and
+  their ancestors when hierarchical) into their own entity file, depth-ascending, and emit the
+  linking relation. Do not invent Wix ids at extract time — the import stage resolves them
+  through the `ImportCrosswalk`.
+- **Coerce per inferred type**, and apply `coerceEmpty` with the recorded `emptyPolicy` so
+  required Wix fields are not fed empty strings.
+- CSV values are plain text and are written as-is — no entity-decoding step unless a specific
+  vendor is known to double-encode.
+- No auth, no pagination, no rate limits: the entire WordPress transport section collapses to
+  "open the file once".
+
+## Media
+
+Image columns hold either public URLs (Wix-reachable) or local paths / private URLs (not
+reachable — Wix Media import fetches from Wix servers, the same concern as a WordPress
+`localhost` source). Capture flags these as `media-reachability` warnings. Record the note in
+`source-profile.md` and offer the two choices:
+
+- rewrite via `CSV_MEDIA_URL_REWRITE_FROM` / `CSV_MEDIA_URL_REWRITE_TO`, or expose the files at
+  a public HTTPS URL, or
+- skip/defer media import and continue with non-media entities.
+
+## Schema shape
+
+`source-schema.example.json` (in this skill folder) is the template `rp-discovery` follows when
+emitting `migrations/<project>/source-schema.json`. It is a shape to follow, not a strict schema
+to validate against. Keep the platform-agnostic core stable; push CSV specifics
+(`sourceFiles`, `vendor`, `dialect`, `drift`, `mappingHints`, `joins`) into `sourceMeta`, and
+give every entity an `origin`.
+
+## Contract tests
+
+Contract tests live in the repo's `tests/` tree, not in this bundle — a fixture shipped to a
+partner is dead weight. Run them from the repo root:
+
+```
+bash tests/run-all.sh source-csv
+```
+
+Or individually: `node tests/source-csv/csv-parse-contract-test.js` (also
+`csv-fingerprint-`, `csv-layout-`, `csv-fileset-`). Fixtures are in `tests/fixtures/csv/`.
+
+They cover the dialect/quoting/BOM/line-ending/empty-policy matrix and chunk-boundary feeding;
+per-vendor header fixtures, the `custom` fallback, near misses and drifted headers; the layout
+patterns plus their false-positive guards, the ambiguity halt and the verification of a pinned
+continuation mode in both directions; derived-entity split order,
+ancestors and the URL guard; and role assignment, split-file concatenation, header-superset
+halts and part ordering.
+
+When a vendor's format drifts, fix `vendors/<vendor>.json` and add a header fixture to
+`tests/fixtures/csv/headers/` — no skill logic changes.