@wix/agent-skills 1.33.1 → 1.34.0

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

@@ -25,12 +25,27 @@ This is not a stage in the migration flow — it is a reference consulted by two
 WordPress-specific knowledge is already baked into the generated reader code. Keeping the
 WordPress knowledge here is what lets the rest of the workflow stay platform-agnostic.
 
+For app routing and internal-link reconciliation, the generated reader also enumerates the captured source roots, declared
+source hosts, source permalink/alias evidence, and each record's containing source page.
+It passes those facts to the shared `internal-link-audit.js plan` input after backend
+import. Do not infer the containing page from a file basename or assume a default
+WooCommerce path. The deterministic census records every captured file as scanned,
+unreadable or unsupported; unsupported documents, dynamic URLs and missing captures
+remain coverage items. Never scan `config/*.env` or execute captured source code.
+
 ## Platform identity
 
 - Source platform: WordPress (core REST `wp/v2`), optionally WooCommerce (`wc/v3`).
 - Detect by hitting `<base-url>/wp-json/` — the REST index lists advertised namespaces.
 - Set `"platform": "wordpress"` (and note WooCommerce presence in `sourceMeta`) in the
-  emitted `source-schema.json`.
+  emitted `source-schema.json`. This describes the discovery artifact, not the orchestration
+  decision.
+- Once discovery confirms WooCommerce, record `sourcePlatform.value=woocommerce` in
+  `orchestration/decisions.json` and use `config/source.woocommerce.env`. Otherwise record
+  `sourcePlatform.value=wordpress` there and use `config/source.wordpress.env`. Generated
+  importers read that exact nested value — never the decision wrapper object and never the
+  nullable `orchestration/run.json` `sourcePlatform` field. The adapter remains
+  `rp-source-wordpress` in both cases.
 
 ## Capture (discovery-time)
 
@@ -43,13 +58,16 @@ turn that hint into a target decision here. Keep frontend, theme, runtime, admin
 transient routes skipped by default even if a knowledge entry exists for a related
 setup/config target.
 
-Before capture, verify `migrations/<project>/config/source.wordpress.env`. Create it if
-missing, using empty values for the user to fill:
+After identifying the platform, verify `migrations/<project>/config/source.<platform>.env`.
+For a confirmed WooCommerce source, this is `source.woocommerce.env`; for WordPress without
+WooCommerce evidence, it is `source.wordpress.env`. Create the selected file if missing with
+empty values:
 
 ```bash
 WP_BASE_URL=
 WP_USERNAME=
 WP_APPLICATION_PASSWORD=
+WMH2_MIGRATION_KEY=
 WP_MEDIA_URL_REWRITE_FROM=
 WP_MEDIA_URL_REWRITE_TO=
 WC_CONSUMER_KEY=
@@ -64,13 +82,52 @@ the user which data scope they want:
 
 This choice is mandatory and must be explicit. Do not ask for `WP_USERNAME`,
 `WP_APPLICATION_PASSWORD`, or WooCommerce keys until the user chooses `also include
-private/authenticated data`.
+private/authenticated data`. Request `WMH2_MIGRATION_KEY` only when bridge-backed entities
+are actually in scope and the detected source has no WooCommerce. Collect every sensitive
+value through the secure Secrets Manager flow; do not ask the user to paste it into chat.
+
+There are two independent scopes, and a complete run may need both credentials:
+
+- **Private WordPress/WooCommerce REST** (`wp/v2`, `wc/v3`) requires a WordPress
+  Application Password (`WP_USERNAME` + `WP_APPLICATION_PASSWORD`).
+- **`wix-wp-plugin-v2` bridge reads** use the Application Password path only when
+  WooCommerce is present, because that route requires `manage_woocommerce`. When the
+  source has no WooCommerce, collect `WMH2_MIGRATION_KEY` for bridge reads instead. The
+  key is generated and shown once on the plugin's wp-admin page at activation or rotation.
+  It never authenticates ordinary `wp/v2` or `wc/v3` reads.
+
+Key sensitivity is predefined and does not change at runtime. Requiredness is separate
+and may depend on the selected acquisition mode or source behavior.
+
+| Key | Sensitivity | Requiredness |
+|---|---|---|
+| `WP_BASE_URL` | non-sensitive | Required for URL-based capture |
+| `WP_USERNAME` | sensitive | Required for private/authenticated WordPress capture via Application Password |
+| `WP_APPLICATION_PASSWORD` | sensitive | Required for private/authenticated WordPress capture via Application Password |
+| `WMH2_MIGRATION_KEY` | sensitive | Required for `wix-wp-plugin-v2` bridge reads when the source has no WooCommerce; optional otherwise |
+| `WP_MEDIA_URL_REWRITE_FROM` | non-sensitive | Optional |
+| `WP_MEDIA_URL_REWRITE_TO` | non-sensitive | Optional |
+| `WC_CONSUMER_KEY` | sensitive | Optional unless WooCommerce rejects the WordPress Application Password for `wc/v3` reads |
+| `WC_CONSUMER_SECRET` | sensitive | Optional unless WooCommerce rejects the WordPress Application Password for `wc/v3` reads |
 
 Required for a complete WordPress/WooCommerce capture:
 
 - `WP_BASE_URL`
-- `WP_USERNAME`
-- `WP_APPLICATION_PASSWORD`
+- `WP_USERNAME` + `WP_APPLICATION_PASSWORD` when private REST-visible data is in scope
+- `WMH2_MIGRATION_KEY` additionally when bridge-backed entities are in scope and the
+  source has no WooCommerce
+
+⚠️ **`WMH2_MIGRATION_KEY` only unblocks the plugin's own `/structure` and `/query` routes**
+(`wix-wp-plugin-v2`'s `structure-bridge-plugin` entities — custom plugin tables with no REST
+route) — `wp-discovery.js`/`wix-wp-plugin-v2-client.js` sign requests with it
+automatically when the signed bridge path is selected. It does **not** authenticate
+standard WordPress/WooCommerce REST (`wp/v2`, `wc/v3`) at all — reading posts, pages,
+products, orders, customers, and every other REST-visible entity still requires the
+Application Password. On a source site with no WooCommerce, the Application Password routes
+are `manage_woocommerce`-gated and unusable by any user regardless, so the migration key is
+the only credential that reaches the bridge. If no separate WordPress REST credential is
+available, ordinary private content still cannot be captured through this adapter and needs
+another source API or export.
 
 `WC_CONSUMER_KEY` and `WC_CONSUMER_SECRET` are optional when WooCommerce accepts the
 WordPress Application Password for `wc/v3` reads; ask for them only if WooCommerce routes
@@ -81,7 +138,7 @@ WordPress API is reached through a public tunnel but media/file URLs inside reco
 point at `localhost` or another private origin. If they are blank, generated readers may
 rewrite localhost/private origins to `WP_BASE_URL` when `WP_BASE_URL` is public.
 
-`config/source.wordpress.env` is a secret-bearing file once it may contain real values.
+`config/source.<platform>.env` is a secret-bearing file once it may contain real values.
 Do not read it with whole-file commands that print its contents into tool output. Check
 only whether the file exists and whether each required key is present/blank/missing; when
 describing status, name keys only and never echo values.
