=== Fernlight Migration ===
Contributors: softseasdigital
Tags: migration, kadence, importer, block-editor, fse
Requires at least: 6.5
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 1.2.18
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

See how cleanly your site maps to the Fernlight editorial theme, then create reviewable Fernlight drafts with local Migration Handoff Pack exports.

== Description ==

Moving to the **Fernlight** editorial theme? Fernlight Migration does both halves of the move in one place: it tells you how well your site fits *before* you change anything, then converts supported builder content into matching Fernlight blocks when you are ready.

It opens on a read-only **fit audit** and offers an opt-in **"Create Fernlight drafts"** step for supported builders, core block content, and legacy Minimalist blocks. Both are free.

**1. Audit — how well does my site fit? (read-only)**

Install it on your current site and it scans your content, then shows:

* A plain-language **fit verdict** — strong fit, partial fit, or "this is a marketing-heavy site an editorial theme would leave a lot behind."
* A **mapping-confidence breakdown** — what maps cleanly, what maps approximately, and what has no editorial equivalent.
* A **block-by-block table** — each of your blocks and the Fernlight block or pattern it would become.
* An honest **gap list** — the constructs (countdown timers, progress bars, animations) a calm editorial theme intentionally does not recreate. Knowing this up front is the point.

It understands two kinds of source today:

* **Kadence** — full Kadence Blocks mapping (rows, headings, tabs, accordions, info boxes, testimonials, counters, icon lists, post grids, header/footer builder, and more).
* **Stackable** — audit support plus draft creation through the shared Fernlight mapping engine.
* **CoBlocks** — audit support plus draft creation through the shared Fernlight mapping engine.
* **Block themes / core blocks** — sites already built on core blocks map almost as-is, with legacy Minimalist blocks mapped to Fernlight-friendly equivalents where possible.

**The audit never changes your site.** It only reads your content to produce the report, and **no data ever leaves your server** — there is no tracking and no phone-home. You do not need the Fernlight theme installed to run it.

**2. Migrate — convert supported builders to Fernlight (creates drafts)**

The same screen offers the intelligent migration engine:

* A **review-and-confirm mapping report** — exactly how each block will translate, with clean / approximate / needs-a-match confidence badges.
* One-click creation of **Fernlight-ready draft copies** you can review before publishing.
* It scans posts and pages, reusable blocks, templates and template parts, and WooCommerce products.
* Each draft stores local provenance metadata: source title/URL, source block summary, mapping confidence, content hashes, gap explanations, and migration run id.
* Baked-in legacy theme chrome is removed from migrated page bodies and saved as
  reviewable header/footer `wp_template_part` drafts instead of being repeated in
  content.

**Your original content is never edited.** Anything without a clean editorial match is preserved and flagged so a matching Fernlight pattern can be built; the plugin keeps a local, private log of that demand — nothing is sent anywhere.

**3. Migration Handoff Pack — export review evidence**

The audit includes a local **Migration Handoff Pack** download in JSON or Markdown. It includes the fit verdict, confidence counts, gap explanations, pattern-demand evidence, source item summaries, and next-step prompts that Companion and Pro can understand, but not full page content. Use it to help an owner review options with an AI assistant; it does not decide what to keep, rebuild, or publish.

After the audit, the next steps are explicit: create draft copies when the owner
is ready, review gaps, or ask an AI assistant to inspect the handoff pack.

When you are ready to go live, install the free Fernlight theme and the optional Fernlight Companion plugin, then review and publish your drafts.

== Installation ==

1. Upload the plugin to `/wp-content/plugins/`, or install it from the Plugins screen.
2. Activate it.
3. Go to **Tools → Fernlight Migration** to read your audit and create Fernlight drafts.

== WP-CLI ==

After installing and activating Fernlight Migration through the normal WordPress plugin workflow:

* `wp fernlight migrator expose-tools [--context=stage|prod] [--off]`
* `wp fernlight migrator status --format=table|json`
* `wp fernlight migrator assess [--post-type=<post,page>] [--include-drafts] [--format=table|json]`
* `wp fernlight migrator export-handoff --out-dir=<path> [--source=<slug>] [--limit=<count>] [--format=json|md|both]`
* `wp fernlight theme presets list|validate|set [--slug=<slug>]`
* `wp fernlight companion status|capabilities|pillar-source [--source=category|tag] [--format=table|json]`
* `wp fernlight tools preflight [--format=table|json]`
* `wp fernlight tools demand [--format=table|json] [--limit=<count>] [--clear]`

Use `wp fernlight companion pillar-source --source=tag` to switch pillar-based accent assignment to post tags across compatible card surfaces.

== CLI onboarding ==

Recommended staging flow after normal plugin installation and activation:

1. `wp fernlight migrator expose-tools --context=stage`
2. `wp fernlight tools preflight --format=table`
3. `wp fernlight tools demand --format=table --limit=25`
4. `wp fernlight migrator status --format=table`
5. `wp fernlight migrator assess --post-type=post,page --include-drafts --format=table`

Common responses:

* `context must be "stage" or "prod".`  
  Use only `--context=stage` or `--context=prod`.
* `Unsupported format ...`  
  Use `table` or `json` only.

== Operator SOP: staged vs production lanes ==

* **Staging lane (default):** activate the plugin, then run `expose-tools --context=stage`.
* **Production lane:** activate the plugin, then run `expose-tools --context=prod`.

Acceptance checks:

* `wp fernlight migrator expose-tools --context=stage|prod` exposes tooling for the requested context.
* `wp fernlight tools preflight` returns a valid JSON/table payload with `migrator_plugin=pass`.
* `wp fernlight tools demand` returns a valid payload.
* `wp fernlight migrator status` includes:
  - `migrator.active`
  - `migrator.tools_exposed`
  - detected source and fit verdict
* `wp fernlight migrator assess` returns a summary payload with `total`, `clean`, and `gap` counts.

== Frequently Asked Questions ==

= Does the audit change my site? =

No. The audit is strictly read-only — it scans your existing content to build a report and makes no changes of any kind.

= Does it send my content anywhere? =

No. Everything is computed locally in your WordPress admin. Nothing is transmitted off your server, in either the audit or the migration.

= What is the Migration Handoff Pack for? =

It is a local review pack for you, Companion, Pro, or your AI tool. It summarizes the audit, explains gaps in plain language, and lists next review steps without including full page content or making decisions for you.

= Do I need the Fernlight theme installed? =

No. You can run the audit on your current site, whatever theme you use, so you can assess fit before switching. You can also create the Fernlight draft copies first and switch the theme afterward.

= Will migrating overwrite my pages? =

No. Migration only creates new **draft** copies for you to review. Your original posts, pages, and templates are left exactly as they are.

= It says my site is "marketing-heavy" — what does that mean? =

Fernlight is an editorial/essayist theme. Sites built around marketing constructs (countdowns, progress bars, animated counters) will map poorly, and the audit tells you honestly rather than after you have switched.

= I came from the old Migration Scout or Kadence Migrator plugins — what happened? =

Those two plugins are now combined into this one. Fernlight Migration does the read-only audit (formerly Scout) and the Kadence conversion (formerly Kadence Migrator) together, using one shared mapping engine.

== Changelog ==

= 1.2.18 =
* Removes the public WP-CLI package installer and bootstrap commands; installation now uses the normal WordPress plugin workflow.
* Keeps local assessment, handoff, status, and tooling-exposure commands available after activation.

= 1.2.17 =
* Hardens legacy Minimalist Home conversion for anchor-wrapped cards, plural stat bars, bare-div value/label cells, and nested card stacks such as the featured-plus-secondary Latest Reads layout.
* Adds anchor-aware wrapper extraction and nested grid traversal so legacy card rows convert into native groups/columns instead of leaking raw inline card markup into paragraphs.

= 1.2.16 =
* Adds optional migration profile support: bundled JSON profiles can be auto-detected or selected, supplied profile JSON can be used for a single draft, and profile metadata is stored in mapping reports/provenance.
* Adds a draft Minimalist Beginnings profile plus fresh-agent instructions for generating future site profiles.
* Lets profile page-group mappings guide page-template decisions before fallback heuristics run.

= 1.2.15 =
* Converts unhandled preserved HTML fallbacks into editor-safe migration review cards with the source markup shown as code.
* Prevents live Custom HTML previews from breaking converted page drafts.

= 1.2.14 =
* Adds a separate legacy theme-chrome extraction pass for baked-in MB/header/footer HTML.
* Removes detected header/footer chrome from migrated page bodies and creates reviewable wp_template_part draft posts for Site Editor review.
* Shows detected theme chrome in the preview report and links generated chrome drafts from the success notice.

= 1.2.13 =
* Copies source categories and tags to migrated drafts and reports taxonomy parity before promotion.
* Serializes Fernlight server-rendered dynamic blocks as self-closing blocks instead of baked HTML snapshots.
* Migrates pull-quote text into the block attribute before self-closing.
* Maps legacy [mb_blog_grid] shortcodes to the live [fernlight_blog_grid] shortcode.

= 1.2.12 =
* Makes migrated legacy related grids editor-safe review groups instead of dynamic previews.
* Keeps listing shortcodes as shortcode blocks until native query output has editor validation coverage.

= 1.2.11 =
* Fixes silent content loss for attribute-only legacy Minimalist dynamic blocks, especially mb/related-grid.
* Makes comment-only fallback gaps visible for review instead of rendering as empty space.
* Stops HTML entities from being counted as hardcoded hex colors in migration reports.

