@wix/agent-skills 1.33.1 → 1.35.0

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

@@ -0,0 +1,373 @@
+# WordPress Plugin Profiles
+
+Declarative, machine-readable profiles describing how to **detect** one WordPress /
+WooCommerce plugin and **how to read** its durable business data.
+
+Profile files are the source of truth. `index.json` is generated from them and checked in so
+runtime lookups stay token-cheap. `lib/plugin-knowledge.js` is the authority on a profile's
+shape; the field reference below documents it.
+
+## What a profile is, and is not
+
+- **It is** detection signals, per-entity read channels, route scope, and pointers to Wix
+  target refs.
+- **It is not** authoritative about what a route returns. The live `OPTIONS` + sample `GET`
+  in `scripts/wp-discovery.js` always is. A profile is *advisory*: a stale one can only make
+  detection less complete — it can never cause a wrong read.
+- **It does not** hold Wix target behavior. That lives in
+  `replatform/resources/rp-target-wix/domains/`. A profile only points at target refs
+  (`candidateTargetRefs`) and declares its `capabilities`.
+
+## Recognized or not
+
+A plugin does not need a profile to migrate; it needs one to migrate *natively*.
+
+| Population | What it means |
+| --- | --- |
+| recognized | a profile matched — named entities, channels, and target refs are known; the mapping is `confirmed` |
+| derived | no profile, but the data is REST-visible; the mapping is `proposed` (CMS, or native when the domain KB confirms the proposed capability) |
+| named only | detected with no readable channel — lands in *Pending* or on the no-migration-needed list, reported, never silent |
+
+The invariant: **every installed plugin lands in exactly one of the four statuses**
+(migration-planned · no-need-to-migrate · pending · requires-development). Authoring a
+profile is always an upgrade from a working baseline, never the difference between working
+and broken.
+
+### Two states automation may assign, and one only a human may
+
+**By default every plugin is either profiled or pending.** A capability with no resolved Wix
+target is *pending*, not impossible.
+
+| State | Means | Assigned by |
+| --- | --- | --- |
+| migration planned / no need to migrate | resolved to a Wix target — native or CMS — or nothing to move | automation |
+| **pending** | we do not know how to migrate this yet | automation — **the default** |
+| **requires development** | Wix genuinely has no surface for this | **a named human, only** |
+
+**Why the restriction.** An agent concluded twice that Wix had no target — gift cards and
+events — and was wrong both times, because Wix splits capabilities across doc trees and a
+service plugin reads like an absent write API. A wrong impossibility is the most expensive
+error in this system: it tells a customer to abandon data that could have moved. So automation
+is capped at *pending*, and the impossibility verdict needs a name against it.
+
+**Recording pending** — `capabilities-pending-decision.json`, optional but useful: `reason`,
+the `searched` evidence, and `suspected` (`target-exists` with a `plannedTarget` to author, or
+`no-target` if we think Wix cannot). `suspected` carries **no authority** — a `no-target`
+suspicion is still pending until signed.
+
+**Recording a verdict** — `requires-development.json` requires `decidedBy` and
+`decidedOn` alongside the search. Validation rejects an entry without them, and rejects any
+entry once a target entity claims that capability, so a verdict cannot outlive its truth.
+
+**Recording "nothing to move" for a capability of a profiled plugin** — the `capabilities[]`
+register in `no-migration-needed.json`: `capability`, `reason` (`platform-does-it` /
+`not-needed` / `reconfigure-in-wix`), `replacedBy`, `rationale`, `decidedBy`, `decidedOn`. The
+slug list below cannot carry this (a slug with a profile is rejected there) and
+*requires-development* is the wrong verdict when Wix covers the outcome natively — so this is
+the third register, and the only way a profiled capability reaches *No need to migrate*
+(`basis: decision`). It is not an impossibility verdict, so no recorded search is required,
+but it is still signed: unsigned entries fail validation and are ignored at runtime. Mutually
+exclusive with the other two registers, and rejected once a target entity claims the
+capability.
+
+**Recording "CMS may keep the records" — `cms-fallback-eligible.json`.** A profile **never**
+names a `cms/*` ref in `candidateTargetRefs` (validation rejects it, and the classifier drops
+one from a stale profile): a profile-declared CMS ref used to ship as a *confirmed* CMS plan
+with no merchant decision. CMS keeps a plugin's records; it does not bring back what the plugin
+*did*. So a recognized capability reaches CMS only through two gates:
+
+1. **Eligibility (here, signed).** One `capabilities[]` entry per capability: `capability`,
+   `targetRefsByEntity` (`"<plugin-slug>/<entity>": ["cms/collection", ...]`, keys covering
+   exactly the capability's profile entities), `reason` (why nothing native fits),
+   `nativeAlternativesChecked`, `featureLoss` (one merchant-readable sentence of what does not
+   work after archival — shown verbatim at the ask and in reports), `decidedBy`, `decidedOn`,
+   optional `note`. Only a capability whose every declaring profile declares exactly one
+   capability may appear (a multi-capability profile's entity set is ambiguous). Every ref
+   starts with `cms/` and resolves. Mutually exclusive with `requires-development.json` and
+   the no-need `capabilities[]` register, and rejected once a target entity claims the
+   capability. Unsigned entries fail validation and are ignored at runtime.
+2. **Approval (per migration, the merchant).** Eligibility alone plans nothing: the row stays
+   *Pending* (`cms-fallback-awaiting-approval`) until the merchant approves or declines at the
+   mapping review, recorded as `pluginCmsFallback:<capability>` in that project's
+   `orchestration/decisions.json` by `orchestration-state.js decide-cms-fallback`. Nothing is
+   written back to this register.
+
+Unresolved capabilities are deliberately **not** a validation error. Blocking there would push
+authors to invent a verdict just to make the build pass — which is the failure this rule exists
+to prevent. The coverage report surfaces pending rows and asks a human instead.
+
+### Promotion paths into the recognized population
+
+Two triggers, three possible destinations. Adding a plugin is a data change: no classifier,
+discovery, mapper or codegen edit.
+
+| Trigger | Destination | Cost |
+| --- | --- | --- |
+| **Research phase** — we investigate a plugin we expect to matter | full profile | research doc → profile → target entity → area entry |
+| **After a run** — telemetry flags it unresolved, a human reviews it | full profile | same four |
+| Either, and it turns out to need **no** data migration | one `no-migration-needed.json` line | one line |
+
+**Order matters: author the target entity before the profile that points at it**, or record the
+capability as awaiting a target. Validation enforces this rather than leaving it to memory.
+
+## Read channels
+
+| `channel` | Reads from | Needs |
+| --- | --- | --- |
+| `plugin-rest` | the plugin's own namespace | sometimes plugin-specific credentials |
+| `core-cpt` | `/wp/v2/<rest_base>` | nothing extra |
+| `core-embedded` | properties injected into core/Woo records | sometimes `context=edit` |
+| `core-meta` | registered meta (`show_in_rest`) | auth for edit-context meta |
+| `plugin-rest-child` | a `{parentId}`-templated sub-resource on an already-sampled parent (`route` + `parentRoute`) | nothing extra, but only a representative sample — see SKILL.md |
+| `export-file` | a user-supplied WXR / CSV / JSON export | the file |
+| `db-only` | plugin custom tables | see "Resolving a db-only capability" below |
+| `admin-page-only` | a wp-admin settings page with no REST route at all (config, not records) | human transcription — see below |
+
+**Resolving a `db-only` capability -- try this order, do not default straight to a user file:**
+
+1. **Check whether the plugin exposes a REST route at all.** Confirm live against
+   `GET /wp/v2/plugins` and the REST index -- do not assume from the plugin's name or
+   marketing copy.
+2. **If there is no REST route, check the plugin's own admin UI for a built-in export
+   first.** Two `db-only` guesses on this project turned out to have one (Discount Rules'
+   CSV export, MailPoet's own REST API) and needed no bridge at all -- an existing native
+   export is simpler than authoring a new fulfillment.
+3. **Research the plugin's actual storage mechanism** before assuming a bridge can reach
+   it: check the plugin's public docs/WordPress.org page, or clone its public GitHub
+   source (many WordPress.org plugins are mirrored) and grep for `CREATE TABLE` /
+   `dbDelta` (a real custom table) versus `get_option`/`update_option` (`wp_options`) or
+   `add_post_meta`/`add_user_meta` (postmeta/usermeta). This determines which of the next
+   two steps applies -- guessing wrong wastes a whole fulfillment-authoring attempt.
+4. **A genuine custom database table is reachable, with zero user effort, via
+   wix-wp-plugin-v2's `structure-bridge-plugin` fulfillment kind -- try
+   this BEFORE falling back to a user-supplied export.** wix-wp-plugin-v2 is this skill
+   bundle's own bridge plugin (unlike the retired Wix Migration Helper below, it ships
+   with this skill and is meant to be installed on every source site this adapter
+   targets). Its `/structure` route describes any live table's real columns; its `/query`
+   route reads it with a safe, validated query. A permanent profile is optional: for an
+   unfamiliar plugin prepare an evidence-backed project-local entity plan through
+   [the shared producer](../PLUGIN-READ-PLANS.md). Do not edit this bundle during a migration.
+   Reuse a complete supported REST reader first. When maintaining a reusable profile,
+   author its entity's `blocked[]` as
+   `{"kind": "structure-bridge-plugin", "resolution": "<what/why, cite live evidence>",
+   "declined": false, "fulfillment": {"kind": "structure-bridge-plugin", "handlerId":
+   "wix-wp-plugin-v2", "table": "<bare_table_name>"}}` -- `handlerId`/`table` (and the
+   optional `sampleStructureRequest` below) live nested under `fulfillment`, not flattened
+   onto the `blocked[]` entry itself; `resolution` and `declined` are required on every
+   `blocked[]` entry regardless of kind (see the field reference below). Add
+   `sampleStructureRequest` when a raw "every column" read would expose something that needs
+   filtering or aggregating -- see `pw-woocommerce-gift-cards.json`'s gift-card-balance
+   aggregate for a full worked example of the complete shape.
+   See `lib/wix-wp-plugin-v2-client.js`, `scripts/wp-discovery.js`'s
+   `sampleStructureBridgeEntities` for the full contract.
+
+   **Credential split, decided by whether the source site has WooCommerce.** The bridge's
+   routes register two ways: an Application Password path gated on
+   `current_user_can('manage_woocommerce')`, and a signed migration-key JWT path gated only
+   on the signature/request-binding. `manage_woocommerce` does not exist on a WordPress
+   site with no WooCommerce installed, not even for an administrator -- on such a site the
+   Application Password bridge routes are structurally unusable for every user, so do not
+   offer an Application Password as the bridge credential on a content-only/blog/marketing
+   WordPress site; collect the migration key (`WMH2_MIGRATION_KEY`) instead. An Application
+   Password may still be required separately for private `wp/v2` reads. When a migration
+   key is configured, `wp-discovery.js` prefers the signed bridge route; otherwise it uses
+   the Application Password route when WooCommerce supplies the required capability.
+   Standard private `wp/v2`/`wc/v3` reads still require their own WordPress REST credential;
+   the migration key is never a substitute for that scope.
+5. **Know which tables the bridge can and cannot reach.**
+
+   | Table | Reachable? |
+   | --- | --- |
+   | `wp_options`, `wp_usermeta`, `wp_links`, multisite globals | **No, never.** No unlock path; pinning `option_name` does not help |
+   | `wp_postmeta`, `wp_commentmeta`, `wp_termmeta`, `wc_orders_meta`, any `*meta` table, or any table whose live schema carries a recognized key/value column pair | **Yes -- key-scoped.** Key names and counts are freely listable; a value is readable by naming its key (max 50 per request) |
+   | A table NAMED like a meta table whose key/value columns are *not* one of the six recognized pairs | **No.** No key column to pin means nothing to scope |
+   | Everything else | Yes, in full, minus the named credential columns in `COLUMN_DENYLIST` |
+
+   Row 2 is the one that changed. `wp_postmeta` **is** reachable now, via a two-step read
+   (discover key names, then read the keys you want) -- see `rp-source-wordpress/SKILL.md`'s
+   "Reading key/value tables through the bridge" for the request shapes. So Flamingo's message
+   data, which this list previously called permanently unreachable, is reachable: it is
+   `wp_postmeta` on a `flamingo_inbound` CPT. Checkout Field Editor's is not: it is a single
+   `wp_options` row (`thwcfe_sections`), and row 1 is unchanged.
+
+   **Do not declare a `user-file` blocker or accept a gap for a `wp_postmeta`-shaped entity
+   without checking this first.** Asking a site owner to hand-export data the bridge can read
+   is a real cost, and a profile that hard-codes "unreachable" outlives the reason it was
+   written. When research in step 3 lands on rows 1 or 3, then yes -- stop, and the remaining
+   options are `user-file` or accepting the gap.
+
+The retired Wix Migration Helper plugin used the same idea -- a
+site-installed bridge exposing specifically-named read-only REST routes for `db-only`
+data -- but was a bespoke, per-capability plugin the site owner had to install
+separately. wix-wp-plugin-v2 replaces it with one generic bridge covering any table,
+subject only to the reachability table in step 5; do not author a new profile against the retired
+`bridge-plugin` fulfillment kind.
+
+**`admin-page-only` is not the same limitation as `db-only`.** `admin-page-only` means the
+*configuration itself* renders only inside an authenticated wp-admin page (e.g.
+`wp-admin/admin.php?page=<slug>`), and **WordPress Application Passwords do not
+authenticate wp-admin page loads at all** — only REST API requests. VERIFIED against a
+live WordPress installation (Discount Rules for WooCommerce's `woo_discount_rules`
+settings page): a Basic-Auth request with a valid Application Password 302-redirects to
+`wp-login.php?reauth=1`, the standard unauthenticated-session response, identical to what
+an anonymous request gets. There is no scrapeable path here — WordPress core does not
+extend Application Password auth to admin page rendering, by design.
+
+### Blocked source data and fulfillment
+
+An entity may declare `blocked[]` only for a concrete, evidenced access gap. Every entry needs a
+`kind` (`user-file` or `structure-bridge-plugin`), a `resolution` (what/why, citing live
+evidence), and a `declined` boolean (whether the user has already declined this ask at
+run time -- always `false` at authoring time). `user-file` means the owner must supply or
+transcribe data; it does not imply a machine-readable import path. `structure-bridge-plugin`
+means wix-wp-plugin-v2 (this skill bundle's own generic bridge -- see "Resolving a `db-only`
+capability" above) can read the table directly; its optional `fulfillment` names the
+registered `handlerId` and the bare `table` to read (plus an optional `sampleStructureRequest`
+-- see the field reference below). A future file handoff uses `fulfillment.kind:
+"csv-upload"` with a registered `handlerId` and `expectedInputPath`.
+
+wix-wp-plugin-v2 has no manifest or case registry of its own to check a fulfillment's
+readiness against -- unlike the retired, per-capability Wix Migration Helper bridge, which did (`manifestCaseId`, `expectedNamespace`, `extractionRoute`,
+`productionReady: true` -- do not author against that retired shape). Authorization for
+`structure-bridge-plugin` is a live core-table denylist plus a live `DESCRIBE` check at
+request time, not a build-time readiness flag. Markdown documents are never runtime readiness
+authorities.
+
+Do not ask the user for their real WordPress account password to work around this — that is a
+materially more sensitive credential than an Application Password and outside this pipeline's
+secrets model. The correct escalation is the same one already established for other
+structurally-invisible config (Checkout Field Editor's custom fields, PW Gift Cards' DB-only
+balances): surface it as a `blocked: [{kind: "user-file"}]`-style row at the mapping review
+gate and ask the site owner to transcribe or screenshot the specific admin page, since they can
+view it directly with their own login.
+
+`core-embedded` matters more than it looks: several major WooCommerce extensions add **no
+REST route at all** and only widen `wc/v3/products` / `wc/v3/orders` payloads. Those plugins
+are detectable solely from sampled record keys, which is why detection runs a second pass
+after sampling.
+
+`plugin-rest-child` is for a sub-resource that needs a known parent id first (e.g.
+`/wc/v3/orders/{parentId}/notes`) and so can never be listed as its own flat collection.
+`route` carries the literal `{parentId}` placeholder; `parentRoute` names the collection route
+(already in scope and sampled) that supplies real ids. See SKILL.md's "Read channels" section
+for how presence is checked and why a live per-parent sample is a representative check, not a
+completeness claim.
+
+## Adding a plugin
+
+1. Read the vendor's REST documentation and record its URL in `sourceOfTruth`.
+2. Create `plugins/<slug>.json` following the field reference below. The filename slug must
+   equal `plugin`.
+3. Declare detection signals. Prefer `pluginFileIds` and `routes` (high confidence) over
+   `restNamespaces` and `assetPathSlugs` (low confidence — `wc/v3` is shared by dozens of
+   plugins).
+4. Declare one entity per durable record type, each with a `channel` and
+   `candidateTargetRefs`. An entity with no target refs must carry a `pitfall` explaining the
+   gap. Never list a `cms/*` ref: if nothing native fits and CMS should keep the records, a
+   named human adds a signed `cms-fallback-eligible.json` entry instead.
+5. Put helper, runtime, and configuration routes in `excludeRoutes` so the plugin's data
+   routes can be opted in without widening scope.
+6. Add a fixture: extend `test-fixtures/rest-index-plugins.json` and, if relevant,
+   `test-fixtures/wp-plugin-signals.json`, then assert detection in
+   `scripts/wp-plugin-contract-test.js`.
+7. Regenerate and validate:
+
+```bash
+node scripts/plugin-knowledge-validate.js --write-index
+node scripts/wp-plugin-contract-test.js
+node scripts/wp-discovery-classifier-test.js
+```
+
+## Profile field reference
+
+`lib/plugin-knowledge.js` is the **authority** on this shape — there is no `schema.json`, on
+purpose: a second non-enforcing definition of the same contract only drifts out of sync.
+
+**Required:** `schemaVersion` (1) · `plugin` (must equal the filename slug) · `displayName` ·
+`profileVersion` (bump when the plugin's API changes) · `sourceOfTruth` (vendor docs URL) ·
+`capabilities[]` · `detect` · `entities[]`.
+
+**`detect`** — at least one signal required:
+
+| Field | Confidence | Notes |
+| --- | --- | --- |
+| `pluginFileIds[]` | high | `plugin` values from `GET /wp/v2/plugins`. Matched on the directory too, because the main-file basename often differs (`wordpress-seo/wp-seo`). |
+| `routes[]` | high | routes whose presence in the REST index identifies this plugin |
+| `restBases[]` | medium | `rest_base` from `/wp/v2/types` or `/wp/v2/taxonomies` |
+| `recordProperties[]` | medium | keys this plugin injects into core/Woo payloads; the only way to see route-less extensions |
+| `restNamespaces[]` | low | **shared platform namespaces are rejected** — `wc/v3` identifies WooCommerce, not your plugin |
+| `assetPathSlugs[]` | low | `/wp-content/plugins/<slug>/`, works with no credentials |
+| `minVersion` | — | below it, detection reports `api-below-min-version` rather than assuming the API |
+
+**`entities[]`** — each requires `entity`, `channel`, `candidateTargetRefs[]`. `capability` is
+optional for backward compatibility, but required on every entity once any entity in that profile
+uses it; it must name one of the profile's `capabilities[]`. This attribution prevents a
+multi-capability profile's entities and target refs from leaking into each other's coverage rows.
+Then:
+**The FIRST `blocker`-severity pitfall across a capability's entities is what the merchant
+reads.** `classifyCoverage` uses it verbatim as the coverage row's `userImpact`, and
+`buildDispositionRows` joins those into the plugin's `consequence` line. So lead that one with
+the consequence in plain words and put the internal instruction after it — an authoring note or
+a cross-reference in first position becomes the customer-facing sentence.
+
+`route` (route-bearing channels; a `{parentId}`-templated path for `plugin-rest-child`) ·
+`parentRoute` (`plugin-rest-child` only — the already-sampled collection route parent ids come
+from) · `responseEnvelope` (route-bearing channels only — `{itemsPath, countPath}` for a
+non-standard wrapped response; see below) · `embeddedIn[]` + `propertyPath` (`core-embedded`) ·
+`context` (`view`/`edit`/`both`, when the two differ) · `requiresParent` (sub-collection
+ordering) · `hierarchical` · `recordKeyField` · `relations[]` · `pitfalls[]`
+(`code`/`severity`/`summary`) · `blocked[]` (an evidenced access gap; `kind`, `resolution`,
+`declined`, and optional executable `fulfillment`) · `overridesCoreRule`.
+
+**`responseEnvelope`** — for a plugin whose REST route does not return a flat array (or a
+single object), and does not advertise `X-WP-Total`/`X-WP-TotalPages` headers. `itemsPath` is
+the dot-path to the array of records inside the response body (e.g. MailPoet's
+`"data.items"`); `countPath` is the optional dot-path to the true total count when the header
+is absent (e.g. `"data.meta.count"` — without it, `recordCount` reflects only the sampled
+page, same as a headerless flat array). Sampling and counting otherwise behave exactly as they
+would for a flat array once unwrapped — this only changes *where in the response* the sampler
+looks.
+
+**Optional top level:** `distribution` · `credentials[]` (plugin-specific keys) ·
+`dataRoutePatterns[]` (wholly data-bearing namespaces) · `excludeRoutes[]` ·
+`quirks[]`. (`dispositionHint` is retired — a plugin either has a profile or a `no-migration-needed.json` entry, never both.)
+
+## Rules the validator enforces
+
+- `plugin` matches the filename; `schemaVersion` is 1; `profileVersion` and `sourceOfTruth`
+  are present (drift provenance).
+- Every `candidateTargetRefs` entry resolves in `rp-target-wix/domains/index.json`, and none
+  is a `cms/*` ref (CMS goes through `cms-fallback-eligible.json` plus the merchant's approval).
+- `cms-fallback-eligible.json` entries are signed, complete, CMS-only, cover exactly the
+  capability's profile entities, belong to single-capability profiles, and are exclusive with
+  the other two signed registers.
+- Every `capability` is claimed by a Wix target entity's `capability` field **or** listed in
+  `requires-development.json` with a reason.
+- Route-bearing channels declare `route`; `core-embedded` declares `embeddedIn` +
+  `propertyPath`.
+- A wildcard route pattern keeps at least **two concrete leading segments**: `/ssp/v1/*` is
+  allowed, `/yoast/*` is not. This is what stops a profile from silently reopening an
+  excluded route family.
+- No two profiles claim the same route, and no profile shadows a classifier core rule
+  without `"overridesCoreRule": true`.
+
+## Route precedence
+
+Highest to lowest:
+
+1. operator `--exclude-route`
+2. profile `excludeRoutes`
+3. profile entity routes and `dataRoutePatterns`
+4. the classifier's own category rules
+5. generic collection-shape acceptance
+6. unsupported by default
+
+Profile data routes outrank exclusion families because an explicitly listed route *is* the
+per-capability opt-in — bounded by the wildcard rule above.
+
+## Maintenance
+
+- Keep long analysis separate from the profile; profiles carry compact facts and a `sourceOfTruth` link.
+- Bump `profileVersion` when a plugin's API changes.
+- A capability that keeps resolving as `proposed` across real runs is the signal to
+  write a profile for it.

package/skills/wix-replatform/resources/rp-source-wordpress/plugins/advanced-custom-fields.json

@@ -0,0 +1,101 @@
+{
+  "schemaVersion": 1,
+  "plugin": "advanced-custom-fields",
+  "displayName": "Advanced Custom Fields",
+  "profileVersion": "2026-08",
+  "sourceOfTruth": "https://wordpress.org/plugins/advanced-custom-fields/",
+  "distribution": "wordpress-org",
+  "capabilities": [
+    "content.custom-fields",
+    "content.custom-field-schema"
+  ],
+  "detect": {
+    "pluginFileIds": [
+      "advanced-custom-fields/acf"
+    ],
+    "recordProperties": [
+      "acf",
+      "_acf_changed"
+    ],
+    "assetPathSlugs": [
+      "advanced-custom-fields"
+    ]
+  },
+  "entities": [
+    {
+      "entity": "field-values",
+      "channel": "core-embedded",
+      "embeddedIn": [
+        "/wp/v2/posts",
+        "/wp/v2/media",
+        "/wp/v2/categories",
+        "/wp/v2/tags",
+        "/wp/v2/users"
+      ],
+      "propertyPath": "acf",
+      "candidateTargetRefs": [],
+      "pitfalls": [
+        {
+          "code": "acf-key-rides-every-wp-v2-object-type",
+          "severity": "info",
+          "summary": "ACF registers a single REST field named `acf` per request, against whichever object sub type the request resolves to - post type, taxonomy or user. [VERIFIED IN PLUGIN SOURCE v6.8.7, includes/rest-api/class-acf-rest-api.php register_field(), 2026-08-16.] [VERIFIED LIVE 2026-08-16] the key is present on every sampled record of /wp/v2/posts, /wp/v2/pages, /wp/v2/media, /wp/v2/product, /wp/v2/podcast, /wp/v2/tribe_events, /wp/v2/categories and /wp/v2/users. embeddedIn lists the core routes; any plugin CPT the classifier accepts through wp.data.registered-type carries it too, so an extraction step must look for `acf` on every wp/v2 record it fetches rather than only on the listed routes. /wp/v2/pages is listed nowhere because pages are excluded from backend-data scope by wp.frontend.pages."
+        },
+        {
+          "code": "absent-from-woocommerce-rest",
+          "severity": "warning",
+          "summary": "[VERIFIED LIVE 2026-08-16] the `acf` key does NOT appear on any sampled /wc/v3/products or /wc/v3/products/categories record - ACF only extends the wp/v2 controllers. Custom field values on a WooCommerce product are therefore readable only through /wp/v2/product, which returns no commerce fields, so a product import that wants both must join the two by post id."
+        },
+        {
+          "code": "empty-array-means-no-groups-not-no-plugin",
+          "severity": "warning",
+          "summary": "[VERIFIED LIVE 2026-08-16] a site with no field groups defined returns `acf: []` on every sampled record - an empty ARRAY, not an object. Detection must treat presence of the key as the signal and must not require a truthy value; and a run that finds only empty acf keys should report 'ACF installed, no field data' rather than a failed read. [NEEDS-VERIFICATION on a site with real field groups: the populated shape (a {fieldName: value} object) and the per-field-type value shapes.]"
+        },
+        {
+          "code": "value-shapes-are-field-type-dependent",
+          "severity": "warning",
+          "summary": "ACF returns typed values, not strings: a relationship or post-object field returns post IDs (or embedded objects when ACF's rest_api_embed_links setting is on), an image/file field returns an attachment ID or an object, a repeater returns an array of row objects, a flexible-content field returns rows tagged with acf_fc_layout, and a taxonomy field returns term IDs. Every ID-bearing value must be remapped through the relevant crosswalk after its target exists, exactly like any other reference. A CMS collection column type cannot be chosen without knowing the field type, which is why field-group-definitions is a prerequisite rather than a nice-to-have. [DOCUMENTED - ACF field-type reference; not exercised live.]"
+        },
+        {
+          "code": "rest-visibility-is-opt-in-per-field-group",
+          "severity": "warning",
+          "summary": "The `acf` property only carries a group's fields when that field group has Show in REST API enabled, and the whole integration can be switched off site-wide (acf_get_setting('rest_api_enabled')). Accordion, tab and message field types are never exposed (show_in_rest = false on those classes). [VERIFIED IN PLUGIN SOURCE v6.8.7, includes/rest-api/class-acf-rest-api.php and includes/fields/class-acf-field-{accordion,tab,message}.php, 2026-08-16.] So an empty or partial acf object can mean 'not exposed' rather than 'not set', and the run cannot tell the two apart from REST alone - reconcile against the field-group definitions before reporting completeness."
+        }
+      ]
+    },
+    {
+      "entity": "field-group-definitions",
+      "channel": "export-file",
+      "candidateTargetRefs": [],
+      "pitfalls": [
+        {
+          "code": "acf-field-group-cpt-is-not-rest-visible",
+          "severity": "blocker",
+          "summary": "Field group definitions are stored as posts of the `acf-field-group` post type, registered with 'show_in_rest' => false. [VERIFIED IN PLUGIN SOURCE v6.8.7, includes/post-types/class-acf-field-group.php:104, 2026-08-16.] [VERIFIED LIVE 2026-08-16: acf-field-group is absent from /wp/v2/types, identical authenticated and unauthenticated, and GET /wp/v2/acf-field-group returns 404, as do acf-field, acf-post-type, acf-taxonomy and acf-ui-options-page.] There is no REST read path, authenticated or otherwise, so this entity is Blocked - recoverable (kind: user-file) until the user supplies an export."
+        },
+        {
+          "code": "the-export-the-user-must-produce",
+          "severity": "warning",
+          "summary": "ACF ships its own exporter - ACF > Tools > Export Field Groups, which emits a JSON file (or generates PHP) - and many themes keep the same JSON checked in under an acf-json/ directory. Either is the file to ask for. That JSON carries the field key, name, label, type, per-type settings (choices, sub_fields, layouts, return_format) and the location rules that say which post types the group applies to; the WXR export does NOT reliably carry it, because the definitions are posts plus their own acf-field child posts. Ask for the ACF JSON specifically, not for a WXR."
+        },
+        {
+          "code": "definitions-are-the-cms-schema",
+          "severity": "warning",
+          "summary": "This entity does not migrate as records - it is the input that decides the shape of the Wix CMS collection that field-values lands in: one column per ACF field, with the column type derived from the ACF field type, and one collection per (post type x field group) grouping. cms/collection is setup-config: the collection must exist before any item import, and creating it is not automated. Import ordering is therefore definitions (setup) -> owning records -> field values."
+        },
+        {
+          "code": "group-definitions-are-not-lost-if-unavailable",
+          "severity": "info",
+          "summary": "If the user cannot supply the export, the field VALUES are still fully readable from the `acf` key and can land in a CMS collection whose columns are inferred from the observed values. That is reduced fidelity - inferred types, no labels, no choice lists, repeaters flattened or stored as JSON - and it must be ledgered as such, but it is never a reason to drop the data."
+        }
+      ]
+    }
+  ],
+  "quirks": [
+    "Plugin file id is `advanced-custom-fields/acf` - the main-file basename is `acf`, not the directory name, and the /wp/v2/plugins id carries no .php suffix [VERIFIED LIVE 2026-08-16: active, version 6.8.7, textdomain acf]. Never construct dir/dir.php. ACF PRO is a separate directory (advanced-custom-fields-pro/acf) and would appear as its own row.",
+    "Storage model: two different ones in one plugin, which is why it has two entities. Field VALUES are ordinary post/term/user meta that ACF re-exposes as a computed REST property (`acf`), so they are REST-visible without being registered meta - channel core-embedded. Field GROUP DEFINITIONS are a post type deliberately hidden from REST - channel export-file. Reading the values without the definitions is possible but lossy; reading the definitions without a user-supplied file is impossible.",
+    "Registers NO REST namespace of its own [VERIFIED LIVE 2026-08-16: the site's REST index advertises no namespace such as acf/* or acf/v3]. ACF is a textbook route-less plugin: nothing about it appears in the REST index, and the only way to see it is the payload-key pass over sampled records - the 'record payload keys' tier, and the reason detection is split into two passes.",
+    "Enqueues no front-end asset [VERIFIED LIVE 2026-08-16: no wp-content/plugins/advanced-custom-fields path in the homepage or a post permalink], so assetPathSlugs will not fire and the fingerprinted tier cannot see ACF from public HTML. It is listed anyway because a theme that enqueues an ACF-provided script would expose it.",
+    "ACF also leaves a registered meta key `_acf_changed` on every post [VERIFIED LIVE 2026-08-16: present in the `meta` object of /wp/v2/posts, /wp/v2/pages, /wp/v2/product and /wp/v2/categories records, authenticated AND unauthenticated, value false]. It is an editor bookkeeping flag with no migration value, but it is a reliable secondary detection signal that survives when a site has zero field groups and every `acf` value is empty.",
+    "ACF's newer builders - ACF Post Types, ACF Taxonomies and ACF Options Pages - are stored as the acf-post-type / acf-taxonomy / acf-ui-options-page post types, all equally hidden from REST [VERIFIED LIVE 2026-08-16: all 404]. The custom post types they CREATE are normal registered types and are discovered by the classifier's wp.data.registered-type rule as usual, so their records are never missed; only the builder definitions are invisible. Options-page values are wp_options rows and are not readable at all."
+  ]
+}

package/skills/wix-replatform/resources/rp-source-wordpress/plugins/back-in-stock-notifier-for-woocommerce.json

@@ -0,0 +1,81 @@
+{
+  "schemaVersion": 1,
+  "plugin": "back-in-stock-notifier-for-woocommerce",
+  "displayName": "Back In Stock Notifier for WooCommerce | WooCommerce Waitlist Pro",
+  "profileVersion": "2026-08",
+  "sourceOfTruth": "https://wordpress.org/plugins/back-in-stock-notifier-for-woocommerce/",
+  "distribution": "wordpress-org",
+  "capabilities": [
+    "commerce.back-in-stock-notifications"
+  ],
+  "detect": {
+    "pluginFileIds": [
+      "back-in-stock-notifier-for-woocommerce/cwginstocknotifier"
+    ],
+    "restNamespaces": [
+      "back-in-stock/v1",
+      "wc-instocknotifier/v3"
+    ],
+    "assetPathSlugs": [
+      "back-in-stock-notifier-for-woocommerce"
+    ]
+  },
+  "entities": [
+    {
+      "entity": "back-in-stock-subscriber",
+      "channel": "plugin-rest",
+      "route": "/wc-instocknotifier/v3/list_subscriber",
+      "recordKeyField": "id",
+      "requestMethod": "POST",
+      "requestBody": {
+        "p_ids": "$SAMPLED_IDS:/wc/v3/products",
+        "status": "cwg_subscribed"
+      },
+      "responseFragmentGroupSize": 4,
+      "candidateTargetRefs": [
+        "stores/back-in-stock-request"
+      ],
+      "pitfalls": [
+        {
+          "code": "two-namespaces-live-simultaneously",
+          "severity": "warning",
+          "summary": "[VERIFIED LIVE 2026-08-19] The installed build (v7.3.3, a paid/CodeCanyon-tier release) advertises BOTH `back-in-stock/v1` (new; only a GET namespace-self-description at `/subscriber` and a POST-only `/subscriber/create` with an undocumented body) AND the legacy `wc-instocknotifier/v3` namespace matching the free wordpress.org v5.6.1 codebase. Use the legacy namespace -- it is the one with a working read path."
+        },
+        {
+          "code": "list-endpoint-is-post-not-get",
+          "severity": "info",
+          "summary": "[VERIFIED LIVE 2026-08-19] The read/list endpoint is `POST /wc-instocknotifier/v3/list_subscriber` with a JSON body, not a GET collection route. This entity declares `requestMethod`/`requestBody` so `wp-discovery.js` samples it automatically like any other candidate -- no `--include-route` override needed, and no plugin-specific sampler code. The `$SAMPLED_IDS:/wc/v3/products` placeholder resolves to the product ids already sampled earlier in the same run; at discovery time this is only the small sample page (schema learning, not bulk extraction) -- `rp-import-codegen` must pass the FULL catalog id list at execution time, not rely on the discovery-time sample."
+        },
+        {
+          "code": "status-any-returns-nothing",
+          "severity": "blocker",
+          "summary": "[VERIFIED LIVE 2026-08-19] Passing `status: \"any\"` in the request body returns an empty array -- WordPress's `any` magic value excludes custom post statuses registered as excluded-from-search, which this plugin's statuses are. Pass the literal status string instead, e.g. `{\"p_ids\": [<all catalog product ids as strings>], \"status\": \"cwg_subscribed\"}`. `p_ids` uses a meta_query `IN` comparison, so an empty or omitted array also returns nothing -- pass the real product id list."
+        },
+        {
+          "code": "response-shape-is-flattened-and-buggy",
+          "severity": "info",
+          "summary": "[VERIFIED LIVE 2026-08-19, matches free v5.6.1 source `includes/class-rest-api.php` format_subscriber_data_schema()] The plugin's own multi-record response is malformed: each subscriber is emitted as 4 SEPARATE single-key array entries (`{id}`, `{last_modified_date}`, `{status}`, `{meta_data}`) in sequence, not one merged object. This entity declares `responseFragmentGroupSize: 4` so `wp-discovery.js` reassembles the flat array back into one record per subscriber automatically -- generically across any entity, no plugin-specific sampler code. Record count = flat array length / 4."
+        },
+        {
+          "code": "storage-is-a-custom-post-type",
+          "severity": "info",
+          "summary": "[DOCUMENTED, free v5.6.1 source `includes/class-api.php`] Each subscriber is a `cwginstocknotifier` custom post (not `show_in_rest`, invisible to `/wp/v2/types`). post_status encodes state: `cwg_subscribed` / `cwg_unsubscribed` / `cwg_doubleoptin` / `cwg_mailsent` / `cwg_mailnotsent` -- only `cwg_subscribed` rows are live/current signups worth importing. Meta keys: `cwginstock_subscriber_email`, `cwginstock_pid` (product-or-variation id used for matching), `cwginstock_product_id`, `cwginstock_variation_id`, `cwginstock_subscriber_name`, `cwginstock_subscriber_phone`, `cwginstock_custom_quantity`, `cwginstock_user_id`, `cwginstock_created_via`."
+        },
+        {
+          "code": "write-endpoint-also-exists-and-was-used-for-seed-data",
+          "severity": "info",
+          "summary": "[VERIFIED LIVE 2026-08-19] `POST /wc-instocknotifier/v3/create_subscriber` accepts and creates real subscriber records. Required fields: `subscriber_name`, `email`, `product_id`, `status`, `subscriber_phone`, `custom_quantity`; optional `variation_id`. Duplicate (email, pid) pairs are rejected 403 by the plugin's own dedup, not a bug to work around."
+        },
+        {
+          "code": "no-admin-csv-export-on-this-site",
+          "severity": "info",
+          "summary": "The plugin ships an admin UI at wp-admin -> Instock Notifier -> All Subscribers, but its one-click CSV export is a SEPARATE paid add-on, not part of the base plugin (checked 2026-08-19) -- do not assume the Discount-Rules-style admin-export escape path is available without checking first."
+        }
+      ]
+    }
+  ],
+  "quirks": [
+    "Vendor: CodeWooGeek (`codewoogeek`). Free tier on wordpress.org tops out at v5.6.1 (namespace `wc-instocknotifier/v3`); the CodeCanyon/paid tier (verified here at v7.3.3) additionally registers a `back-in-stock/v1` namespace but keeps the legacy namespace and its REST controller working unchanged -- confirmed by calling both live against the same install.",
+    "wp-admin menu: **Instock Notifier -> Settings** / **Instock Notifier -> All Subscribers** (left sidebar top-level menu, not under WooCommerce)."
+  ]
+}