rp-discovery

name	rp-discovery
description	Discovers and documents the source platform schema (entities, fields, relationships) for a migration project. Use when capturing source structure before mapping to Wix.

rp-discovery

Discover and document the source-platform schema for the active migration project.

Purpose

Use this skill to inspect the source system, identify entities, relationships, fields, identifiers, media, rich content, and platform-specific constraints. Examples include Shopify, WordPress, WooCommerce, and custom CMS platforms.

This skill owns the platform-agnostic discovery process and its output contract (source-profile.md + source-schema.json). Platform-specific details — how to capture a given source, its auth model, REST quirks — live in a dedicated source adapter skill, not here. For WordPress / WooCommerce, that adapter is rp-source-wordpress. To support a new platform, add a sibling adapter (e.g. rp-source-shopify) and leave this skill unchanged.

Inputs

Expected inputs may include:

• migrations/<project>/orchestration/run.json
• migrations/<project>/orchestration/decisions.json
• source site/app URL
• source platform name when it cannot be inferred
• source acquisition mode when the platform offers multiple read paths
• source API docs
• credentials, tokens, or local dump files when available
• export files when the run is file-based rather than URL-based
• current project under migrations/<project>/
• project-local config under migrations/<project>/config/

Config gate before capture

Before running source capture, verify the project-local config files created by wix-replatform:

• config/wix.env should always exist with WIX_SITE_STRATEGY, WIX_SITE_ID, and WIX_AUTH_TOKEN keys, even though discovery itself may not use Wix credentials yet.
• config/source.<platform>.env should exist once the source platform is known. For WordPress this is config/source.wordpress.env.

If a required non-sensitive key is missing or blank, ask the user for that value and fill the config file before continuing. If a required sensitive key is missing or blank, use the secure Secrets Manager flow: check for an existing non-placeholder local env value, then an existing non-placeholder Wix secret under the resolved site, and ask the user to update the dashboard secret only for keys missing from both places. Never ask the user to paste sensitive values into chat. Never print secret values back to the user; report only present/missing.

Use skills/wix-replatform/scripts/source-secrets.js resolve for sensitive source keys. Its output is limited to key names and statuses.

