rp-source-wordpress

name	rp-source-wordpress
description	WordPress and WooCommerce source adapter: REST capture, auth, pagination, and read contract for codegen. Use when the source platform is WordPress or WooCommerce.

rp-source-wordpress

WordPress / WooCommerce source adapter. Owns every WordPress-specific detail the platform-agnostic skills must not hardcode: how to capture the schema, how to read the data, auth models, pagination, and REST quirks.

When this skill is used

This is not a stage in the migration flow — it is a reference consulted by two stages:

• rp-discovery consults the Capture section to sample the source and produce the canonical source-profile.md + source-schema.json.
• rp-import-codegen consults the Read contract section to generate a reader that bulk-extracts WordPress data correctly (auth, pagination, wc/v3 vs wp/v2) into durable project-local files for the later import step.

rp-execute-import never consults this skill — by the time execution runs, the 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.

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.

Capture (discovery-time)

Sampling the source to learn its shape — not a bulk export.

The Wix domain knowledge base may be used as a classifier supplement during synthesis, but not as a sampling mandate. When a discovered WordPress/WooCommerce route matches a known alias, annotate the emitted entity with sourceMeta.candidateTargetRefs[]; do not turn that hint into a target decision here. Keep frontend, theme, runtime, admin, and 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 with empty values:

WP_BASE_URL=
WP_USERNAME=
WP_APPLICATION_PASSWORD=
WP_MEDIA_URL_REWRITE_FROM=
WP_MEDIA_URL_REWRITE_TO=
WC_CONSUMER_KEY=
WC_CONSUMER_SECRET=

Before requesting any WordPress / WooCommerce credentials for a URL-based migration, ask the user which data scope they want:

• public content only
• also include private/authenticated data

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. After that choice, collect sensitive values through the secure Secrets Manager flow; do not ask the user to paste them into chat.

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
WP_APPLICATION_PASSWORD	sensitive	Required for private/authenticated WordPress capture
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

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 return 401/403 with the WordPress Application Password.

WP_MEDIA_URL_REWRITE_FROM and WP_MEDIA_URL_REWRITE_TO are optional. Use them when the WordPress API is reached through a public tunnel but media/file URLs inside records still 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. 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.

1. Run the deterministic capture script from this skill's directory (the folder containing this SKILL.md; see CONVENTIONS.md):

   node scripts/wp-discovery.js --env-file <migrations-root>/<project>/config/source.wordpress.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). --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.

2. If the user chose public content only, run unauthenticated and keep the scope framed as public-only. Do not pivot into asking for credentials unless the user changes scope.

3. Credentials are required for a complete capture. Without auth, only published public content is reachable; drafts, WooCommerce (wc/v3), user PII, and private fields return 401/403, making their recordCount/inUse unreliable. The script flags this in its README under "Incomplete Capture (Authentication)" — do not treat an unauthenticated run as authoritative.

   Author identity is a specific casualty of public-only capture. Public /wp/v2/users lists only users who authored public posts and exposes no roles and no emails — admin vs editor vs contributor vs subscriber is indistinguishable. Roles/capabilities require context=edit (App Password with list_users) or a DB dump (wp_usermeta → wp_capabilities); WXR exports carry author login/email/display name but no roles either. Vanilla WP has no guest-byline concept (every byline is a user); plugin guest authors (Co-Authors Plus guest-author entities) are separate non-user records. Record author capture mode in the source profile — it determines the blog authorAttributionMode downstream (public-only → fallback/owner attribution; 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 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).

The raw capture is evidence, not a hand-off artifact. rp-discovery synthesizes it into the canonical artifacts and records traceability pointers (rawDiscovery, per-entity rawFile).

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.

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. 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. That data is reachable only from a WXR export or the database.
• 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.
• 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, 's , 's , 's ), and is authored and live-verified against the reference store (a real order id substituted into the template found 2 of 3 sampled orders had matching notes) — do not guess a plugin's installed-directory id when authoring a similar profile; confirm against a live response first, it is exactly the kind of fact a stale or invented guess silently gets wrong.

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 only source credential. A plugin REST namespace that honours WordPress authentication works with it, 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.
• blocked[] entries are collected and asked once, batched, each individually skippable. A user-file blocker is the one state no credential can fix: unregistered post meta and plugin tables are unreachable by any WordPress API, and Application Passwords cannot reach wp-admin, so a WXR or CSV export must be produced by the user. 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.
• 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.

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

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.

Read contract (codegen-time)

What a generated WordPress reader must get right. Capture the operational facts below into source-profile.md during discovery so codegen has them without re-deriving.

The generated reader is an extractor, not an in-memory bulk loader. It should fetch WordPress/WooCommerce records page by page and write them to project-local files (for example per-entity paged JSON files plus a manifest) so the import step can read from disk later without re-fetching the source.

Reuse the shared transport — do not regenerate it. The auth, URL building, rate-limit 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 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 core is what makes the sampler and the reader behave identically. How the module is carried into a runnable migration project is rp-import-codegen's concern (its File targets), not this adapter's. The notes below describe what the reader does on top of that shared core:

• Namespaces & auth differ per namespace:
  • wp/v2 (core): HTTP Basic auth with a WordPress Application Password (--username + --application-password).
  • wc/v3 (WooCommerce): consumer key / secret, sent as Basic auth over HTTPS (or as query params on some hosts). This is a different credential from the Application Password — both may be needed for a full migration.
• Pagination: ?page=N&per_page=M (max per_page is typically 100). Total pages are in the X-WP-TotalPages response header and total records in X-WP-Total — read those rather than guessing when to stop. Some public WooCommerce Store API collection routes paginate without X-WP-TotalPages; when that header is absent, generated readers must stop on the first page whose item count is smaller than per_page.
• Embedded relations: request ?_embed to inline related resources, or follow the _links block (author, wp:featuredmedia, wp:term) to resolve relations. The evidence pointers in source-schema.json relations come from this _links block.
• Hierarchical taxonomies: WordPress categories (and custom hierarchical taxonomies) carry a parent field on each term (0 = top-level). When any term has a non-zero parent, the source taxonomy is nested. Discovery must elevate this into structured schema — set "hierarchical": true on that entity in source-schema.json (see source-schema.example.json → category) rather than leaving parent buried in the raw dump. The Wix Blog category target is flat (no parent/child), so this flag is what triggers the mapper's mandatory lossiness entry; without it, the flatten happens silently.
• Rate limits / retries: not advertised; the capture script throttles (--rate-limit-rpm, default 120) and backs off on 429/503 honoring Retry-After. Generated readers should inherit the same discipline.
• Rich content: content.rendered / are HTML; requires (authenticated). Note which the reader should pull.

Schema shape

source-schema.example.json (in this skill folder) is the template rp-discovery follows when emitting migrations/<project>/source-schema.json. It is a shape to follow, not a strict schema to validate against. Keep the platform-agnostic core stable; push 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 (spec 0044/0045) — 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.