@@ -90,12 +147,14 @@ describing status, name keys only and never echo values.
    containing this `SKILL.md`; see `CONVENTIONS.md`):
 
    ```
-   node scripts/wp-discovery.js --base-url <url> --out-dir <migrations-root>/<project>/data/wp-discovery
+   node scripts/wp-discovery.js --env-file <migrations-root>/<project>/config/source.<platform>.env --out-dir <migrations-root>/<project>/data/wp-discovery
    ```
 
    It walks the REST index, runs one `OPTIONS` + a small `GET` sample per entity, and
    writes per-entity markdown (routes, schemas, sample records, record counts,
-   relationships). Pass auth options (see Read contract → Auth) for a complete capture.
+   relationships). `--env-file` is the preferred launch path for project-local
+   credential-bearing config because it avoids shell sourcing of secret-bearing files.
+   Pass direct auth options only when there is no project-local config yet.
    For long runs, pass `--progress-log <path>` and poll it per
    `CONVENTIONS.md#progress-log-polling`.
 
@@ -120,7 +179,7 @@ describing status, name keys only and never echo values.
    authenticated → per-author mapping: administrators → owner user-member,
    content roles → per-author members; subscribers/customers → **Wix contacts by
    default** — a contact is the no-login CRM person entity and Contacts V5 upserts in
-   bulk — promote to full site members (MEM-01: 1/sec serial, re-registration) only when
+   bulk — promote to full site members (1/sec serial, re-registration) only when
    member-gated features are in scope. Every Wix member auto-creates its contact, so
    member-first ordering: never pre-create a contact for someone who will become a
    member. Note contacts cannot author blog posts or comments — bylines need members).
@@ -135,6 +194,12 @@ describing status, name keys only and never echo values.
    setup, and integration/helper APIs. It writes the skipped-route audit trail to
    `skipped-routes.json`.
 
+   It also always writes `source-coverage.json` (`rows: []` when clean): one row per entity
+   whose data request returned 401/403 (`auth-gated`) or failed with no records (an
+   OPTIONS-probe failure alone is not one), per backend data route skipped by rule, per
+   credential-bearing route never read (`not-recoverable`), and per unsupported route
+   namespace. Frontend, theme, admin and transient skips get no row. `rp-discovery` promotes it; never edit it by hand.
+
    For WooCommerce, prefer canonical durable data APIs such as `wc/v3` over duplicated
    `wc/v2`/`wc/v1` routes for authenticated/private commerce reads. For `public content only`
    discovery, probe public Store API catalog routes before declaring commerce deferred:
@@ -142,8 +207,51 @@ describing status, name keys only and never echo values.
    commerce data when present. Cart and checkout Store API routes remain out of scope as
    runtime session state.
 
-6. Map known plugins to entity types where relevant (e.g. WooCommerce → store,
-   Seriously Simple Podcasting `ssp/v1` → podcasts, Yoast → SEO, ACF → custom fields).
+   **Images: never read a field, always resolve.** An image reference in a WordPress-family
+   payload is a *set* of candidate URLs for one picture — the merchant's original upload plus
+   the crops WordPress generated from it. Which field holds the original varies by route, and
+   the two WooCommerce APIs disagree on the **same site**: on `wc/store/v1` `images[].src` is
+   the original, while on `wc/v3` it is resolved through WordPress's registered image sizes
+   and can be the *smallest* crop, because any theme or image-optimizer plugin may redefine
+   those sizes. Pass the whole reference to `resolveImageUrl` / `resolveImageUrls` in
+   `lib/wp-image-url.js` and use what it returns. It handles `src`, `thumbnail`,
+   `source_url`, `srcset`, `thumbnail_srcset`, and `media_details.sizes.*`, prefers the
+   original, falls back to the widest crop, percent-encodes the result, and retains the
+   attachment id as `sourceId` for the media-record check below.
+
+   **Product pictures require source-record confirmation in generated imports.** For the
+   exact orchestration identities `woocommerce` and `wordpress`, resolving the product
+   reference is only the first step. Vendor/use the shared root `lib/confirmed-pictures.js`:
+   collect the selected products' distinct positive `sourceId` values, call
+   `readSourceMediaRecords({ ids, source: { baseUrl, request: authenticatedWpRequest } })`,
+   where that wrapper delegates to `fetchJson` with the run's existing auth headers, then pass each
+   whole resolved gallery to `confirmPictures`. The read requests authenticated
+   `GET /wp/v2/media?include=<ids>&per_page=100` chunks in sorted groups of at most 100; each
+   chunk has one total 60-second transport deadline. The media record's `source_url` is the
+   evidence. Never infer an original from the filename and never construct a lookalike read or
+   confirmed list: provenance is private to the shared module.
+
+   A picture with no positive attachment id, no returned media record, or a media record in an
+   unreadable chunk is unconfirmed (`no-source-id`, `no-source-record`, or
+   `source-unreadable`). One unconfirmed picture defers the entire product gallery; continue
+   with non-media product fields and follow `rp-import-codegen`'s ledger/recovery contract.
+   Quick mode is unchanged and does not use this boundary.
+
+   ⚠️ This is not optional on the public path just because `src` happens to be right there
+   today. Same call, everywhere — a contract test pins the Store API no-op, so a change in
+   that behaviour surfaces as a test failure rather than as a merchant's blurry storefront.
+
+   ⚠️ The destination gives one attempt. Wix copies the single URL you send and generates
+   every derivative from it, with no way to raise quality afterwards, so a crop shipped here
+   is that product's permanent ceiling. When `resolvedIsCrop()` is true the source genuinely
+   had nothing better — report those images in the run's own record rather than shipping them
+   silently.
+
+6. **Plugin coverage runs automatically.** Plugin handling is a deterministic pre-pass plus
+   declarative profiles, not prose guesswork — see "Plugin coverage" below. The capture
+   script writes `plugin-inventory.json` and `plugin-coverage.json` alongside the per-entity
+   files. Never hand-map a plugin from memory; consult the profiles through
+   `scripts/plugin-knowledge.js`.
 
 7. **Localhost sources and media URLs.** A source at `localhost`, `127.0.0.1`, or another
    private-only host is valid for discovery and source reads from the user's machine.
@@ -168,6 +276,477 @@ The raw capture is evidence, not a hand-off artifact. `rp-discovery` synthesizes
 the canonical artifacts and records traceability pointers (`rawDiscovery`, per-entity
 `rawFile`).
 
