@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-replatform/resources/rp-source-wordpress/lib/yoast-product-seo-evidence.js

@@ -1,272 +0,0 @@
-'use strict';
-
-// Per-field Yoast override evidence for WooCommerce products.
-//
-// `yoast_head_json` is Yoast's RENDERED output: it can carry a title for every product while the
-// raw override meta holds none. Importing the rendered text turns an inherited template into
-// hundreds of hard per-product overrides. So this module
-// decides, per product and per field, whether the SOURCE proves an override, and records how it
-// knows. Rendered output alone is never proof; it only supplies the decoded value once the raw
-// meta has proven the field was overridden.
-//
-// Deterministic by design. The only I/O is the caller-supplied `queryPage` (a bound
-// wix-wp-plugin-v2 `queryStructure`), so every branch is unit-testable offline.
-
-const FIELD_KEYS = Object.freeze({
-  title: '_yoast_wpseo_title',
-  description: '_yoast_wpseo_metadesc',
-  focusKeyword: '_yoast_wpseo_focuskw',
-});
-// Exact allow-list; never widened by key discovery.
-const ALLOWED_KEYS = Object.freeze(Object.values(FIELD_KEYS));
-const SEO_FIELDS = Object.freeze(Object.keys(FIELD_KEYS));
-const HEAD_FIELD = Object.freeze({ title: 'title', description: 'description' });
-const STATES = Object.freeze(['override', 'inherit', 'unknown']);
-
-// A post_id list is sent inline in the `where` clause, so keep one batch well inside a request.
-const DEFAULT_BRIDGE_BATCH = 50;
-const MAX_BRIDGE_BATCH = 200;
-const MAX_BRIDGE_PAGES = 1000;
-
-function isBlank(value) {
-  return value == null || String(value).trim() === '';
-}
-
-const NAMED_ENTITIES = Object.freeze({
-  amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', ndash: '–', mdash: '—',
-  hellip: '…', lsquo: '‘', rsquo: '’', ldquo: '“', rdquo: '”', laquo: '«',
-  raquo: '»', copy: '©', reg: '®', trade: '™', middot: '·', bull: '•',
-});
-
-// Exactly ONE decoding pass. `&amp;amp;` becomes `&amp;`, never `&`: decoding repeatedly would
-// corrupt a title that legitimately contains an entity-looking string.
-function decodeEntitiesOnce(value) {
-  return String(value).replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, body) => {
-    if (body[0] === '#') {
-      const code = body[1] === 'x' || body[1] === 'X' ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
-      return Number.isInteger(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match;
-    }
-    const named = NAMED_ENTITIES[body.toLowerCase()];
-    return named === undefined ? match : named;
-  });
-}
-
-function sanitizeRendered(value) {
-  if (typeof value !== 'string') return null;
-  const decoded = decodeEntitiesOnce(value).trim();
-  return decoded === '' ? null : decoded;
-}
-
-// Channel 1: the product post's REST `meta` object. A key counts only when `meta` contains it;
-// a response without the key (not registered for the product type, or unauthenticated) leaves
-// that key unresolved -- never "no override" -- so it can fall through to the bridge.
-function restEvidence({ response, path = null } = {}) {
-  const meta = response && typeof response.meta === 'object' && !Array.isArray(response.meta) ? response.meta : null;
-  const out = {};
-  for (const key of ALLOWED_KEYS) {
-    if (meta && Object.prototype.hasOwnProperty.call(meta, key)) {
-      out[key] = { resolved: true, raw: meta[key], evidenceRef: { path, keyPresentInMeta: true } };
-    } else {
-      out[key] = { resolved: false, reason: meta ? 'key-absent-from-rest-meta' : 'rest-meta-unavailable', evidenceRef: { path } };
-    }
-  }
-  return out;
-}
-
-function pinnedKeysOf(eavAccess, keyColumn) {
-  if (!eavAccess) return null;
-  const pairs = [eavAccess, ...(eavAccess.additionalPairs || [])];
-  const pair = pairs.find((p) => p && p.keyColumn === keyColumn);
-  if (!pair || pair.tier !== 'key-scoped' || !Array.isArray(pair.pinnedKeys)) return null;
-  return pair.pinnedKeys;
-}
-
-// Channel 2: wix-wp-plugin-v2 key-scoped postmeta read, paginated to exhaustion.
-// `queryPage({ structureRequest, cursor })` resolves to queryStructure's `{ rows, pagingMetadata,
-// eavAccess }`. A batch is COMPLETE only when every page succeeded, the response proved a
-// key-scoped read of every queried key, and the last page reported no next cursor. Anything else
-// leaves the batch incomplete -- and only that batch.
-async function readBridgeEvidence({ queryPage, table, productIds, keys = ALLOWED_KEYS, batchSize = DEFAULT_BRIDGE_BATCH, keyColumn = 'meta_key', valueColumn = 'meta_value', idColumn = 'post_id', orderColumn = 'meta_id' } = {}) {
-  if (typeof queryPage !== 'function') throw new Error('readBridgeEvidence: queryPage is required');
-  if (!table || typeof table !== 'string') throw new Error('readBridgeEvidence: table (the prefixed postmeta table) is required');
-  if (!Array.isArray(productIds)) throw new Error('readBridgeEvidence: productIds must be an array');
-  if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > MAX_BRIDGE_BATCH) {
-    throw new Error(`readBridgeEvidence: batchSize must be 1..${MAX_BRIDGE_BATCH}`);
-  }
-  const wanted = [...new Set(keys)];
-  if (!wanted.length || wanted.some((key) => !ALLOWED_KEYS.includes(key))) {
-    throw new Error(`readBridgeEvidence: keys must be a non-empty subset of ${ALLOWED_KEYS.join(', ')}`);
-  }
-  const ids = [...new Set(productIds.map(String))];
-  const batches = [];
-  for (let start = 0, index = 0; start < ids.length; start += batchSize, index += 1) {
-    const batchIds = ids.slice(start, start + batchSize);
-    const structureRequest = {
-      table,
-      select: [{ column: orderColumn }, { column: idColumn }, { column: keyColumn }, { column: valueColumn }],
-      where: [
-        { column: keyColumn, op: 'in', value: wanted },
-        { column: idColumn, op: 'in', value: batchIds.map((id) => (/^\d+$/.test(id) ? Number(id) : id)) },
-      ],
-      orderBy: [{ column: orderColumn, direction: 'asc' }],
-    };
-    const batch = { batchId: `yoast-bridge-${index}`, productIds: batchIds, keys: wanted, pageCount: 0, complete: false, finalHasNext: null, reason: null, failedPage: null, rows: [] };
-    let cursor;
-    for (;;) {
-      if (batch.pageCount >= MAX_BRIDGE_PAGES) { batch.reason = 'page-limit-exceeded'; break; }
-      let page;
-      try {
-        page = await queryPage({ structureRequest, cursor });
-      } catch (error) {
-        batch.failedPage = batch.pageCount + 1;
-        batch.reason = `page ${batch.failedPage} failed: ${error && error.message ? error.message : String(error)}`;
-        break;
-      }
-      batch.pageCount += 1;
-      const pinned = pinnedKeysOf(page && page.eavAccess, keyColumn);
-      if (!pinned || wanted.some((key) => !pinned.includes(key))) {
-        batch.failedPage = batch.pageCount;
-        batch.reason = `page ${batch.pageCount} did not prove a key-scoped read of every queried key`;
-        break;
-      }
-      if (!page || !Array.isArray(page.rows) || !page.pagingMetadata || typeof page.pagingMetadata.hasNext !== 'boolean') {
-        batch.failedPage = batch.pageCount;
-        batch.reason = `page ${batch.pageCount} had no rows/pagingMetadata`;
-        break;
-      }
-      for (const row of page.rows) {
-        batch.rows.push({ productId: String(row[idColumn]), key: row[keyColumn], value: row[valueColumn] });
-      }
-      batch.finalHasNext = page.pagingMetadata.hasNext;
-      if (!page.pagingMetadata.hasNext) { batch.complete = true; break; }
-      const next = page.pagingMetadata.cursors && page.pagingMetadata.cursors.next;
-      if (!next) { batch.reason = `page ${batch.pageCount} reported hasNext without a cursor (truncated)`; break; }
-      cursor = next;
-    }
-    batches.push(batch);
-  }
-  return batches;
-}
-
-function resolveOverrideValue(field, raw, yoastHeadJson) {
-  if (field === 'focusKeyword') return { value: String(raw).trim() };
-  const rendered = sanitizeRendered(yoastHeadJson && yoastHeadJson[HEAD_FIELD[field]]);
-  if (rendered !== null) return { value: rendered };
-  const trimmed = String(raw).trim();
-  if (!trimmed.includes('%%')) return { value: trimmed };
-  return { unknown: 'override-has-yoast-variables-and-no-resolved-value' };
-}
-
-// The per-product audit receipt. It is stored with the extraction and is NOT hashed as a
-// whole; only `seoHashProjection` (rp-target-wix/lib/product-seo.js) feeds the source hash.
-function buildProductSeoReceipt({ productId, capturedAt, rest = null, bridgeBatch = null, yoastHeadJson = null } = {}) {
-  if (productId == null || String(productId) === '') throw new Error('buildProductSeoReceipt: productId is required');
-  if (!capturedAt) throw new Error('buildProductSeoReceipt: capturedAt is required');
-  const id = String(productId);
-  const fields = {};
-  for (const field of SEO_FIELDS) {
-    const key = FIELD_KEYS[field];
-    const failures = [];
-    let raw;
-    let provenance = null;
-    const restKey = rest && rest[key];
-    if (restKey && restKey.resolved) {
-      raw = restKey.raw;
-      provenance = { channel: 'rest', readComplete: true, evidenceRef: { path: restKey.evidenceRef.path, keyPresentInMeta: true } };
-    } else {
-      failures.push(restKey ? `rest: ${restKey.reason}` : 'rest: not read');
-      if (bridgeBatch && bridgeBatch.complete && bridgeBatch.productIds.includes(id) && bridgeBatch.keys.includes(key)) {
-        const row = bridgeBatch.rows.find((r) => r.productId === id && r.key === key);
-        raw = row ? row.value : undefined;
-        provenance = {
-          channel: 'bridge',
-          readComplete: true,
-          evidenceRef: { batchId: bridgeBatch.batchId, productIds: bridgeBatch.productIds, pageCount: bridgeBatch.pageCount, finalHasNext: false, rowPresent: Boolean(row) },
-        };
-      } else {
-        failures.push(!bridgeBatch ? 'bridge: unavailable' : `bridge: ${bridgeBatch.reason || 'key not read for this product'}`);
-      }
-    }
-    if (!provenance) {
-      fields[field] = { state: 'unknown', rawPresent: false, provenance: { channel: 'none', readComplete: false, evidenceRef: { failures } } };
-      continue;
-    }
-    const rawPresent = raw !== undefined && raw !== null;
-    if (!rawPresent || isBlank(raw)) {
-      fields[field] = { state: 'inherit', rawPresent, provenance };
-      continue;
-    }
-    const resolved = resolveOverrideValue(field, raw, yoastHeadJson);
-    if (resolved.unknown) {
-      fields[field] = { state: 'unknown', rawPresent, provenance: { ...provenance, evidenceRef: { ...provenance.evidenceRef, failures: [resolved.unknown] } } };
-    } else {
-      fields[field] = { state: 'override', rawPresent, value: resolved.value, provenance };
-    }
-  }
-  return { productId: id, capturedAt, fields };
-}
-
-// Receipts for a whole extraction. `products` rows: { id, yoast_head_json?, restResponse?,
-// restPath? }. `bridgeBatches` is readBridgeEvidence's output (or [] when the bridge is absent).
-function buildProductSeoReceipts({ products, bridgeBatches = [], capturedAt } = {}) {
-  if (!Array.isArray(products)) throw new Error('buildProductSeoReceipts: products must be an array');
-  const batchFor = new Map();
-  for (const batch of bridgeBatches || []) for (const id of batch.productIds) batchFor.set(String(id), batch);
-  return products.map((product) => buildProductSeoReceipt({
-    productId: product.id,
-    capturedAt,
-    rest: product.restResponse ? restEvidence({ response: product.restResponse, path: product.restPath || null }) : null,
-    bridgeBatch: batchFor.get(String(product.id)) || null,
-    yoastHeadJson: product.yoast_head_json || null,
-  }));
-}
-
-// Canonical-record projection of a receipt (`product.seoEvidence`). `rendered` carries the
-// sanitized rendered title/description ONLY so an owner's `materialize` choice has a value to
-// write; it is never proof and never written without that choice.
-function seoEvidenceFromReceipt(receipt, { yoastHeadJson = null, permalink = null } = {}) {
-  const out = {};
-  for (const field of SEO_FIELDS) {
-    const f = receipt.fields[field];
-    out[field] = f.state === 'override' ? { state: 'override', value: f.value } : { state: f.state };
-  }
-  out.rendered = {
-    title: sanitizeRendered(yoastHeadJson && yoastHeadJson.title),
-    description: sanitizeRendered(yoastHeadJson && yoastHeadJson.description),
-  };
-  out.canonical = classifyProductCanonical(yoastHeadJson, permalink);
-  return out;
-}
-
-// A computed self-canonical (the product's own source permalink) is never written: Wix
-// generates its own. A canonical pointing anywhere else may be intentional, but REST cannot prove
-// it and no policy for foreign canonicals is approved, so it is flagged, never written.
-function normalizeUrl(value) {
-  try {
-    const url = new URL(String(value));
-    return `${url.host.toLowerCase()}${decodeURI(url.pathname).replace(/\/+$/, '')}`;
-  } catch (e) {
-    return null;
-  }
-}
-function classifyProductCanonical(yoastHeadJson, permalink) {
-  const canonical = yoastHeadJson && yoastHeadJson.canonical;
-  if (isBlank(canonical)) return 'none';
-  if (permalink && normalizeUrl(canonical) && normalizeUrl(canonical) === normalizeUrl(permalink)) return 'self';
-  return 'pending_policy';
-}
-
-module.exports = {
-  FIELD_KEYS,
-  ALLOWED_KEYS,
-  SEO_FIELDS,
-  STATES,
-  DEFAULT_BRIDGE_BATCH,
-  decodeEntitiesOnce,
-  restEvidence,
-  readBridgeEvidence,
-  buildProductSeoReceipt,
-  buildProductSeoReceipts,
-  seoEvidenceFromReceipt,
-  classifyProductCanonical,
-};

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

@@ -1,373 +0,0 @@
-# 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.