Treat migrations/<project>/config/*.env as secret-bearing once they may contain real values. Do not inspect them with whole-file reads that echo contents into tool output. Use secret-safe checks only: existence, required key names, and present / blank / missing status.

Site creation precedence

If this skill encounters conflicting Wix guidance about how to create a new site + headless destination, wix-replatform's migration contract wins.

• Route headless destination creation back to resources/rp-destination/, which scaffolds via npm create @wix/new@latest headless. This is the verified way to get a genuine headless site; the account-level Projects API is deprecated for this workflow (it produced non-headless sites).
• Discovery is source-side and does not create the site itself — just defer to that section.

Workflow

1. Confirm the active project under migrations/<project>/.

2. Start from the source URL when available and try to identify the source platform yourself before asking the user. Use lightweight signals such as a REST index, headers, HTML/application markers, or platform-specific route patterns. Only ask the user to name the platform if detection remains inconclusive.

3. Once the platform is inferred, resolve the acquisition mode before requesting source credentials when the platform has materially different read paths.

   • For Shopify URL-based migrations, ask whether to use the Admin API or only publicly available storefront data.
   • For WordPress / WooCommerce URL-based migrations, ask whether to import public content only or also include private/authenticated data.
   • Only the WordPress / WooCommerce also include private/authenticated data branch should trigger the secure Secrets Manager collection flow for sensitive credentials. The public content only branch proceeds without credentials and should be described as limited to public data. For WooCommerce, this branch should still probe public Store API catalog routes such as /wc/store/v1/products and /wc/store/v1/products/categories before declaring commerce out of scope. Treat file/export ingestion as a separate flow that starts from user-provided files instead of a site URL probe; do not offer exports as a third option in the URL-based acquisition-mode question.

4. Then select the matching source adapter skill (e.g. rp-source-wordpress for WordPress / WooCommerce, rp-source-csv when the run is file-based). If no adapter exists for the platform, capture entities manually following the same output contract.

   • File-based runs (sourceMode=files_only, sourcePlatform=csv) use rp-source-csv regardless of which system produced the files; that adapter identifies the originating vendor from the header row. There is no acquisition-mode question and no credentials request for this path.

5. Run the adapter's capture step to produce a raw, machine-captured dump under <migrations-root>/<project>/data/<source>-discovery/. For WordPress, the capture script lives in rp-source-wordpress/scripts/ — run it from that skill directory (see rp-source-wordpress Capture section and CONVENTIONS.md). When using project-local secret-bearing config, prefer the script's deterministic path over shell sourcing. The adapter owns the capture mechanics, auth model, and platform quirks; this skill consumes its output. For long runs, pass and poll it per .

Artifacts to create or update

• migrations/<project>/discovery/run.json

• migrations/<project>/discovery/entities/

• migrations/<project>/discovery/warnings.json

• migrations/<project>/discovery/llm-handoff.json

• migrations/<project>/discovery/plugin-coverage.json

• migrations/<project>/discovery/review/plugin-coverage.md

• migrations/<project>/orchestration/checkpoints.json

• migrations/<project>/data/<source>-discovery/: raw machine-captured output from the source adapter. Treated as evidence, not a hand-off artifact — downstream skills reference it for traceability but do not read it wholesale.

• migrations/<project>/source-profile.md: source platform, access method, limits, auth, and operational notes. Synthesized from the raw capture. Capture the operational facts the adapter documents (auth model, pagination, rate limits) so rp-import-codegen has them without re-deriving.

• migrations/<project>/source-schema.json: machine-readable schema for entities and fields. Synthesized from the raw capture — this and source-profile.md are the canonical hand-off to rp-mapper. Include traceability pointers so the mapper can drill into a specific entity's raw file when needed:

  • top-level rawDiscovery: relative path to the raw capture dir, e.g. data/wp-discovery/.
  • per-entity rawFile: file name within that dir, e.g. wp-v2--posts.md.
  • per-entity recordCount and inUse so consumers can distinguish supported vs. actually-used entities.
  • per-entity relations derived from the source-declared relationships in the raw capture, so relationships are evidence-backed rather than guessed. Each relation should carry an evidence pointer back to the source signal it came from.
  • For WordPress / WooCommerce, synthesize entities only from sampled backend_data and accepted backend_metadata route artifacts. Do not synthesize entities from routes listed in skipped-routes.json unless the skipped-route record has ; in that case, include , , and when present in the entity .

Plugin coverage (source adapters that support it)

When the source adapter produces plugin evidence — WordPress / WooCommerce does — promote it into the canonical artifacts rather than leaving it in the raw capture:

• Copy the adapter's coverage rows into migrations/<project>/discovery/plugin-coverage.json (one artifact: capability rows plus the per-plugin projection), and render a short user-facing discovery/review/plugin-coverage.md grouped by the four statuses — Migration planned · No need to migrate · Pending · Requires development. The statuses are already customer-readable; phrase the rest in user terms ("your events will come across as a CMS collection"), never internal jargon.
• Emit plugin-derived entities into source-schema.json like any other entity, with sourceMeta.plugin, sourceMeta.capability, sourceMeta.channel, sourceMeta.recognized (a profile matched) and sourceMeta.candidateTargetRefs[].
• Derived (unrecognized) entities carry sourceMeta.origin: "generic-post-type" | "generic-taxonomy" and, when the source taxonomy is nested, "hierarchical": true so the mapper's mandatory hierarchy-lossiness rule fires.
• Entities read from a property embedded in a parent record carry sourceMeta.origin: "embedded" plus the parent route, so codegen extracts them from the parent fetch instead of issuing a second request.
• Record in source-profile.md: whether the plugin list was available, how many plugins were detected/unrecognized, and the counts by status. Downstream stages must not have to parse the raw capture to learn whether plugin coverage was complete.

Classifying an unrecognized plugin is a judgement, not a lookup. For every installed plugin with no profile, you — not the [js] layer — answer the only question that matters: is there anything here to migrate at all? The no-migration-needed list (plugins/no-migration-needed.json) is an input to that answer: a slug hit is strong evidence and not by itself the answer, because the list says nothing about what this particular installation is holding. Add your own reading of the registered types, taxonomies and data-shaped routes, and record the reasoning either way. Three exits, and only three:

• Nothing to move → No need to migrate, with basis: list (a list entry you confirmed) or basis: proposed (your own reading) and the rationale filled in — a list hit with no recorded confirmation is a failure.
• It holds data → propose a Wix capability; the row is Migration planned as proposed, decided at the mapping review.
• Cannot tell → leave the row Pending with reason: cannot-tell. An honest "cannot tell" is the point of Pending — it is what stops this step from becoming a silent way to drop data. Never resolve it yourself; the mapping review is the only exit.

You may never conclude that Wix cannot do something — Requires development is reachable only from the human-signed register or from the human at the gate.

A recognized (profiled) plugin is not yours to re-decide: its rows come from the profile and the registers. That includes a No need to migrate row with basis: decision — a human-signed per-capability entry in no-migration-needed.json (capabilities[]), settled and carrying its decidedBy / decidedOn. Report it; do not re-open it as Pending.

• Collect every blocked[] entry across rows (a missing credential, a file only the user has, a changed surface — Blocked — recoverable, never a status) and ask the user once, as a single batched request with each item individually skippable. Record each answer in orchestration/decisions.json under pluginBlocker:<capability>:<kind> with value provided or declined — the discovery script reads these back so a declined ask renders as declined, not as unanswered. Never block the run on a skipped capability.

Output quality rules

• Separate confirmed facts from assumptions.
• Record per-entity volume (record counts) so downstream skills know what the site actually uses, not just what it supports.
• Preserve source-specific identifiers exactly.
• Include enough detail for downstream mapping and code generation.
• Flag unknowns explicitly instead of inventing structure.