+## Payment gateways: read the summary, never the route
+
+`GET /wc/v3/payment_gateways` and `/wc/v3/payment_gateways/{id}` return each gateway's **entire
+settings object**. On a site with a real gateway connected that includes the live API key and
+secret. Anything a tool returns is in the model's context, the transcript and potentially a
+durable run artifact, so there is no careful-handling mitigation available after the fact — the
+value must never be requested.
+
+**`fetchGatewaySummary()` in `lib/wp-http.js` is the only way to read gateway configuration.**
+It returns, per gateway, `id` / `title` / `enabled` / `order` and `fields: [{ name, state }]`,
+where `state` is `present`, `blank` or `absent` — plus a `value` for the short allowlist of
+display and behaviour fields, each of which passes the shared secret-value guard first. That is
+everything discovery legitimately needs: which gateways are registered, which are enabled, and
+whether a credential is configured. Request-level outcomes (`ok`, `unauthorized`, `unreachable`,
+`malformed`) are a separate axis, and a failed request returns **zero** field entries rather
+than a page of `absent`, so "this gateway has no API key" can never be confused with "we could
+not ask".
+
+Everything else about the route is closed, on purpose:
+
+- `fetchJson()` **refuses** either gateway route before issuing the request, below discovery's
+  `--include-route` override. There is no flag, option, capability token or environment variable
+  that lifts it; adding one is the exposure with extra steps.
+- The route classifier categorizes both shapes as `excluded_credential_bearing`, and neither
+  `--include-route` nor `--include-excluded-category` can promote them to `sample`.
+- A plugin profile may not declare a gateway route as a readable entity route, under any flag.
+- Never write a gateway field value into `source-profile.md`, `source-schema.json`, a sample
+  record, a progress log, a completion report, a CMS field, telemetry, or `.local.env`. Never a
+  prefix, a length or a hash of one either — each of those is a usable clue on its own.
+
+Report what was read. A run that states "N gateways, M enabled, K credential fields present, 0
+values retained" is auditable; one that silently read the settings blob is not.
+`describeGatewaySummary()` produces that line for the approval gate.
+
+⚠️ The value guard is a pattern list, not a guarantee — a credential in an unrecognized format
+passes it. It is the backstop for credentials nobody can name in advance; the controls above are
+the actual protection.
+
+## Reading payment, refund and invoice history
+
+Three deterministic registries carry this knowledge. Use them; do not re-derive which source keys
+mean what, and do not hand-author the reads.
+
+| What you need | Use |
+| --- | --- |
+| Which source keys the payments import may read at all | `paymentReadKeys()` in `lib/gateway-source-keys.js` |
+| Which value may become a payment's provider transaction reference | `resolveTransactionReference()` in the same module |
+| Whether a method is online or offline | `resolveOfflinePayment()` — omits the flag when unknown |
+| Whether a refund actually happened | `qualifyRefund()` in `lib/refund-corroboration.js` |
+| Whether the store has invoices, and where their bytes live | `lib/invoice-discovery.js` |
+
+**The read manifest is closed.** `paymentReadKeys()` returns the complete set of keys this import
+touches — the amount, both paid-date fields, the method, the currency, the canonical reference,
+and each registry family's candidate fields. Nothing else is read. In particular a raw provider
+response blob is declared **unreadable**, not "to be pattern-matched later": on a live store its
+sibling fields carried customer name, phone and email, and a contract that requires parsing
+unstructured personal data is not one that can be honoured safely.
+`assertNoNeverReadKeys()` refuses a read plan naming it *before* the plan executes — filtering
+after the response arrives is too late, the blob is already in the run's working data.
+
+**Two surfaces, and neither alone covers payments.** Row-shaped tables come through the plugin
+`/query` surface; meta-backed fields come through WooCommerce REST. Run the generated
+`…--<table>.eav-read-plan.json` verbatim and reconcile it afterwards — a hand-authored scoped read
+cannot be reconciled against anything, and a plan edited after discovery wrote it is caught by its
+own hash.
+
+**A gateway-shaped key is not attribution.** The payment-method slug names the checkout plugin,
+not necessarily the processor: orders whose method is one gateway can carry
+another gateway's reference key, while every order whose method *was* that second gateway carried
+none. So a candidate is written only when its semantics are verified AND the registry recognizes
+the order's method — directly, or through a separately verified layered integration. Everything
+else is reported with a reason and never guessed at by precedence. Report candidate coverage and
+defensible coverage as separate numbers; collapsing them overstates fidelity.
+
+**A refund needs a refund record.** A canonical WooCommerce refund entity with a stable id and a
+positive amount is authoritative on its own. An order-level refunded status corroborates but
+cannot supply a missing amount. Gateway flags, statuses and refundable-balance fields never create
+a refund, however many agree — fields written by one callback are one signal. When only such flags and
+statuses exist, this yields zero importable refunds, which is the correct output.
+
+**Invoices are resolved per run.** Discovery matches key *families*, not authored names, and
+patterns found in a sample are then applied across the full order population. A discovered
+document URL is untrusted input that something is about to fetch: classify it before touching it,
+and never log or store it — the query string can be a bearer token and the filename can carry the
+customer's name. Nothing found means nothing is created, and the report says "no invoices found",
+never "not supported".
+
+Redaction counts are findings, not plumbing: a non-zero `redactedValueCount` means a credential
+was sitting somewhere unexpected in the source, and it belongs in the run report. Telemetry
+carries counts only — never a discovered key name and never a value.
+
+## Plugin coverage
+
+A real WooCommerce site is mostly plugins. Handling them is deterministic and has its own
+knowledge base: `plugins/` (profiles + `no-migration-needed.json` + `README.md`), read through
+`scripts/plugin-knowledge.js`, detected by `scripts/wp-plugin-inventory.js`.
+
+**Every installed plugin lands in exactly one of the four statuses, and every status
+produces a row the user sees. Nothing is silently ignored.**
+
+| Population | Evidence | Result |
+| --- | --- | --- |
+| recognized | a profile matched | named entities, declared read channels, Wix target refs; mapping `confirmed` |
+| derived | no profile, data is REST-visible | derived from `wp/v2/types` + `wp/v2/taxonomies`, mapping `proposed` (CMS, or native on a domain-KB match) |
+| named only | detected, no read channel | *Pending* with its reason, resolved by the no-migration-needed list or at the review gate |
+
+A plugin therefore does not need a profile to migrate — it needs one to migrate *natively*.
+
+### Detection
+
+Runs before route classification so profile-declared routes are already in scope. Signals,
+strongest first:
+
+1. `GET /wp/v2/plugins` — the authoritative installed list (`plugin`, `status`, `name`,
+   `version`). **Administrator credential required.** On 401/403 the run continues and
+   records `pluginListAvailable: false`; say so plainly rather than implying full coverage.
+   Without it, installed-but-unprofiled plugins cannot be enumerated at all — this is the
+   concrete argument for the authenticated acquisition mode.
+2. Declared routes present in the REST index.
+3. `GET /wp/v2/types` / `GET /wp/v2/taxonomies` entries matching a profile's `restBases`.
+4. **Record payload keys from the samples** — a second pass after sampling. This is not
+   optional polish: several major WooCommerce extensions (Product Bundles, Composite
+   Products, Product Add-Ons, ACF, Yoast) add **no REST route at all** and only widen
+   `wc/v3/products` / `wc/v3/orders` payloads. Route-based discovery cannot see them.
+5. REST namespaces and public `/wp-content/plugins/<slug>/` asset paths (low confidence,
+   but they work with no credentials).
+
+A plugin version below a profile's `detect.minVersion` is reported as
+`api-below-min-version`, not read as if the documented API were present.
+
+### Project-local plugin entity plans
+
+For an unfamiliar plugin, prefer a complete supported REST reader. If it is unavailable,
+investigate verified storage and use [PLUGIN-READ-PLANS.md](PLUGIN-READ-PLANS.md)'s shared
+validator/writer, including stable entity references, scoped related records and a bounded
+sample. A permanent profile or new transport handler is not required. Preserve the plan
+binding in canonical source metadata; only reconciled full extraction certifies readiness.
+Never return an ineffective “rerun discovery” task when a producer cannot emit its input.
+
+## Read channels
+
+`plugin-rest`, `core-cpt`, `core-embedded`, `core-meta`, `plugin-rest-child`, `export-file`,
+`db-only` — see `plugins/README.md`. Two consequences worth stating to the user:
+
+- **Unregistered post meta is invisible to the REST API.** WordPress exposes meta only when
+  the plugin registered it with `show_in_rest` (and, for a CPT, declared `custom-fields`
+  support). A plugin can keep its entire per-record state in `postmeta` and expose none of
+  it. Three ways to reach it, in preference order: the **structure bridge** (see "Reading
+  key/value tables through the bridge" below — this is the one that needs no profile and no
+  user action), a WXR export the user produces, or a database dump.
+- **WXR cannot be fetched.** Application Passwords authenticate the REST API and XML-RPC
+  only, never `wp-admin`, so an export file is something the **user produces and supplies**.
+  Treat `export-file` as a request to the user, never as a download.
+### Source redirect maps
+
+Old addresses kept alive only by redirect rules must be inventoried; an empty REST answer or
+the route classifier's `/redirection/*` exclusion is never evidence that no rules exist.
+`lib/wp-redirect-sources.js` normalizes them from the plugins' own storage:
+
+- **Redirection** — `redirection_items` + `redirection_groups` tables; **Rank Math** —
+  `rank_math_redirections` (PHP-serialized `sources`, one rule per pattern). Read them through
+  the structure bridge by **bare** table name; `resolveTable` matches the site's real prefix
+  from the bridge's table listing and reports several matches (multisite) as ambiguous.
+- **Yoast Premium** keeps redirects in `options`, which stays denied: coverage is
+  `unsupported` until the operator supplies the plugin's CSV export.
+- Server/CDN rules (`.htaccess`, nginx, edge) live outside WordPress: record them as
+  `unsupported` and ask the host for an export.
+- Logs, 404 records and hit counts are not rules. Disabled rules and rules of an inactive
+  plugin are kept as `enabled: false` exclusions, never reactivated.
+- A failed, partial or channel-less read is `unreadable`, never `confirmed_empty`.
+
+Feed the reads to `node skills/wix-replatform/scripts/url-redirects.js sources --project
+<dir> --input <file.json>`; it appends `state/url-preservation/source-redirects.ndjson` and
+writes `source-redirect-coverage.json`. When declared source domains are present, it also
+plans the captured destinations into the redirect audit and URL rewrite report. If domains
+are declared later, run `url-redirects.js import-targets --project <dir>` after that
+declaration. Capability evidence for a specific rule can be supplied in the source input's
+`targetCapabilities[ruleKey]` with `productSupported`, optional `automationSupported`, and
+an evidence reference; absent evidence remains unverified where product support is not
+established for that rule shape. A complete capture records a disabled tombstone for a
+previously captured rule that disappeared, so the cutover report keeps its old address
+open for explicit redirect reconciliation. Partial or unreadable captures never retire
+missing rules.
+
+### Reading key/value tables through the bridge
+
+When `wix-wp-plugin-v2` is installed on the source site, `postmeta` and every other
+key/value-shaped table is readable — key-scoped. This is the channel to reach for when a
+capability would otherwise be a `user-file` blocker, and it is the ONLY one that works for a
+plugin nobody has profiled.
+
+**Always run key discovery, even for a profiled plugin.** It is tempting to treat a profile's
+`detect.recordProperties` as the key list and skip the round-trip — `subscriptions-for-woocommerce.json`
+names `_wps_sfw_product` there — but those are *detection markers*, one or two keys that prove
+the plugin wrote the record. They are not the record's field list. Reading only them produces a
+short extraction that looks complete, the same failure as a truncated key list.
+
+Profiles earn their place elsewhere: they say which table to read, which entity it maps to, and
+what the pitfalls are. The key list comes from the site. A single order on a gateway-backed store
+can carry dozens of gateway-specific meta keys under a prefix no profile anywhere has seen, which
+is why discovery is the mechanism and not the fallback.
+
+**The rule: if you have not named the keys you want, the value column does not exist.** Not
+in `select`, not in `where`, not in `orderBy`, not in `groupBy`. Violating it returns
+`wmh2_invalid_structure_request` (400) — the same error as naming a nonexistent column, so
+the refusal will not tell you which column is the value column. Two steps:
+
+1. **`GET /structure?table=postmeta`** → the column list plus `eavPair: {keyColumn,
+   valueColumn}`. This tells you the table is key-scoped *before* you write a query. No rows,
+   no key names.
+2. **Discovery** — `select` the key column plus a count, `groupBy` the key column. Returns the
+   real key list with row counts, `eavAccess.tier: "key-discovery"`.
+3. **Scoped read** — `where` the key column `in` the keys you want (**max 50 per request**),
+   then `select` the value column freely. `eavAccess.tier: "key-scoped"`.
+
+```jsonc
+// 2. discovery                                  // 3. scoped read
+{"structureRequest": {                           {"structureRequest": {
+  "table": "postmeta",                             "table": "postmeta",
+  "select": [{"column": "meta_key"},               "select": [{"column": "post_id"},
+             {"column": "meta_key",                            {"column": "meta_key"},
+              "aggregate": "count", "as": "n"}],              {"column": "meta_value"}],
+  "groupBy": ["meta_key"],                         "where": [{"column": "meta_key", "op": "in",
+  "orderBy": [{"column": "meta_key",                          "value": ["<key from step 2>",
+               "direction": "asc"}]                                     "<key from step 2>"]}],
+}}                                               "orderBy": [{"column": "post_id", "direction": "asc"}]
+                                                 }}
+```
+
+⚠️ **Count the KEY column, not some other column.** `{"column": "<keyColumn>", "aggregate":
+"count"}` works on any key/value table; counting `meta_id` only works where that column happens
+to exist, and a `name`/`value` table has no `meta_id` at all. The generic client counts the
+discovered key column for exactly this reason.
+
+Things that will bite:
+
+- **Page discovery to exhaustion.** `limit` maxes at 200 and a large `postmeta` has more
+  distinct keys than one page. Follow `pagingMetadata.cursors.next` until it is null before
+  concluding a key is absent — a truncated key list reads as "these are all the keys" and
+  will send the mapping down a wrong path. Budget `ceil(N/200)` discovery pages plus at least
+  `ceil(N/50)` scoped **batches** — and a batch is not a request: each pages at 200 rows, so a
+  batch whose 50 keys hold 4,000 rows costs 20 requests. Because discovery returns each key's
+  row count, the read plan states the real figure (`expectedPages` per batch,
+  `expectedScopedRequests` overall) — read it there rather than estimating.
+- **`options` and `usermeta` are still refused outright**, and pinning `option_name` does not
+  unlock `options`. Gateway configuration held in `options` is a different mechanism
+  entirely — do not try to route around this.
+- **Check `redactionMetadata.redactedValueCount` on every response.** Non-zero means a value
+  matched a credential shape and came back as `[REDACTED:secret-shaped]`. That is not a bug
+  to work around: it means the source site keeps a credential somewhere unexpected, and it
+  belongs in the run's notes.
+- **A table named `*meta` whose pair is not one of the six recognized ones is refused (403),
+  not readable.** There is no key column to pin, so there is nothing to scope. Reach for a WXR
+  export or a database dump for that table, and say so rather than reporting it as empty.
+- **A table can carry MORE than one pair**, and each is guarded separately: pinning `meta_key`
+  does not make a second pair's `value` column readable. `eavPair.additionalPairs` and
+  `eavAccess.additionalPairs` list them; `guardedValueColumns()` in the client returns all of
+  them at once, which is what you want when building a select list.
+- **Every value comes back as a STRING — including flags, ids and counts.** A column the
+  plugin stores as an integer flag arrives as `"0"` or `"1"`, and `Boolean("0")` is **true**
+  in JavaScript, so the natural-looking `if (row.is_spam)` classifies *every* row as spam.
+  A form-submission import that reads a plugin's `is_spam` column straight into a truthiness
+  test mismarks the entire set, and nothing errors: the run simply reports every row as spam. Compare
+  explicitly (`row.is_spam === '1'`, or `Number(row.is_spam) === 1`) on every flag, id and
+  numeric column you branch on, and never feed a bridge value to a bare truthiness test. The
+  same holds for text-valued status columns: `"active"` is a string the plugin chose, not a
+  normalized enum — and note that a source's own spam/status flags being uniformly clean is
+  not evidence the data is clean, only that the source never flagged it.
+- **A submissions table shared by every form needs the source form id on BOTH sides.** Form
+  plugins that keep one entries table (Forminator's is the shape seen live; it has no profile
+  in `plugins/` yet) key each row by the source form id, while the target form ids are minted
+  per form by the forms import. That is two lookups, not one: filter the source rows to the
+  form being imported, **and** resolve that same form's crosswalked target id. Getting either
+  side wrong writes real submissions onto the wrong target form and the create still succeeds
+  — there is no error to notice. Assert the source-form-id →
+  target-form-id pairing from the crosswalk before the first write, and read one created
+  submission back on the form you expected it to land on.
+
+#### Yoast product SEO evidence
+
+WooCommerce product `yoast_head_json` is **rendered** output, never proof of an override (a store
+can render a title on every product while holding no raw title override). Decide each product's SEO title,
+description and focus keyphrase per field with `lib/yoast-product-seo-evidence.js`:
+
+1. **REST `meta`** on the product post (`/wp/v2/product/{id}?context=edit`): a key counts only
+   when `meta` contains it (`restEvidence`). Missing key means unresolved, not "no override".
+2. **Bridge key-scoped `postmeta` read** for keys still unresolved (`readBridgeEvidence`, with
+   `queryPage` bound to `queryStructure`). It pins exactly `_yoast_wpseo_title`,
+   `_yoast_wpseo_metadesc`, `_yoast_wpseo_focuskw` plus a batch of product ids, and pages to
+   `hasNext: false`. This is the one deliberate exception to "always run key discovery": the key
+   set is a fixed allow-list, never widened, and a complete scoped read with **no row** is itself
+   the evidence (inherit). A failed, truncated or non-key-scoped batch makes only that batch's
+   unresolved fields `unknown`.
+3. Otherwise `unknown`. A user-supplied export can later provide evidence through the
+   blocked-data request flow.
+
+`buildProductSeoReceipts` returns the audit receipt per product (stored with the extraction,
+never hashed whole); `seoEvidenceFromReceipt` gives the canonical `product.seoEvidence`. Never map
+`yoast_head_json.title/description`, `og_*` or the excerpt into `seoTitle`/`seoDescription`.
+Non-Yoast SEO plugins have no evidence contract: their product SEO is `unknown`.
+
+- **Parent-scoped sub-resources (`plugin-rest-child`, fixed 2026-08-11).** WooCommerce order
+  *notes* (`/wc/v3/orders/{id}/notes`) and similar per-parent sub-collections cannot be listed
+  on their own — the base classifier only samples flat collection routes (`page`/`per_page`
+  shape). This is why a plugin that writes real data via `$order->add_order_note(...)` (e.g.
+  Custom Payment Gateway for WooCommerce's payment-note field) used to report as
+  `pending · cannot-tell` even though the data is real and REST-reachable in principle.
+  `plugin-rest-child` fixes this: an entity declares `route` as a `{parentId}`-templated path
+  (`/wc/v3/orders/{parentId}/notes`) plus `parentRoute` (the already-sampled collection that
+  supplies real parent ids, e.g. `/wc/v3/orders`). Availability is a two-part **presence**
+  check against the site's REST index — `parentRoute` is in scope, and the index advertises a
+  route shaped like the template (WordPress's `(?P<id>[\d]+)`-style regex segments are
+  normalized to `{parentId}` for the comparison, so the parameter's name never has to match).
+  Presence alone does not confirm real data exists there: `wp-discovery.js`'s
+  `sampleChildEntities` runs a **live, representative check** afterward — it substitutes up to
+  3 already-sampled parent ids into the template and fetches each, purely to say "N of 3
+  sampled parents actually returned something," not to claim a full count. That result surfaces
+  as a plain-language run note, never as a channel-status change: a small sample coming back
+  empty does not mean the capability is absent, only that this sample did not confirm it.
+  The infrastructure is
+  built and tested (`plugin-knowledge.js`, `wp-route-classifier.js`'s `childRouteAdvertised`,
+  `wp-plugin-detect.js`'s `describeProfiledEntity`, `wp-discovery.js`'s `sampleChildEntities`),
+  and `plugins/woocommerce-other-payment-gateway.json` is authored and live-verified
+  — do not guess a plugin's installed-directory id when authoring a similar
+  profile; confirm `detect.pluginFileIds` against a live `GET /wp/v2/plugins` response first, it
+  is exactly the kind of fact a stale or invented guess silently gets wrong.
+- **Non-standard response envelope (`responseEnvelope`, fixed 2026-08-11).** Sampling and
+  counting assume a flat array (`X-WP-Total`/`X-WP-TotalPages` headers, or the array's own
+  length) or a single object. MailPoet's REST API (`/mailpoet/v1/subscribers`,
+  `/segments`, `/newsletters`, ...) broke that assumption: it is a real, paginated, GET-only
+  REST route (VERIFIED LIVE 2026-08-11: readable with the
+  standard Application Password), but the payload is wrapped as
+  `{ data: { items: [...], meta: { count, pages } } }` with no `X-WP-Total` header — the count
+  lives inside the body instead. Before this fix the whole envelope would have sampled as one
+  opaque record. A profile entity (route-bearing channels only) now declares
+  `responseEnvelope: { itemsPath, countPath }` — a dot-path to the array of records, and an
+  optional dot-path to the true total when there's no header. `wp-discovery.js`'s
+  `inspectEntity` unwraps to that path and otherwise treats it exactly like a flat array; a
+  path that stops resolving (stale profile, plugin version drift) falls back to the raw payload
+  shape and records a discovery note rather than failing the run.
+  `plugins/mailpoet.json` is authored and live-verified: `crm.email-subscription`
+  now resolves to migration-planned via the existing `crm/email-subscription` target, with
+  `recordCount` read via the declared `countPath`. A namespace-wide `unprofiledRoutes`
+  entry is still a sign a route this shape (or any other) has never been profiled — check there
+  before concluding a plugin has "no REST surface."
+- **Route default query (`ROUTE_DEFAULT_QUERY_RULES`, fixed 2026-08-16).** Sampling sends
+  `per_page` and nothing else, so any collection route that applies a **default filter to an
+  unparameterized request** is read as its filtered subset and the plan under-counts — the
+  hidden records are invisible to the mapper, not merely misreported. Observed on
+  `/wc/v3/products/reviews`, which defaults to `status=approved`: a store holding both approved and on-hold
+  reviews had only the approved ones counted. This is a class of bug, so the fix is a
+  table rather than a special case: `wp-route-classifier.js` carries
+  `ROUTE_DEFAULT_QUERY_RULES` — `[pattern, params, reason]`, `*`-suffix matching, longest
+  pattern wins — and `defaultQueryFor(routePath)` / `defaultQueryReasonFor(routePath)` resolve
+  it. `wp-discovery.js` merges the result under its paging parameters and records a discovery
+  note naming the parameters and the reason, so generated readers know to send them too.
+  Adding a route is one row in the table plus a fixture; a route with no row is unchanged.
+
+### Coverage statuses
+
+The four statuses, and only the four: `migration-planned` (via `api` or `cms`,
+confidence `confirmed` or `proposed`), `no-need-to-migrate`, `pending`,
+`requires-development`. A failed or unavailable read is never a status — it attaches to the
+row as `blocked[]` (`user-file` / `surface-changed`, with a `declined` flag).
+
+The split is deliberate: `pending` (we do not know how to migrate this yet — our open item)
+and `requires-development` (a human established Wix has no surface) call for different
+conversations. Only the second is a closed door, and only a human may open it — the
+human-signed register `plugins/requires-development.json` is its single source.
+
+### Interaction rules
+
+- **The admin Application Password is the source REST credential; `wix-wp-plugin-v2`'s
+  migration key is scoped to that bridge.** A plugin REST namespace that honours
+  WordPress authentication works with the Application Password, and that is the normal
+  case — plugins with their own key systems offer them as an *alternative* for external
+  callers, not a requirement (verified for Gravity Forms, which accepts Application
+  Passwords and runs requests under the caller's plugin capabilities). Do **not** treat
+  "this plugin has API keys" as "we need another credential"; that reasoning has been
+  wrong every time it was applied. If a plugin genuinely rejects the platform credential,
+  that is a config-gate requirement like the WooCommerce consumer keys — not a
+  per-capability runtime state. For the structure bridge specifically, select the
+  Application Password path only when WooCommerce is present; otherwise use
+  `WMH2_MIGRATION_KEY`. Never describe that bridge-only key as private REST authentication.
+- `blocked[]` entries are collected and asked **once**, batched, each individually
+  skippable. A `user-file` blocker means no *WordPress API* can reach it: unregistered post
+  meta and plugin tables are invisible to REST, and Application Passwords cannot reach
+  `wp-admin`, so absent anything else a WXR or CSV export must be produced by the user.
+  **Check the structure bridge first** — if `wix-wp-plugin-v2` is installed on the source
+  site, both of those are readable through it (see "Reading key/value tables through the
+  bridge" below), and asking the user for an export they did not need to produce is a real
+  cost to avoid. Record each
+  answer in `orchestration/decisions.json` under `pluginBlocker:<capability>:<kind>`
+  (`provided` / `declined`); `wp-discovery.js` reads it back (`--decisions`, defaulting to
+  `<out-dir>/../../orchestration/decisions.json`) so a declined ask renders as declined.
+- `pluginCmsFallback:<capability>` sits beside it in the same file: the merchant's
+  approve/decline answer to archiving a recognized capability's records in CMS, bound to the
+  exact proposal shown. `wp-discovery.js` reads it with the eligibility register
+  (`plugins/cms-fallback-eligible.json`) and classifies the row (`pending` with a
+  `cms-fallback-*` reason, or `migration-planned · via cms · basis decision` with
+  `cmsFallback.functionalityRestored: false`). It is written only at the mapping review by
+  `orchestration-state.js decide-cms-fallback`. A malformed entry is never honored and never
+  fails the run; with no row to carry it, it appears in `plugin-coverage.json`
+  `cmsFallbackDecisionIssues[]`.
+- `plugin-coverage.json` also carries `entityStats` (per-route record counts and sample
+  evidence) and `inputs.cmsFallbackDigest`; `--reclassify-coverage` rebuilds coverage from
+  them without any source request (see `rp-discovery`).
+- `migration-planned · proposed` rows never block; the proposed capability and target are
+  reviewed at the normal mapping-review checkpoint.
+- `requires-development` and `pending` rows **must** reach the user. A detected but
+  undeliverable capability the user was never told about is the failure this machinery
+  exists to prevent. Every `pending` row is decided at the mapping review — the only exit.
+
+**A recognized plugin always ends in Migration planned** (J2 property 1). If a profile
+matched we know what the plugin holds, so:
+- no readable channel (plugin tables only) → still classified by its target, with a
+  `user-file` blocker on the row — **not** pending, and never a "cannot" verdict. A database
+  export or a source-side bridge would reach it, and automation may not foreclose that any
+  more than it may declare Wix incapable.
+- `pending · cannot-tell` is reserved for an **unrecognized** plugin where we genuinely
+  found nothing; the no-migration-needed list or the agent's own reading can
+  still resolve it to *No need to migrate* with a recorded rationale.
+- The one deliberate exception is a **CMS fallback**: when nothing native fits, a
+  recognized capability with a signed `cms-fallback-eligible.json` entry stays *Pending*
+  (`cms-fallback-*` reason) until this migration's merchant approves archiving its records in
+  CMS. A profile never names a `cms/*` target itself.
+
+**A CMS destination is not turnkey.** "Kept as data" means the records land in a Wix CMS
+collection with their original IDs — genuinely migrated, not documented. But Wix Data must be
+installed first (item writes fail with `WDE0110` otherwise) and collection creation has no
+verified writer yet, so it is a setup step. Say both on the row; a customer reading "Kept as
+data" should not discover the setup work later.
+
+### Guardrails
+
+- **Never a silent native mapping.** A derived entity may target a native Wix entity
+  only when the Wix domain knowledge confirms its proposed capability; otherwise it goes to
+  CMS. Either way the row is `confidence: proposed` and is confirmed at the mapping review.
+- **Never a scope reopening.** The generic path operates only on routes the route classifier
+  already accepted. It does not resurrect frontend, editor, admin, runtime, or integration
+  families because a plugin registered them.
+- Profile data routes outrank exclusion families (that is the per-capability opt-in), but a
+  wildcard pattern must keep two concrete leading segments, so `/yoast/*` can never be
+  opted in wholesale.
+
+### Commands
+
+```bash
+node scripts/plugin-knowledge.js list-plugins
+node scripts/plugin-knowledge.js read-plugin --slug the-events-calendar
+node scripts/plugin-knowledge.js resolve-route --route /tribe/events/v1/events
+node scripts/plugin-knowledge.js resolve-property --property bundled_items
+node scripts/plugin-knowledge.js list-capabilities
+node scripts/wp-plugin-inventory.js --base-url <url> --out-dir <dir> [auth options]
+node scripts/plugin-knowledge-validate.js --write-index
+```
+
+To add or correct a plugin, edit `plugins/<slug>.json` and add a fixture — no skill logic
+changes. See `plugins/README.md`.
+
+## Product and variation stock
+
+Extract `stock_status`, `manage_stock`, `stock_quantity`, `backorders`,
+`backorders_allowed`, and `backordered` from products and every variation. Use
+`lib/woo-inventory.js` → `mapWooInventory(record, {parent})` during canonical mapping.
+Persist its `fields` on the canonical variant and its disposition beside the source ID.
+An untracked product can still be explicitly in stock; `manage_stock:false` is not missing
+inventory. Use variation records for variable products; never replicate a parent's shared
+tracked quantity onto each child. Preserve `decision-needed` outcomes for missing signals,
+backorders, invalid quantities, and shared stock; do not turn them into an empty success.
+
 ## Read contract (codegen-time)
 
 What a generated WordPress reader must get right. Capture the operational facts below into
@@ -182,7 +761,9 @@ disk later without re-fetching the source.
 throttling, and `Retry-After`-aware 429/503 backoff a reader needs already exist as a
 dependency-free module at `lib/wp-http.js` in **this skill directory** (the same module
 the capture script imports). It
-exports `fetchJson`, `buildHeaders`, `configureRateLimit`, and `parseTotalHeader`. Any
+exports `fetchJson`, `buildHeaders`, `configureRateLimit`, and `parseTotalHeader`. It does
+**not** export an undenied transport — `fetchJson` refuses payment-gateway routes, and a
+generated reader must not reintroduce a raw one. Any
 generated WordPress reader **must reuse this module rather than reimplementing transport**,
 so the reader contains only per-project orchestration: which entities to pull, the
 pagination loop, `_embed`/`_links` resolution, and transform glue. One tested transport
@@ -191,6 +772,11 @@ carried into a runnable migration project is `rp-import-codegen`'s concern (its
 targets), not this adapter's. The notes below describe what the reader does *on top of*
 that shared core:
 
+- **Bounded media reads:** `fetchJson` accepts optional `deadlineMs`. One absolute deadline
+  includes the rate-limit wait, every fetch attempt, each attempt timeout, response handling,
+  and every retry delay. A wait that would finish after the deadline is not started. Omit
+  `deadlineMs` for all existing calls; their behavior stays unchanged.
+
 - **Namespaces & auth differ per namespace:**
   - `wp/v2` (core): HTTP Basic auth with a WordPress **Application Password**
     (`--username` + `--application-password`).
@@ -224,29 +810,88 @@ that shared core:
   name, blog title, tag label, CMS text columns) must be entity-decoded by the generated
   transforms or the encoded form appears verbatim in the Wix dashboard. HTML passed to
   rich-content conversion does NOT need pre-decoding — the converter handles entities.
+- **`slug` / `post_name` is percent-encoded for non-Latin values, and REST returns it
+  undecoded (trap, confirmed live on a non-Latin source 2026-09-27):** WordPress stores a
+  post/product slug whose original text contains non-Latin characters (e.g. Hebrew) as raw
+  UTF-8 percent-encoded escapes (`%d7%90%d7%99...`), and both `wp/v2` and `wc/v3` return this
+  field exactly as stored — no decoding happens server-side. The target's slug coercion
+  (`rp-target-wix`'s `toWixSlug`) turns the literal `%` characters into dashes rather than
+  erroring, so passing this value straight through silently produces a garbled
+  hex-with-dashes URL instead of the real slug. Generated transforms must decode `slug` /
+  `post_name` with `decodeURIComponent` before using it as a Wix slug or any other field —
+  guarded in a try/catch, since a slug that was never percent-encoded (or one containing a
+  literal `%` that isn't part of a valid escape) must pass through unchanged rather than throw
+  or get mangled. The decoded Unicode slug is then kept as-is (the coercion preserves letters
+  and digits in any script), so do not transliterate it. See the codegen-side rule in
+  `rp-import-codegen/SKILL.md`'s "Never hand-write slug sanitizing" section and the domain-knowledge pitfalls on `rp-target-wix`'s
+  `stores/entities/product.json` and `blog/entities/post.json`.
 - **Custom fields:** ACF / meta often appear in sample records but are absent from the
   `OPTIONS` schema — surface them as `unknowns` in discovery so the mapper can decide.
 - **WooCommerce variation attribute values are URL-encoded slugs, not display names (trap, hit live 2026-07-21):**
   `variations[].attributes[].value` from `wc/v3/products/{id}/variations` is a URL-encoded
-  taxonomy-term slug (e.g. `1-%d7%a7%d7%92` for `1 ק"ג`), not the human-readable display
+  taxonomy-term slug (e.g. `caf%c3%a9` for `café`), not the human-readable display
   name that the product's `attributes[].options[]` array contains. Generated readers must
   build a per-option slug→displayName map from the parent product's `attributes[].options[]`
   (which does carry display names) and resolve slug values to display names before writing to
   Wix. Passing slugs directly causes `MISSING_VARIANT_OPTION_CHOICE` because Wix compares
   variant choice names against option choice names and finds no match.
-- **WooCommerce "Any"-style variations have null attribute values (trap, hit live 2026-07-21):**
-  When a WooCommerce variation is set to "Any" for an option (the variation applies to any
-  value of that option), `variations[].attributes[].value` is an empty string or null, not a
-  specific term. Generated transforms that filter variants by attribute value will silently
-  drop "Any" variants, leaving options with no variants — Wix then auto-generates priceless
-  placeholder variants, causing price-empty errors. Fix: when ALL attributes for a variation
-  are null/"Any", treat the variation as a single cartesian entry covering all option choices
-  at the variation's price, rather than filtering it out.
+- **WooCommerce "Any"-style variations omit the attribute entirely, and fail silently (trap,
+  hit live 2026-07-21):**
+  `wc/v3` returns the per-variation field as `attributes[].option`, not `.value`. When a
+  WooCommerce variation is set to "Any" for an option (the variation applies to any value of
+  that option), that attribute is typically omitted from the variation's `attributes` array
+  entirely rather than present with a null/empty `option` — but treat a present-and-empty
+  `option` the same way if seen. Generated transforms that require every declared parent
+  attribute to appear on the variation will resolve an empty option set for it. **This does
+  not fail loudly** — Wix accepts the write — it surfaces only as a product that goes live
+  with zero purchasable options, found by a human browsing the storefront, not by any
+  automated check. Do not "fix" this by auto-expanding into a cartesian combination of all
+  option choices: live-refuted (the combination count explodes for some products,
+  because the attribute slots are ordinal pick-N-from-a-shared-list pickers,
+  not independent size/color axes). The correct handling is to record the loss for human
+  review rather than emit a default variant silently.
+- **The store's own configuration must be read DIRECTLY, and with the WordPress credential
+  (trap, hit live 2026-09-01):** `/wc/v3/settings/general` holds the business address
+  (`woocommerce_store_address`, `_address_2`, `_city`, `_postcode`, `woocommerce_default_country`),
+  the currency, which countries the shop sells to, and whether tax is calculated. Two reasons it
+  was never captured on any run:
+  1. **The REST index advertises only the parameterized form** `/wc/v3/settings/(?P<group>...)`,
+     never the literal group route, so nothing in the generic sweep ever fetches it. Read
+     `/wc/v3/settings/general` directly, the same way a shipping zone's `/locations` and
+     `/methods` sub-resources are — a parent-scoped sub-resource the caller resolves itself.
+  2. **The WooCommerce consumer key gets `401 woocommerce_rest_cannot_view` here; the WordPress
+     application password gets `200`.** Both are already in every run's source config. A reader
+     that only tries the store key gets a plausible "no permission" and moves on — which is
+     exactly how this stayed invisible while migrated sites published with an empty business
+     address.
+
+  `woocommerce_default_country` is `COUNTRY` **or** `COUNTRY:STATE` (e.g. `US:CA`) — the same
+  packing a zone's `state`-type location uses. `rp-target-wix/lib/store-config-build.js` maps the
+  whole group; do not hand-roll it.
 - **Route paths passed to `fetchJson` / `buildApiUrl` must NOT include `/wp-json` (trap, hit live 2026-07-21):**
   `buildApiUrl` in `lib/wp-http.js` already prepends `/wp-json` to the `routePath` argument.
   Generated route paths must start with the namespace directly (e.g. `/wc/store/v1/products`,
   `/wp/v2/posts`) — never with `/wp-json/...`. Prefixing with `/wp-json` doubles the prefix
   and produces 404s.
+- **WooCommerce consumer key/secret can 401 on some `wc/v3` routes even when it reads others
+  fine (trap, hit live 2026-08-12):** `WC_CONSUMER_KEY`/`WC_CONSUMER_SECRET` are scoped at
+  key-creation time (Read / Write / Read-Write) and can be narrower than the WordPress
+  Application Password's access. The consumer key/secret can 401
+  `woocommerce_rest_cannot_view` on `wc/v3/taxes`, `wc/v3/taxes/classes`, and
+  `wc/v3/settings/tax` while the very same reads succeeded immediately with the
+  `WP_USERNAME`/`WP_APPLICATION_PASSWORD` Basic auth pair. Generated readers must not treat a
+  401/403 on one `wc/v3` route as proof the whole consumer key is broken (which would wrongly
+  block products/orders/coupons too) — retry that specific route with the Application Password
+  credential before failing, and prefer the Application Password outright for admin-ish
+  `wc/v3` routes (taxes, settings) that a narrowly-scoped key is more likely to be denied on.
+- **Core WooCommerce settings/tax routes are core, not plugin data:** `wc/v3/taxes`,
+  `wc/v3/taxes/classes`, and `wc/v3/settings/tax` are ordinary WooCommerce core collections
+  (same auth/pagination rules as `wc/v3/products` etc.) — they are not profiled as a "plugin"
+  because tax is core WooCommerce, not an extension. Per-product `tax_status`/`tax_class`
+  fields ride along on the ordinary `wc/v3/products` read; no separate per-product route is
+  needed to get them. See `rp-target-wix` domains/tax/ for the corresponding Wix target
+  entities (Tax Group / Tax Region / Manual Tax Mapping / Tax Settings) and mapping-plan.json's
+  `product` and `tax-class` entities.
 
 ## Schema shape
 
@@ -254,3 +899,72 @@ that shared core:
 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 WordPress
 quirks (`restNamespace`, statuses, etc.) into each entity's open `sourceMeta` blob.
+
+For a profiled plugin entity, `sourceMeta` MUST also carry `requestMethod`, `requestBody`,
+and `responseFragmentGroupSize` verbatim whenever the plugin profile declares them — copy them from the profile entity (surfaced structurally in plugin detection's
+per-entity output, `wp-plugin-detect.js`'s `describeProfiledEntity`) rather than re-deriving
+them from discovery's prose notes. `rp-import-codegen`'s read contract depends on finding
+these under exactly those `sourceMeta` keys; omitting them silently degrades a declared
+non-GET/fragmented read into an unreadable one downstream.
+
+## Coupons, coupon usage and the currency gate
+
+Three source-side decisions, each in a library so a generated importer supplies facts rather than
+rules. Read `lib/coupon-discovery.js` and `lib/currency-gate.js`; both are pure.
+
+- **Coupons are counted from one surface and imported from the same one.** `wc/v3/coupons`
+  (published) is the discovered set and the denominator; sweep it to exhaustion with
+  `sweepCoupons(fetchPage)`, which refuses a total that disagrees with `X-WP-Total`. The `posts`
+  count by `post_status` is a reconciliation check only — `summarizeCoupons({ restCoupons,
+  postsByStatus })` reports the non-published rows as deliberately excluded, never as a shortfall
+  (the difference being drafts and auto-drafts).
+- **Redeemability, not expiry, classifies a coupon.** `classifyCoupon` — redeemable iff not expired
+  and not usage-exhausted; **`usage_limit` 0 or empty means UNLIMITED**. A `usage_limit` or
+  `usage_count` that is not an integer (`"1.5"`, `"abc"`) is `unresolved`: neither redeemable nor
+  exhausted, not written (`coupon-usage-limit-unresolved`), its own partition line. Import all
+  published coupons; the report carries the breakdown, never "imported N coupons".
+- **Mapping reports rather than approximates.** `mapCouponToWix(coupon, { resolveProduct,
+  resolveCategory })` returns a Wix specification or a named refusal: `fgf_free_gift` and any
+  unknown `discount_type` are `coupon-type-unmappable`, and so is an **unrestricted
+  `fixed_product`** (a per-unit amount on every product; Wix's money-off takes it off the order
+  once — a product-scoped one maps); a scope Wix cannot hold in one group is
+  `coupon-scope-unmappable`. An exhausted single-use code is imported `active: false`, because
+  Wix's usage count starts at zero. An eligibility constraint Wix cannot hold — excluded products
+  or categories, a sale-item exclusion, a maximum discount amount, an email restriction, or a
+  minimum spend on a product/collection-scoped coupon — is a **refusal** (`coupon-scope-unmappable`,
+  reason `scope: constraints`): dropped, each would make the coupon more generous than the
+  merchant published. Only a dropped amount on a free-shipping coupon stays a per-coupon finding.
+- **Coupon usage rides on the order.** On legacy post storage the surface is the order's REST
+  `coupon_lines[]` (each carrying
+  `discount` per code); HPOS stores have `wc_order_coupon_lookup`. Name whichever was found as
+  `coupon-usage-surface`. The target side (`rp-target-wix/lib/order-applied-discount-build.js`)
+  turns the lines into `appliedDiscounts` through the coupon crosswalk; an unresolved code writes
+  nothing and is reported.
+- **Currency halts before any order write.** `currency-gate.js` `evaluateCurrencyGate({
+  settingsCurrency, orderCurrencies, targetSiteCurrency })` — settings from
+  `wc/v3/settings/general` through `store-currency.js`, order currencies through
+  `resolveOrderCurrency` (which decodes `&#8362;` and refuses a contradicting symbol). One
+  currency matching the site proceeds with `currency-validated`; a mismatch or a history spanning
+  two currencies is a **halt**, and unresolved orders halt too. Two configured currencies with a
+  single-currency history proceeds, with the configuration reported.
+- **Plan-shaped sources are gated by row counts** (`B1` subscription products, `B2` membership
+  CPT, `B3` recurring-plan meta), never by plugin detection. Zero rows on all three reports "no pricing plans found". The gate and the plan body live target-side
+  in `rp-target-wix/lib/pricing-plan-definition.js`.
+
+## Currency is a store setting, not an order field
+
+`order.currency` is documented as an ISO 4217 code. Do not trust it. A store can return
+`currency: "&#8362;"` (an HTML-encoded currency SYMBOL) on every order, because a plugin or
+theme filter has overridden the field. Passed through, the payment
+existence gate refuses every payment as a currency mismatch; passed through without a gate it
+labels amounts with a symbol.
+
+`lib/store-currency.js` resolves it: `readStoreCurrency()` reads `woocommerce_currency` from
+`/wc/v3/settings/general` (one request per run, and the store's own authoritative setting), and
+`resolveOrderCurrency(order, storeCurrency)` trusts the order's own value when it is a plausible
+ISO code — a multi-currency store legitimately holds several — and falls back to the store setting
+when it is not. It reports `order-currency-not-iso` when it falls back, because a store that
+mangles this field is a store whose other currency-bearing fields are suspect too.
+
+It never infers a code from a symbol. `$` is at least a dozen different currencies, and guessing
+one silently mislabels money.