@respira/wordpress-mcp-server 7.3.0 → 7.4.0

package/skills/migrate-beaver-builder-to-bricks/SKILL.md

@@ -0,0 +1,251 @@
+# Migrate Beaver Builder to Bricks
+
+**Version:** 2.0.0
+**Updated:** 2026-06-30
+**Freshly updated:** v2.0.0 wires in current Respira safety and precision. Pre-migration now inventories source pages with `respira_find_builder_targets`. Every write is preceded by a `respira_get_snapshot`, and the existing draft-duplicate path is kept. After the first `respira_inject_builder_content`, validation issues (collapsed column widths from the row/column-to-container translation, broken parent refs, a misconverted module) are corrected surgically with `respira_find_element` + `respira_update_element` (and `respira_batch_update` for multi-element or multi-page fixes) instead of re-injecting whole pages. Snapshot restore and draft deletion are now explicit rollback paths. Reflects the current 16 supported builders.
+
+Full-site migration from Beaver Builder to Bricks Builder. Audits every Beaver Builder page, maps modules to their Bricks equivalents, builds a migration plan for approval, and executes page-by-page conversion into Bricks' JSON format — all through duplicates so your live site stays untouched. Use this skill whenever someone mentions migrating from Beaver Builder to Bricks, switching from BB to Bricks, converting Beaver Builder pages to Bricks, or replacing Beaver Builder with Bricks.
+
+## What This Skill Does
+
+Beaver Builder and Bricks are both visual page builders, but they differ significantly in architecture. Beaver Builder uses a module-based system with rows, columns, and modules stored in `_fl_builder_data`. Bricks uses a more modern, flexbox-first approach with sections, containers, and elements stored as a JSON array in `_bricks_page_content_2`. The migration requires translating BB's row/column grid into Bricks' container model and mapping each module to its Bricks element equivalent.
+
+This skill reads every Beaver Builder page, extracts the module structure, translates each row/column/module to its Bricks equivalent, and writes the result to duplicate pages in Bricks format — giving you a complete parallel version of your site to review before going live.
+
+**Handles:**
+- Row → Bricks Section mapping
+- Column structures → Bricks Container with flex layout
+- Text Editor module → Bricks Text / Heading elements
+- Photo module → Bricks Image element
+- Button module → Bricks Button element
+- Video module → Bricks Video element
+- HTML module → Bricks Code element
+- Heading module → Bricks Heading element
+- Separator module → Bricks Divider element
+- Icon module → Bricks Icon element
+- Call to Action module → Bricks Container + child elements
+- Custom CSS classes and inline styles
+
+## What This Skill Does NOT Do
+
+- Migrate Beaver Builder's saved rows/modules library — these must be recreated in Bricks
+- Convert Beaver Themer layouts (headers, footers, archives) — Bricks templates must be built separately
+- Replicate exact Beaver Builder animations/effects — Bricks has its own interaction system
+- Migrate third-party Beaver Builder add-on modules (PowerPack, UABB, etc.) — flagged for manual handling
+- Convert BB's global rows to Bricks' template system — different architectural concept
+- Guarantee pixel-perfect visual parity — different rendering engines produce different output
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected
+- MCP connection active (desktop or WebMCP)
+- Beaver Builder active on the source site
+- Bricks Builder installed on the target site (can be the same site)
+- Read access to scan Beaver Builder content
+- Write access to create duplicates with Bricks content
+
+## Trigger Phrase
+
+- "migrate beaver builder to bricks"
+
+## Alternative Triggers
+
+- "convert beaver builder to bricks"
+- "switch from bb to bricks"
+- "move beaver builder pages to bricks"
+- "replace beaver builder with bricks"
+- "beaver builder to bricks migration"
+- "migrate bb to bricks"
+
+## Builder Technical Context
+
+**Source: Beaver Builder**
+- Content stored in post_meta keys `_fl_builder_data` and `_fl_builder_data_settings`
+- Module-based structure with rows → columns → modules hierarchy
+- Read via `respira_extract_builder_content` with `builder=beaver` or `builder=beaver-builder`
+- Module types: `rich-text`, `photo`, `button`, `heading`, `html`, `video`, `icon`, `separator`, `callout`, `cta`, `numbers`, `content-slider`, etc.
+
+**Target: Bricks Builder**
+- Content stored in post_meta key `_bricks_page_content_2` as a JSON array
+- Each element is an object with `id`, `name`, `parent`, `settings`, `children`
+- Write via `respira_inject_builder_content` with `builder=bricks`
+- Elements: `section`, `container`, `heading`, `text`, `image`, `button`, `video`, `code`, `divider`, `icon`, etc.
+
+## Execution Workflow
+
+### Phase 1: Pre-Migration Audit
+
+1. Verify Respira + MCP connection via `respira_get_site_context`. If unavailable, stop and show setup guidance.
+2. Detect Beaver Builder presence via `respira_get_builder_info` or `respira_list_plugins`.
+3. Inventory and scope the source pages first:
+   - `respira_find_builder_targets` with `builder=beaver` — a fast, ranked list of every BB-managed page/post before you touch anything
+   - Fall back to `respira_list_pages` / `respira_list_posts` + `respira_get_builder_info` to confirm builder per item where needed
+4. For each BB page, extract content:
+   - `respira_extract_builder_content` with `builder=beaver`
+   - Catalog: module types used, row/column structures, custom CSS, third-party modules, saved rows/modules
+5. Produce an **Audit Report**:
+   - Total pages/posts using Beaver Builder
+   - Module type frequency (how many text editors, photos, buttons, etc.)
+   - Column layout patterns (common row structures)
+   - Complexity flags (third-party modules, Beaver Themer, custom CSS, animations)
+   - Estimated migration difficulty per page (simple / moderate / complex)
+
+### Phase 2: Migration Plan
+
+Present a structured migration plan:
+
+```
+## Beaver Builder → Bricks Migration Plan
+
+### Site Overview
+- Total Beaver Builder pages: X
+- Simple pages (direct mapping): X
+- Moderate pages (some manual review needed): X
+- Complex pages (significant manual work): X
+
+### Module-to-Element Mapping
+| BB Module | Bricks Element | Notes |
+|---|---|---|
+| Row | Section | BB row maps to Bricks section |
+| Column | Container | Flex-based layout in Bricks |
+| Text Editor | Text / Heading | Content parsed into elements |
+| Photo | Image | Direct mapping |
+| Button | Button | Direct mapping |
+| ... | ... | ... |
+
+### Migration Order
+1. [Page Title] — Simple — estimated 2 min
+2. [Page Title] — Moderate — estimated 5 min
+...
+
+### Items Requiring Manual Attention
+- [Page X] — PowerPack Tabs module (no direct Bricks equivalent)
+- [Page Y] — Content slider (needs Bricks slider setup)
+- Beaver Themer layouts — must be rebuilt as Bricks templates
+```
+
+Then ask:
+
+> Here's the migration plan. Would you like me to:
+> 1. Migrate all pages (creates duplicates for review)
+> 2. Migrate only simple pages first
+> 3. Migrate specific pages you choose
+> 4. Just keep this as a reference — no changes
+
+Wait for explicit confirmation before proceeding.
+
+### Phase 3: Page-by-Page Migration
+
+For each approved page:
+
+1. Extract Beaver Builder content via `respira_extract_builder_content` with `builder=beaver`
+2. Map the row/column/module hierarchy to Bricks elements:
+   - Rows → Bricks `section` elements
+   - Columns → Bricks `container` elements with flex layout settings
+   - Text Editor → Parse into `text` and `heading` elements
+   - Photo → `image` element with src, alt, caption
+   - Button → `button` element with text, link, style
+   - HTML → `code` element
+   - Map CSS classes and inline styles to Bricks settings
+   - Preserve text content, image URLs, link targets
+   - Flag any unmappable modules with comment annotations
+3. Build the Bricks JSON array structure
+4. Create a duplicate via `respira_create_page_duplicate` or `respira_create_post_duplicate`
+5. Before writing, take a snapshot with `respira_get_snapshot` so the duplicate's pre-write state can be restored if anything goes wrong
+6. Inject Bricks content via `respira_inject_builder_content` with `builder=bricks`
+7. Surgical fix pass — if the injected page has validation issues (column widths that collapsed during the row/column-to-container translation, broken parent refs, a misconverted module), do not re-inject the whole page. Locate the specific element with `respira_find_element` and correct it with `respira_update_element`. For repeated fixes across many elements or several pages, batch them with `respira_batch_update`
+8. Log the migration result (success, warnings, manual review items)
+
+### Phase 4: Post-Migration Verification
+
+1. Summarize all migrated pages with status:
+   - Clean migrations (no issues)
+   - Migrations with warnings (flagged items needing review)
+   - Failed migrations (if any)
+2. List all manual review items:
+   - Third-party modules that need manual replacement
+   - Content sliders or advanced layouts needing Bricks-native rebuilds
+   - Custom CSS that needs to be added to Bricks element styles
+   - Beaver Themer layouts that need separate rebuilding in Bricks
+3. Provide review instructions:
+   - Where to find duplicates in WordPress admin
+   - How to preview Bricks pages
+   - How to delete duplicates if not wanted
+
+## Safety Model
+
+- Read-only analysis first — full Beaver Builder content audit before any changes
+- Explicit user confirmation before creating any duplicates
+- Duplicate-first only — never modifies live/published Beaver Builder content
+- Never auto-publishes duplicates
+- Snapshot before every write — `respira_get_snapshot` captures the duplicate's pre-write state, and `respira_restore_snapshot` rolls it back if an injection goes wrong
+- Two explicit rollback paths: restore the snapshot to revert a bad write, or delete the draft duplicates entirely to undo the migration
+- Preserves all original Beaver Builder content untouched
+
+## Honest Disclaimer
+
+This skill converts Beaver Builder page structures to Bricks format and creates duplicates for review.
+
+It cannot:
+- Guarantee pixel-perfect visual parity between builders
+- Migrate Beaver Themer layouts automatically
+- Convert third-party BB add-on modules to Bricks equivalents
+- Replicate BB animations in Bricks interactions
+- Replace a thorough manual QA pass on every page
+
+It can:
+- Map 75-85% of standard Beaver Builder modules to Bricks elements
+- Translate row/column grids to Bricks' modern flexbox containers
+- Preserve content, images, links, and layout structure
+- Move you to a more modern builder architecture
+- Save days of manual rebuild work
+- Identify exactly what needs manual attention
+
+## Tooling
+
+**Core WordPress tools**
+- `respira_get_site_context`
+- `respira_get_builder_info`
+- `respira_list_pages`
+- `respira_list_posts`
+- `respira_list_plugins`
+- `respira_find_builder_targets`
+- `respira_extract_builder_content`
+- `respira_inject_builder_content`
+- `respira_create_page_duplicate`
+- `respira_create_post_duplicate`
+- `respira_read_page`
+- `respira_read_post`
+
+**Safety and surgical-fix tools**
+- `respira_get_snapshot`
+- `respira_restore_snapshot`
+- `respira_find_element`
+- `respira_update_element`
+- `respira_batch_update`
+
+## Telemetry
+
+After run completion, send fire-and-forget usage tracking to:
+
+- `POST https://www.respira.press/api/skills/track-usage`
+
+Include:
+- `skill_slug = migrate-beaver-builder-to-bricks`
+- site/version context
+- duration and success
+- pages audited, pages migrated, warnings count
+- tools used
+
+Never block user flow on telemetry failure.
+
+## Related Skills
+
+- WordPress Site DNA (understand site structure before migrating)
+- Technical Debt Audit (clean up before or after migration)
+- SEO & AEO Amplifier (verify SEO preservation post-migration)
+
+---
+
+Built by Respira Team
+https://respira.press/skills/migrate-beaver-builder-to-bricks