= 1.2.10 =
* Fixes the 1.2.9 mixed-wrapper hero regression so raw h1 tags are decomposed into native demoted headings instead of preserved inside core/html.

= 1.2.9 =
* Converts generic legacy post/article HTML wrappers with headings, paragraphs, lists, quotes, images, or dividers into native Group content before core/html fallback.

= 1.2.8 =
* Decomposes legacy wp:html post bodies at top-level legacy wrappers before falling back to intentional core/html.
* Keeps short contact/form pages on the Standard template by ignoring form shortcodes and wrapper bands as Wide signals.

= 1.2.7 =
* Fixes infinite recursion in legacy HTML section/card/grid conversion by adding a depth cap and no-op wrapper guard.
* Preserves unstrippable mixed section chunks as intentional core/html instead of retrying native conversion on the same input.

= 1.2.6 =
* Converts legacy hero/band/card/stat/listing HTML wrappers to native core/Fernlight-shaped blocks before falling back to core/html.
* De-weights legacy header/footer chrome in page-template metrics so prose/contact pages do not get misclassified as Wide.
* Preserves listing shortcodes as shortcode blocks until native query-card-grid output has editor validation coverage.
* Keeps core/html audit rows approximate so passthrough debt is never reported as clean.

= 1.2.5 =
* Fixes page-template registration checks on WordPress builds that group templates by post type.
* Adds a final sanitizer so remaining freeform parser islands are wrapped as intentional core/html.
* Neutralizes preserved block delimiters inside HTML passthroughs so legacy blobs cannot escape their wrapper.

= 1.2.4 =
* Fixes WP-CLI table output fatals.
* Preserves native group wrappers when converting supported descendants.
* Makes HTML conversion lossless: unmatched chunks stay in intentional core/html and forms/scripts/embeds survive.
* Improves source-based page-template decisions with visible reasons, validation flags, and missing-template guards.
* Marks custom HTML blobs as approximate migration debt instead of clean adopt-as-is content.

= 1.2.3 =
* Adds publish-blocking validation for generated drafts.
* Assigns Fernlight page width templates during page migration.
* Improves native output for sections, buttons, query grids, category cards, and stat cards.

= 1.2.2 =
* Adds the WP-CLI command surface for staged migration operations, preflight and demand checks, handoff exports, and theme/Companion support checks.
* Hardens CLI package install handling so remote package installs require HTTPS zip URLs and local/remote zip validation behaves consistently.

= 1.2.1 =
* Adds core block / legacy Minimalist draft creation to the migration screen.
* Maps `mb/post-hero`, `mb/post-callout`, `mb/pull-quote`, and `mb/divider` to Fernlight or core equivalents, and marks `mb/related-grid` as an editor-safe review group.
* Exposes Companion AI tooling metadata in the migration UI and AI handoff exports.
* Keeps the draft section visible for posts, pages, templates, and other public content even when source detection falls back to core blocks.

= 1.2.0 =
* Renamed the review export story to Migration Handoff Pack and clarified
  that it can feed Companion/Pro review workflows without including full page
  content or phoning home.
* Added local Migration Handoff Pack exports in JSON and Markdown.
* Added plain-language gap explanations and owner-review prompts for approximate and needs-a-match mappings.
* Added richer draft provenance metadata: migration run id, source title/URL, source block summary, confidence counts, gap explanations, and content hashes.
* Expanded the private pattern-demand report so it can feed future Fernlight pattern planning without phone-home tracking.

= 1.1.0 =
* Added full Stackable audit adapter (40+ blocks mapped to core and Fernlight equivalents; layout, typography, media, interactive, social, commerce).
* Added full CoBlocks audit adapter (40+ blocks; form fields flagged as gap; gallery variants, tabs, accordion, hero, pricing).
* Auto-detects Stackable and CoBlocks content alongside Kadence via block-namespace tally.

= 1.0.0 =
* Initial release. Unifies the former Fernlight Migration Scout (read-only audit) and Fernlight Kadence Migrator (draft creation) into one plugin with a single shared Kadence-to-Fernlight mapping engine.
* Read-only multi-source fit audit (Kadence + core/block themes): fit verdict, confidence breakdown, block-by-block table, and gap list. No content changes, no phone-home.
* Intelligent Kadence migration: review-and-confirm mapping report and one-click creation of Fernlight-ready draft copies across posts, pages, reusable blocks, templates/template parts, and WooCommerce products. Originals are never touched.

== Upgrade Notice ==

= 1.2.0 =
Adds local Migration Handoff Pack exports and richer draft provenance while preserving the read-only audit and draft-first migration boundary.

= 1.0.0 =
Replaces the separate Fernlight Migration Scout and Fernlight Kadence Migrator plugins. If you have either installed, you can deactivate it after installing Fernlight Migration.
