@respira/wordpress-mcp-server 7.3.0 → 7.4.0

package/skills/migrate-brizy-to-gutenberg/SKILL.md

@@ -0,0 +1,248 @@
+# Migrate Brizy to Gutenberg
+
+**Version:** 2.0.0
+**Updated:** 2026-06-30
+**Freshly updated:** v2.0.0 weaves in the current Respira safety and precision flow — `respira_find_builder_targets` to inventory and scope source pages up front, a `respira_get_snapshot` checkpoint before any write, and surgical fixes via `respira_find_element` + `respira_update_element` (and `respira_batch_update` for multi-element or multi-page corrections) instead of rewriting whole pages. Rollback is now explicit (restore the snapshot, delete the draft duplicates). Reflects the current 16 supported builders.
+
+Full-site migration from Brizy Builder to the WordPress block editor (Gutenberg). Audits every Brizy-built page, maps components 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 Brizy to Gutenberg, switching from Brizy to blocks, converting Brizy pages to the block editor, or moving away from Brizy to native WordPress.
+
+## What This Skill Does
+
+Brizy uses a proprietary content format with its own component system, storing data in `brizy_post_uid` and related custom meta fields. Gutenberg uses a flat block structure in `post_content` with HTML comment delimiters. The migration requires extracting Brizy's custom format, identifying each component type, and translating it to equivalent core Gutenberg blocks.
+
+This skill reads every Brizy page, extracts the builder content, translates each component 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:**
+- Section → Group block mapping
+- Row/Column → Columns/Column block mapping
+- Text components → Paragraph/Heading blocks
+- Image components → Image block
+- Button components → Buttons/Button block
+- Video components → Video/Embed block
+- Icon components → basic equivalents
+- Spacer/Divider → Spacer/Separator blocks
+- Map component → basic embed fallback
+- Form elements → flagged for manual handling (Contact Form 7 or similar)
+- Custom HTML/embed content
+
+## What This Skill Does NOT Do
+
+- Migrate Brizy's global styling system — must be recreated in theme settings or Global Styles
+- Convert Brizy popup designs — Gutenberg has no native popup system
+- Replicate Brizy's built-in form submissions — a separate form plugin is needed
+- Migrate Brizy Cloud templates or synced content
+- Convert Brizy Pro dynamic content features — flagged for manual handling
+- Preserve Brizy's hover effects and animations — Gutenberg has limited animation support
+- Guarantee pixel-perfect visual parity — different rendering approaches
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected
+- MCP connection active (desktop or WebMCP)
+- Brizy Builder active on the source site
+- Read access to scan Brizy content
+- Write access to create duplicates with Gutenberg content
+
+## Trigger Phrase
+
+- "migrate brizy to gutenberg"
+
+## Alternative Triggers
+
+- "convert brizy to blocks"
+- "switch from brizy to gutenberg"
+- "move brizy to block editor"
+- "replace brizy with gutenberg"
+- "brizy to wordpress blocks"
+- "migrate brizy to native wordpress"
+
+## Builder Technical Context
+
+**Source: Brizy**
+- Content stored in post_meta key `brizy_post_uid` and Brizy's custom format
+- Proprietary component structure with sections, rows, columns, and elements
+- Read via `respira_extract_builder_content` with `builder=brizy`
+- Components: sections, rows, columns, text, image, button, video, icon, spacer, map, form, embed, 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`, `spacer`, `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 Brizy presence via `respira_get_builder_info` or `respira_list_plugins`.
+3. Inventory all Brizy-built content:
+   - `respira_list_pages` and `respira_list_posts` — identify all content
+   - `respira_find_builder_targets` with `builder=brizy` — find Brizy-managed pages
+4. For each Brizy page, extract content:
+   - `respira_extract_builder_content` with `builder=brizy`
+   - Catalog: component types used, nesting depth, popups, forms, dynamic content usage
+5. Produce an **Audit Report**:
+   - Total pages/posts using Brizy
+   - Component type frequency (how many sections, text blocks, images, etc.)
+   - Complexity flags (popups, forms, dynamic content, Brizy Pro features)
+   - Estimated migration difficulty per page (simple / moderate / complex)
+
+### Phase 2: Migration Plan
+
+Present a structured migration plan:
+
+```
+## Brizy → Gutenberg Migration Plan
+
+### Site Overview
+- Total Brizy pages: X
+- Simple pages (direct mapping): X
+- Moderate pages (some manual review needed): X
+- Complex pages (significant manual work): X
+
+### Component Mapping
+| Brizy Component | Gutenberg Block | Notes |
+|---|---|---|
+| Section | Group | Container mapping |
+| Row / Columns | Columns / Column | Layout structure |
+| Text | Paragraph / Heading | Content parsed into blocks |
+| Image | Image | Direct mapping |
+| Button | Buttons > Button | Wrapped in container |
+| ... | ... | ... |
+
+### Migration Order
+1. [Page Title] — Simple — estimated 2 min
+2. [Page Title] — Moderate — estimated 5 min
+...
+
+### Items Requiring Manual Attention
+- [Page X] — Brizy popup (no Gutenberg equivalent)
+- [Page Y] — Brizy form (needs form plugin replacement)
+- Global styles — must be configured in theme settings
+```
+
+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 Brizy content via `respira_extract_builder_content` with `builder=brizy`
+2. Map each Brizy component to Gutenberg blocks:
+   - Sections → `<!-- wp:group -->` blocks
+   - Rows/Columns → `<!-- wp:columns -->` with `<!-- wp:column -->` children
+   - Text → Parse into `<!-- wp:paragraph -->` and `<!-- wp:heading -->` blocks
+   - Image → `<!-- wp:image -->` with src, alt, caption
+   - Button → `<!-- wp:buttons -->` wrapper with `<!-- wp:button -->` child
+   - Video → `<!-- wp:video -->` or `<!-- wp:embed -->` block
+   - Spacer → `<!-- wp:spacer -->` block
+   - Custom HTML → `<!-- wp:html -->` block
+   - Preserve text content, image URLs, link targets
+   - Flag unmappable components with `<!-- wp:paragraph --><p>[MIGRATION NOTE: ...]</p><!-- /wp:paragraph -->`
+3. Assemble the complete Gutenberg block markup
+4. Take a `respira_get_snapshot` checkpoint of the target before any write, so the page can be restored exactly if the conversion needs unwinding
+5. Create a duplicate via `respira_create_page_duplicate` or `respira_create_post_duplicate`
+6. Write the Gutenberg markup into the duplicate's `post_content` via `respira_update_page` or `respira_update_post`
+7. Surgical fixes (not a rewrite): when a single block lands wrong — a heading, a button label, a spacing value — locate it with `respira_find_element` and correct it in place with `respira_update_element`. For repeated corrections across many blocks or several migrated pages, batch them with `respira_batch_update` rather than regenerating and re-writing whole pages.
+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:
+   - Popups that need a separate popup plugin solution
+   - Forms that need a WordPress form plugin (Contact Form 7, WPForms, etc.)
+   - Dynamic content that needs reconnecting
+   - Brizy Pro features that have no Gutenberg equivalent
+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 Brizy content audit before any changes
+- Explicit user confirmation before creating any duplicates
+- Snapshot before every write — `respira_get_snapshot` captures the target so it can be returned to its exact prior state
+- Duplicate-first only — never modifies live/published Brizy content
+- Never auto-publishes duplicates
+- Explicit rollback path — restore the snapshot via `respira_restore_snapshot`, or delete the draft duplicates, to undo a migration cleanly
+- Preserves all original Brizy content untouched
+
+## Honest Disclaimer
+
+This skill converts Brizy page structures to Gutenberg block markup and creates duplicates for review.
+
+It cannot:
+- Guarantee pixel-perfect visual parity between builders
+- Migrate Brizy popups or forms automatically
+- Convert Brizy Pro dynamic content features
+- Replicate hover effects or animations
+- Replace a thorough manual QA pass on every page
+
+It can:
+- Map 65-80% of standard Brizy components 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_get_snapshot`
+- `respira_restore_snapshot`
+- `respira_find_element`
+- `respira_update_element`
+- `respira_batch_update`
+- `respira_create_page_duplicate`
+- `respira_create_post_duplicate`
+- `respira_update_page`
+- `respira_update_post`
+- `respira_read_page`
+- `respira_read_post`
+
+## Telemetry
+
+After run completion, send fire-and-forget usage tracking to:
+
+- `POST https://www.respira.press/api/skills/track-usage`
+
+Include:
+- `skill_slug = migrate-brizy-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-brizy-to-gutenberg

package/skills/migrate-divi-to-breakdance/SKILL.md

@@ -0,0 +1,312 @@
+# Migrate Divi to Breakdance
+
+**Version:** 2.0.0
+**Updated:** 2026-06-30
+**Freshly updated:** v2.0.0 weaves in the current Respira safety and precision flow — `respira_find_builder_targets` to inventory and scope the Divi source pages up front, a `respira_get_snapshot` checkpoint before any write, and surgical fixes via `respira_find_element` + `respira_update_element` (and `respira_batch_update` for multi-element or multi-page corrections) instead of re-injecting whole pages. Rollback is now explicit (restore the snapshot, delete the draft duplicates). Reflects the current 16 supported builders.
+
+Converts Divi-built WordPress pages to Breakdance Builder. Parses Divi's shortcode-based content from post_content, maps each module to its Breakdance element equivalent, generates a migration plan for approval, and writes Breakdance content to the target pages. Use this skill whenever someone wants to move from Divi to Breakdance, switch builders from Divi to Breakdance, or rebuild Divi pages in Breakdance.
+
+## What This Skill Does
+
+Divi and Breakdance take very different approaches to content storage — Divi uses nested shortcodes in `post_content`, while Breakdance uses a structured format in post meta. This skill bridges that gap by parsing the full Divi shortcode tree, understanding each module's intent, and recreating it as the appropriate Breakdance element. Breakdance was built by the Oxygen team with a focus on clean output and intuitive editing, making it a popular Divi replacement for users who want better performance without a steep learning curve.
+
+**Handles:**
+- et_pb_section → Breakdance Section element
+- et_pb_row/et_pb_column → Breakdance Div elements with flex layout
+- et_pb_text → Breakdance Text element
+- et_pb_blurb → Breakdance Icon Box or container with children
+- et_pb_image → Breakdance Image element
+- et_pb_button → Breakdance Button element
+- et_pb_video → Breakdance Video element
+- et_pb_divider → Breakdance Separator element
+- et_pb_accordion/et_pb_toggle → Breakdance Accordion element
+- et_pb_tabs → Breakdance Tabs element
+- et_pb_gallery → Breakdance Gallery element
+- et_pb_slider → Breakdance Slider element
+- et_pb_pricing_tables → Breakdance Pricing Table element
+- et_pb_code → Breakdance Code element
+- et_pb_counters → Breakdance Progress Bar element
+- et_pb_map → Breakdance Map element
+- Custom CSS → Breakdance custom CSS fields
+- Column widths → Breakdance flex percentages
+
+**Preserves:**
+- All text content and inline formatting
+- Image URLs, alt text, dimensions
+- Typography settings (font, size, weight, line-height)
+- Color values and gradients
+- Spacing (margin, padding)
+- Background images, overlays
+- Border and shadow settings
+- Button labels, URLs, targets
+- CSS classes
+
+## What This Skill Does NOT Do
+
+- **Specialty sections** — Divi's specialty layouts need manual setup in Breakdance.
+- **Global modules** — Divi's `et_pb_layout` global modules are inlined during migration. Breakdance global blocks are separate.
+- **Third-party Divi modules** — Plugins extending Divi are flagged for manual recreation.
+- **Divi theme customizer** — Global design settings from the Divi customizer must be configured in Breakdance's design settings.
+- **Dynamic content** — Divi's dynamic features need Breakdance's dynamic data system.
+- **Contact forms** — et_pb_contact_form must be rebuilt with Breakdance's form element or a forms plugin.
+- **Divi Library** — Layouts in et_pb_layout post type are not migrated automatically.
+- **Motion effects and animations** — Scroll effects differ between builders.
+- **Theme dependency** — If using Divi theme, switching to Breakdance means using a different base theme.
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected
+- MCP connection active (desktop or WebMCP)
+- Divi theme or Divi Builder plugin active (to read source content)
+- Breakdance plugin installed and active (to write target content)
+- Read access to scan Divi content
+- Write access to create duplicates with Breakdance content
+
+## Trigger Phrase
+
+- "migrate divi to breakdance"
+
+## Alternative Triggers
+
+- "convert divi to breakdance"
+- "switch from divi to breakdance"
+- "rebuild divi pages in breakdance"
+- "move from divi to breakdance"
+- "divi to breakdance migration"
+- "replace divi with breakdance"
+
+## Source Builder: Divi
+
+Divi stores content as shortcodes in `post_content`:
+
+```
+[et_pb_section fb_built="1" _builder_version="4.x"]
+  [et_pb_row]
+    [et_pb_column type="4_4"]
+      [et_pb_text]<p>Content</p>[/et_pb_text]
+      [et_pb_image src="photo.jpg" alt="Photo"][/et_pb_image]
+    [/et_pb_column]
+  [/et_pb_row]
+[/et_pb_section]
+```
+
+Key Divi specifics:
+- **Hierarchy**: section → row → column → module (strict nesting)
+- **Column types**: `4_4` (100%), `1_2` (50%), `1_3` (33%), `2_3` (66%), `1_4` (25%), `3_4` (75%)
+- **Settings as attributes**: `background_color`, `custom_margin`, `custom_padding`
+- **Content encoding**: HTML entities, percent-encoding in attribute values
+- **Global modules**: `global_module` attribute referencing `et_pb_layout` post
+- **Section types**: regular, fullwidth, specialty
+
+Read Divi content via `respira_extract_builder_content` with `builder=divi`.
+
+## Target Builder: Breakdance
+
+Breakdance stores content in post meta with a structured element format.
+
+Key Breakdance specifics:
+- Elements use types like `EssentialElements\\Heading`, `EssentialElements\\Text`, `EssentialElements\\Image`
+- Section and Div elements for layout structure
+- Clean CSS output with minimal wrapper markup
+- Built-in form builder, WooCommerce support, popup system
+- Responsive design through breakpoint-specific settings
+- Created by the Oxygen team — combines Oxygen's clean output with friendlier UX
+
+Write Breakdance content via `respira_inject_builder_content` with `builder=breakdance`.
+
+## 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. Confirm Divi is active via `respira_list_plugins` and `respira_get_site_context`.
+3. Confirm Breakdance is installed and active via `respira_list_plugins`.
+4. **Important**: If using Divi theme, note the user needs a compatible base theme for Breakdance.
+5. Scan and scope all Divi content:
+   - `respira_list_pages` and `respira_list_posts` — identify all content
+   - `respira_find_builder_targets` with `builder=divi` — inventory the Divi-managed pages to scope the migration
+   - Confirm the builder per page via `respira_get_builder_info`
+6. Extract Divi content via `respira_extract_builder_content` with `builder=divi`
+7. Build inventory:
+   - Total Divi pages/posts
+   - Module types (frequency count)
+   - Specialty sections detected
+   - Global modules referenced
+   - Third-party modules
+   - Content encoding issues
+   - Complexity per page
+
+### Phase 2: Migration Plan
+
+```
+## Divi → Breakdance Migration Plan
+
+### Theme Note
+[If Divi theme]: Switching from Divi theme. Breakdance works with most
+themes — you'll need a lightweight base theme (Astra, GeneratePress, etc.)
+or Breakdance can handle full site rendering.
+
+### Why Breakdance
+Breakdance produces significantly cleaner CSS and HTML output compared to
+Divi. Built by the Oxygen team, it offers similar power with a more
+intuitive interface. Most Divi modules have direct Breakdance equivalents.
+
+### Site Inventory
+- Total Divi pages: X
+- Total modules to convert: X
+- Auto-convertible: X (Y%)
+- Manual attention: X (Y%)
+
+### Module → Element Mapping
+| Divi Module        | Breakdance Element | Status |
+|-------------------|-------------------|--------|
+| et_pb_text        | Text              | Auto   |
+| et_pb_image       | Image             | Auto   |
+| et_pb_blurb       | Icon Box          | Auto   |
+| et_pb_button      | Button            | Auto   |
+| et_pb_slider      | Slider            | Auto   |
+| et_pb_accordion   | Accordion         | Auto   |
+| et_pb_pricing     | Pricing Table     | Auto   |
+| et_pb_contact     | Form              | Partial|
+| [divi addon]      | —                 | Manual |
+
+### Page-by-Page Plan
+1. **[Page Title]** — X modules, [complexity]
+2. ...
+```
+
+Ask for confirmation:
+> Ready to migrate? Your original Divi pages remain completely untouched.
+> 1. Migrate all pages
+> 2. Migrate specific pages
+> 3. Start with a test page (recommended)
+> 4. Just keep this plan
+
+### Phase 3: Page-by-Page Migration
+
+For each approved page:
+
+1. Read Divi content via `respira_extract_builder_content` with `builder=divi`
+2. Parse the shortcode tree:
+   - Build section → row → column → module hierarchy
+   - Decode encoded content
+   - Resolve global module references
+   - Calculate column widths from type attributes
+3. Generate Breakdance element structure:
+   - `et_pb_section` → Breakdance Section
+   - `et_pb_row` + `et_pb_column` → Breakdance Div elements with flex layout and percentage widths
+   - Map each module to Breakdance element:
+     - `et_pb_text` → Text element (preserve HTML content)
+     - `et_pb_blurb` → Icon Box element (map icon, title, body)
+     - `et_pb_image` → Image element (map src, alt)
+     - `et_pb_button` → Button element (map text, URL, style)
+     - `et_pb_accordion` → Accordion element (map items)
+     - `et_pb_tabs` → Tabs element (map tab titles and content)
+   - Map colors, spacing, typography to Breakdance settings
+   - Flag unmappable modules
+4. Take a `respira_get_snapshot` checkpoint of the target before any write, so the page can be restored exactly if the conversion needs unwinding
+5. Create duplicate via `respira_create_page_duplicate` or `respira_create_post_duplicate`
+6. Write Breakdance content to the duplicate via `respira_inject_builder_content` with `builder=breakdance`
+7. Surgical fixes (not a re-inject): when a single element lands wrong — a heading, a button label, a spacing value — locate it with `respira_find_element` and correct it in place with `respira_update_element`. For repeated corrections across many elements or several migrated pages, batch them with `respira_batch_update` rather than re-injecting whole pages.
+8. Report status
+
+### Phase 4: Post-Migration Verification
+
+1. Summarize migrations:
+   - Pages migrated, elements created, items flagged
+2. For each migrated page:
+   - Link to Breakdance editor
+   - Flagged items list
+   - Layout and encoding notes
+3. Post-migration checklist:
+   - [ ] Open each duplicate in Breakdance editor
+   - [ ] Verify section and layout structure
+   - [ ] Check responsive views
+   - [ ] Verify images and media
+   - [ ] Test links and buttons
+   - [ ] Recreate flagged modules
+   - [ ] Rebuild forms with Breakdance form element
+   - [ ] Set up global templates (header/footer) in Breakdance
+   - [ ] Review Breakdance's clean CSS output
+   - [ ] Compare with Divi original
+   - [ ] Check for Divi shortcode remnants
+
+## Safety Model
+
+- Read-only analysis first — full content scan before any changes
+- Explicit user confirmation required before creating duplicates
+- Original Divi pages are never modified or deleted
+- All migrated content goes to draft duplicates only
+- Never auto-publishes migrated pages
+- Takes a `respira_get_snapshot` checkpoint before each write
+- Explicit rollback: restore the snapshot via `respira_restore_snapshot`, or delete the draft duplicates if they are not wanted
+- Warns about theme implications if using Divi theme
+
+## Honest Disclaimer
+
+This skill converts Divi page content to Breakdance format and creates draft duplicates for review.
+
+It cannot:
+- Migrate specialty section layouts perfectly
+- Convert global modules to Breakdance global blocks automatically
+- Handle third-party Divi plugin modules
+- Transfer Divi theme customizer settings
+- Migrate popups, dynamic content, or animations
+- Guarantee pixel-perfect visual fidelity from shortcodes
+
+It can:
+- Parse Divi's complex shortcode hierarchies including encoded content
+- Convert 80-90% of standard Divi modules to Breakdance elements
+- Produce cleaner CSS and HTML output than Divi
+- Preserve all text, images, links, and core styling
+- Save significant manual rebuilding time
+- Clearly flag everything needing manual work
+- Keep original pages completely safe
+
+## Tooling
+
+**Core WordPress tools**
+- `respira_get_site_context`
+- `respira_list_plugins`
+- `respira_list_pages`
+- `respira_list_posts`
+- `respira_read_page`
+- `respira_read_post`
+- `respira_get_builder_info`
+- `respira_extract_builder_content`
+- `respira_inject_builder_content`
+- `respira_find_builder_targets`
+- `respira_create_page_duplicate`
+- `respira_create_post_duplicate`
+- `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-divi-to-breakdance`
+- site/version context
+- duration and success
+- pages migrated, elements created, modules flagged counts
+- tools used
+
+Never block user flow on telemetry failure.
+
+## Related Skills
+
+- WordPress Site DNA (understand site structure and theme before migrating)
+- Internal Link Builder (verify internal links post-migration)
+- SEO & AEO Amplifier (verify SEO preservation post-migration)
+- Technical Debt Audit (find Divi shortcode remnants post-migration)
+
+---
+
+Built by Respira Team
+https://respira.press/skills/migrate-divi-to-breakdance