package/skills/migrate-beaver-builder-to-gutenberg/SKILL.md

@@ -0,0 +1,248 @@
+# Migrate Beaver Builder to Gutenberg
+
+**Version:** 2.0.0
+**Updated:** 2026-06-30
+**Freshly updated:** v2.0.0 wires in current Respira safety and precision. Pre-migration now inventories source pages with `respira_find_builder_targets`. Every write is preceded by a `respira_get_snapshot`, and the existing draft-duplicate path is kept. After the initial block-markup write (`respira_update_page` / `respira_update_post`), validation issues (collapsed column widths, malformed block markup, a misconverted module) are corrected surgically with `respira_find_element` + `respira_update_element` (and `respira_batch_update` for multi-block or multi-page fixes) instead of rewriting whole pages. Snapshot restore and draft deletion are now explicit rollback paths. Reflects the current 16 supported builders.
+
+Full-site migration from Beaver Builder to the WordPress block editor (Gutenberg). Audits every Beaver Builder page, maps modules to their Gutenberg block equivalents, builds a migration plan for approval, and executes page-by-page conversion into native block markup — all through duplicates so your live site stays untouched. Use this skill whenever someone mentions migrating from Beaver Builder to Gutenberg, switching from Beaver Builder to blocks, converting Beaver Builder pages to the block editor, or moving away from Beaver Builder to native WordPress.
+
+## What This Skill Does
+
+Beaver Builder uses a module-based architecture with rows, columns, and modules stored in `_fl_builder_data` and `_fl_builder_data_settings`. Gutenberg uses a flat block structure in `post_content` with HTML comments as block delimiters. The architectural gap is moderate — Beaver Builder's row/column grid must be translated to Gutenberg's Group, Columns, and Column blocks, while individual modules map to core blocks.
+
+This skill reads every Beaver Builder page, extracts the module structure, translates each row/column/module to its Gutenberg block equivalent, and writes the result to duplicate pages in native block markup — giving you a complete parallel version of your site to review before going live.
+
+**Handles:**
+- Row → Group block mapping
+- Column layouts → Columns/Column block mapping
+- Text Editor module → Paragraph/Heading blocks
+- Photo module → Image block
+- Button module → Buttons/Button block
+- Video module → Video/Embed block
+- HTML module → Custom HTML block
+- Heading module → Heading block
+- Icon/Icon Group modules → basic equivalents
+- Separator module → Separator block
+- Content slider → basic markup (flagged for enhancement)
+- Call to Action module → Group + Heading + Paragraph + Button blocks
+
+## What This Skill Does NOT Do
+
+- Migrate Beaver Builder's saved rows/modules library — these are separate entities
+- Convert Beaver Themer layouts (headers, footers, archives, parts) — these must be rebuilt as block template parts or theme templates
+- Replicate exact Beaver Builder animations/effects — Gutenberg has limited animation support
+- Migrate advanced modules from third-party Beaver Builder add-ons (PowerPack, UABB, etc.) — flagged for manual handling
+- Preserve exact column width percentages in all cases — Gutenberg columns have different width constraints
+- Guarantee pixel-perfect visual parity — the block editor renders differently than Beaver Builder
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected
+- MCP connection active (desktop or WebMCP)
+- Beaver Builder active on the source site
+- Read access to scan Beaver Builder content
+- Write access to create duplicates with Gutenberg content
+
+## Trigger Phrase
+
+- "migrate beaver builder to gutenberg"
+
+## Alternative Triggers
+
+- "convert beaver builder to blocks"
+- "switch from beaver builder to gutenberg"
+- "move beaver builder to block editor"
+- "replace beaver builder with gutenberg"
+- "beaver builder to wordpress blocks"
+- "migrate bb to gutenberg"
+
+## Builder Technical Context
+
+**Source: Beaver Builder**
+- Content stored in post_meta keys `_fl_builder_data` and `_fl_builder_data_settings`
+- Module-based structure with rows → columns → modules hierarchy
+- Read via `respira_extract_builder_content` with `builder=beaver` or `builder=beaver-builder`
+- Module types: `rich-text`, `photo`, `button`, `heading`, `html`, `video`, `icon`, `separator`, `callout`, `cta`, `numbers`, `content-slider`, etc.
+
+**Target: Gutenberg (Block Editor)**
+- Content stored in `post_content` as HTML with block comment delimiters
+- Format: `<!-- wp:paragraph --><p>Text</p><!-- /wp:paragraph -->`
+- Write via standard WordPress content tools (`respira_update_page` / `respira_update_post`)
+- Core blocks: `paragraph`, `heading`, `image`, `buttons`, `columns`, `group`, `html`, `video`, `separator`, `embed`, etc.
+
+## Execution Workflow
+
+### Phase 1: Pre-Migration Audit
+
+1. Verify Respira + MCP connection via `respira_get_site_context`. If unavailable, stop and show setup guidance.
+2. Detect Beaver Builder presence via `respira_get_builder_info` or `respira_list_plugins`.
+3. Inventory and scope the source pages first:
+   - `respira_find_builder_targets` with `builder=beaver` — a fast, ranked list of every BB-managed page/post before you touch anything
+   - Fall back to `respira_list_pages` / `respira_list_posts` + `respira_get_builder_info` to confirm builder per item where needed
+4. For each BB page, extract content:
+   - `respira_extract_builder_content` with `builder=beaver`
+   - Catalog: module types used, row/column structures, custom CSS, third-party modules, saved rows/modules referenced
+5. Produce an **Audit Report**:
+   - Total pages/posts using Beaver Builder
+   - Module type frequency (how many text editors, photos, buttons, etc.)
+   - Column layout patterns (common row structures)
+   - Complexity flags (third-party modules, Beaver Themer, custom CSS, animations)
+   - Estimated migration difficulty per page (simple / moderate / complex)
+
+### Phase 2: Migration Plan
+
+Present a structured migration plan:
+
+```
+## Beaver Builder → Gutenberg Migration Plan
+
+### Site Overview
+- Total Beaver Builder pages: X
+- Simple pages (direct mapping): X
+- Moderate pages (some manual review needed): X
+- Complex pages (significant manual work): X
+
+### Module Mapping
+| BB Module | Gutenberg Block | Notes |
+|---|---|---|
+| Text Editor | Paragraph / Heading | Content parsed into appropriate blocks |
+| Photo | Image | Direct mapping |
+| Button | Buttons > Button | Wrapped in Buttons container |
+| Row (2 col) | Columns (2 col) | Width ratios preserved where possible |
+| ... | ... | ... |
+
+### Migration Order
+1. [Page Title] — Simple — estimated 2 min
+2. [Page Title] — Moderate — estimated 5 min
+...
+
+### Items Requiring Manual Attention
+- [Page X] — PowerPack module (no core block equivalent)
+- [Page Y] — Content slider (basic fallback only)
+- Beaver Themer layouts — must be rebuilt as block templates
+```
+
+Then ask:
+
+> Here's the migration plan. Would you like me to:
+> 1. Migrate all pages (creates duplicates for review)
+> 2. Migrate only simple pages first
+> 3. Migrate specific pages you choose
+> 4. Just keep this as a reference — no changes
+
+Wait for explicit confirmation before proceeding.
+
+### Phase 3: Page-by-Page Migration
+
+For each approved page:
+
+1. Extract Beaver Builder content via `respira_extract_builder_content` with `builder=beaver`
+2. Map the row/column/module hierarchy to Gutenberg blocks:
+   - Rows → `<!-- wp:group -->` blocks
+   - Columns → `<!-- wp:columns -->` with `<!-- wp:column -->` children
+   - Text Editor → Parse rich text into `<!-- wp:paragraph -->` and `<!-- wp:heading -->` blocks
+   - Photo → `<!-- wp:image -->` with src, alt, caption
+   - Button → `<!-- wp:buttons -->` wrapper with `<!-- wp:button -->` child
+   - HTML → `<!-- wp:html -->` block
+   - Preserve text content, image URLs, link targets, heading levels
+   - Flag any unmappable modules with `<!-- wp:paragraph --><p>[MIGRATION NOTE: ...]</p><!-- /wp:paragraph -->`
+3. Assemble the complete Gutenberg block markup
+4. Create a duplicate via `respira_create_page_duplicate` or `respira_create_post_duplicate`
+5. Before writing, take a snapshot with `respira_get_snapshot` so the duplicate's pre-write state can be restored if anything goes wrong
+6. Update the duplicate's `post_content` with the Gutenberg markup via `respira_update_page` or `respira_update_post`
+7. Surgical fix pass — if the written page has validation issues (collapsed column widths, malformed block markup, a misconverted module), do not rewrite the whole page. Locate the specific block with `respira_find_element` and correct it with `respira_update_element`. For repeated fixes across many blocks or several pages, batch them with `respira_batch_update`
+8. Log the migration result (success, warnings, manual review items)
+
+### Phase 4: Post-Migration Verification
+
+1. Summarize all migrated pages with status:
+   - Clean migrations (no issues)
+   - Migrations with warnings (flagged items needing review)
+   - Failed migrations (if any)
+2. List all manual review items:
+   - Third-party modules that need manual replacement
+   - Content sliders or advanced layouts that need enhancement
+   - Custom CSS that needs to be moved to theme/Additional CSS
+   - Beaver Themer layouts that need separate rebuilding
+3. Provide review instructions:
+   - Where to find duplicates in WordPress admin
+   - How to preview pages in the block editor
+   - How to delete duplicates if not wanted
+
+## Safety Model
+
+- Read-only analysis first — full Beaver Builder content audit before any changes
+- Explicit user confirmation before creating any duplicates
+- Duplicate-first only — never modifies live/published Beaver Builder content
+- Never auto-publishes duplicates
+- Snapshot before every write — `respira_get_snapshot` captures the duplicate's pre-write state, and `respira_restore_snapshot` rolls it back if a write goes wrong
+- Two explicit rollback paths: restore the snapshot to revert a bad write, or delete the draft duplicates entirely to undo the migration
+- Preserves all original Beaver Builder content untouched
+
+## Honest Disclaimer
+
+This skill converts Beaver Builder page structures to Gutenberg block markup and creates duplicates for review.
+
+It cannot:
+- Guarantee pixel-perfect visual parity between builders
+- Migrate Beaver Themer layouts automatically
+- Convert third-party BB add-on modules
+- Replicate animations or advanced effects
+- Replace a thorough manual QA pass on every page
+
+It can:
+- Map 70-85% of standard Beaver Builder modules to core Gutenberg blocks
+- Preserve content, images, links, and basic layout structure
+- Move you off a third-party builder dependency to native WordPress
+- Save days of manual rebuild work
+- Identify exactly what needs manual attention
+
+## Tooling
+
+**Core WordPress tools**
+- `respira_get_site_context`
+- `respira_get_builder_info`
+- `respira_list_pages`
+- `respira_list_posts`
+- `respira_list_plugins`
+- `respira_find_builder_targets`
+- `respira_extract_builder_content`
+- `respira_create_page_duplicate`
+- `respira_create_post_duplicate`
+- `respira_update_page`
+- `respira_update_post`
+- `respira_read_page`
+- `respira_read_post`
+
+**Safety and surgical-fix tools**
+- `respira_get_snapshot`
+- `respira_restore_snapshot`
+- `respira_find_element`
+- `respira_update_element`
+- `respira_batch_update`
+
+## Telemetry
+
+After run completion, send fire-and-forget usage tracking to:
+
+- `POST https://www.respira.press/api/skills/track-usage`
+
+Include:
+- `skill_slug = migrate-beaver-builder-to-gutenberg`
+- site/version context
+- duration and success
+- pages audited, pages migrated, warnings count
+- tools used
+
+Never block user flow on telemetry failure.
+
+## Related Skills
+
+- WordPress Site DNA (understand site structure before migrating)
+- Technical Debt Audit (clean up before or after migration)
+- SEO & AEO Amplifier (verify SEO preservation post-migration)
+
+---
+
+Built by Respira Team
+https://respira.press/skills/migrate-beaver-builder-to-gutenberg