@respira/wordpress-mcp-server 7.3.0 → 7.4.1

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

@@ -0,0 +1,321 @@
+# Migrate Divi to Bricks
+
+**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 Bricks Builder. Parses Divi's shortcode-based content from post_content, maps each module to its Bricks element equivalent, generates a migration plan for approval, and writes clean Bricks JSON to the target pages. Use this skill whenever someone wants to move from Divi to Bricks, replace the Divi Builder with Bricks, or rebuild Divi pages in Bricks.
+
+## What This Skill Does
+
+This is a cross-format migration — Divi stores content as nested shortcodes in `post_content`, while Bricks uses a JSON array in `_bricks_page_content_2`. The skill must parse Divi's shortcode hierarchy, understand each module's purpose and settings, then reconstruct that intent as Bricks elements with proper parent-child relationships and settings.
+
+The format gap makes this complex, but both builders are feature-rich visual editors, so most Divi modules have strong Bricks equivalents. The result is cleaner, faster-rendering content in Bricks' modern architecture.
+
+**Handles:**
+- et_pb_section → Bricks Section element
+- et_pb_row/et_pb_column → Bricks Container elements (with flex layout)
+- et_pb_text → Bricks Text Basic element
+- et_pb_blurb → Bricks Icon Box or Container with child elements
+- et_pb_image → Bricks Image element
+- et_pb_button → Bricks Button element
+- et_pb_video → Bricks Video element
+- et_pb_heading (via text modules) → Bricks Heading element
+- et_pb_divider → Bricks Divider element
+- et_pb_accordion/et_pb_toggle → Bricks Accordion element
+- et_pb_tabs → Bricks Tabs element
+- et_pb_gallery → Bricks Gallery element
+- et_pb_slider → Bricks Slider element (close mapping)
+- et_pb_pricing_tables → Bricks Pricing Table element
+- et_pb_code → Bricks Code element
+- et_pb_map → Bricks Map element
+- Custom CSS → Bricks custom CSS fields
+- Column width ratios → Bricks container flex percentages
+
+**Preserves:**
+- All text content and inline HTML formatting
+- Image URLs, alt text, and dimensions
+- Typography settings (font family, size, weight)
+- Color values and gradients
+- Spacing (margin, padding) — converted from Divi's format to Bricks'
+- Background images and overlays
+- Border and shadow settings
+- Button labels, URLs, targets
+- CSS classes
+
+## What This Skill Does NOT Do
+
+- **Specialty sections** — Divi's specialty section layouts (sidebar + content) need manual layout setup in Bricks.
+- **Global modules** — Divi's global modules (`et_pb_layout` post type) are resolved to inline content. Bricks templates must be set up separately.
+- **Third-party Divi modules** — Plugins extending Divi (Divi Toolbox, Divi Supreme, etc.) are flagged for manual recreation.
+- **Divi theme customizer** — Global fonts, colors, and spacing from the Divi theme customizer don't transfer. These need to be set in Bricks theme settings.
+- **Dynamic content** — Divi's dynamic content needs Bricks' dynamic data system configured separately.
+- **Contact forms** — et_pb_contact_form needs to be rebuilt using Bricks' form element or a forms plugin.
+- **Divi Library layouts** — Stored as `et_pb_layout` post type; not auto-migrated to Bricks templates.
+- **Motion effects** — Scroll effects and animations differ between builders.
+- **Divi theme dependency** — If using the Divi theme (not just plugin), you are switching to Bricks theme — a complete theme change.
+
+## 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)
+- Bricks theme installed and active (to write target content)
+- Read access to scan Divi content
+- Write access to create duplicates with Bricks content
+
+## Trigger Phrase
+
+- "migrate divi to bricks"
+
+## Alternative Triggers
+
+- "convert divi to bricks"
+- "switch from divi to bricks"
+- "rebuild divi pages in bricks"
+- "move from divi to bricks"
+- "divi to bricks migration"
+- "replace divi with bricks"
+
+## Source Builder: Divi
+
+Divi stores content as shortcodes in `post_content`. The module structure follows a strict hierarchy:
+
+```
+[et_pb_section fb_built="1" _builder_version="4.x"]
+  [et_pb_row _builder_version="4.x"]
+    [et_pb_column type="4_4" _builder_version="4.x"]
+      [et_pb_text _builder_version="4.x"]
+        <p>Content here</p>
+      [/et_pb_text]
+    [/et_pb_column]
+  [/et_pb_row]
+[/et_pb_section]
+```
+
+Key Divi specifics:
+- **Section types**: regular, fullwidth, specialty
+- **Column types**: `4_4`, `1_2`, `1_3`, `2_3`, `1_4`, `3_4`
+- **Settings as attributes**: `background_color`, `custom_margin`, `custom_padding`, `text_orientation`
+- **Content encoding**: HTML entities, percent-encoding, occasional base64
+- **Global modules**: `global_module` attribute → `et_pb_layout` post type
+- **Custom CSS**: `custom_css_main_element`, `custom_css_before`, `custom_css_after`
+
+Read Divi content via `respira_extract_builder_content` with `builder=divi`.
+
+## Target Builder: Bricks
+
+Bricks stores content in `_bricks_page_content_2` as a JSON array:
+
+```json
+[
+  { "id": "abc123", "name": "section", "parent": 0, "settings": {...} },
+  { "id": "def456", "name": "container", "parent": "abc123", "settings": {...} },
+  { "id": "ghi789", "name": "heading", "parent": "def456", "settings": { "tag": "h2", "text": "..." } }
+]
+```
+
+Key Bricks specifics:
+- Elements use `name` field: `section`, `container`, `heading`, `text-basic`, `image`, `button`
+- Parent-child via `parent` field referencing `id`
+- IDs are short alphanumeric strings
+- Settings use Bricks-specific keys
+- Responsive via `_breakpoints` within settings
+
+Write Bricks content via `respira_inject_builder_content` with `builder=bricks`.
+
+## 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 Bricks theme is installed via `respira_get_site_context`.
+4. **Important**: If using Divi theme (not plugin), note this is a full theme switch to Bricks.
+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 pages/posts using Divi
+   - Module types (frequency count)
+   - Specialty sections found
+   - Global modules referenced
+   - Third-party Divi modules
+   - Content encoding issues
+   - Complexity per page
+
+### Phase 2: Migration Plan
+
+```
+## Divi → Bricks Migration Plan
+
+### Theme Transition Note
+[If Divi theme is active]: This migration involves switching from the Divi
+theme to the Bricks theme. Headers, footers, and global templates will need
+to be recreated in Bricks' template system.
+
+### Site Inventory
+- Total Divi pages: X
+- Total modules to convert: X
+- Auto-convertible: X (Y%)
+- Manual attention: X (Y%)
+
+### Module → Element Mapping
+| Divi Module        | Bricks Element  | Status   |
+|-------------------|----------------|----------|
+| et_pb_text        | text-basic     | Auto     |
+| et_pb_image       | image          | Auto     |
+| et_pb_blurb       | icon-box       | Auto     |
+| et_pb_button      | button         | Auto     |
+| et_pb_slider      | slider         | Auto     |
+| et_pb_tabs        | tabs           | Auto     |
+| et_pb_accordion   | accordion      | Auto     |
+| et_pb_contact     | —              | Manual   |
+| [divi addon]      | —              | Manual   |
+
+### Shortcode Parsing Complexity
+- Pages with clean shortcodes: X
+- Pages with encoded content: X (will decode during migration)
+- Pages with specialty sections: X (layout approximation needed)
+
+### Page-by-Page Plan
+1. **[Page Title]** — X modules, [complexity]
+2. ...
+```
+
+Ask for confirmation:
+> Bricks offers a modern replacement for Divi with cleaner output. Your originals stay safe.
+> 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:
+   - Identify section → row → column → module hierarchy
+   - Decode encoded content (HTML entities, percent-encoding)
+   - Resolve global modules to inline content
+   - Map column types to percentage widths
+3. Build Bricks JSON array:
+   - Create `section` element for each `et_pb_section`
+   - Create `container` elements for rows/columns with flex layout
+   - Map column widths: `4_4`→100%, `1_2`→50%, `1_3`→33.33%, etc.
+   - Convert each module → Bricks element:
+     - `et_pb_text` → `text-basic` (preserve inner HTML)
+     - `et_pb_blurb` → `icon-box` or container with children
+     - `et_pb_image` → `image` (map src, alt, title attributes)
+     - `et_pb_button` → `button` (map text, URL, style)
+   - Map Divi attributes to Bricks settings (colors, spacing, typography)
+   - Generate unique IDs and proper parent references
+   - Flag unmappable modules with comments
+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 Bricks JSON to the duplicate via `respira_inject_builder_content` with `builder=bricks`
+7. Surgical fixes (not a re-inject): when a single element lands wrong — a heading, a button label, a container width — 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 Bricks editor
+   - Flagged items
+   - Layout notes (specialty sections, encoded content)
+3. Post-migration checklist:
+   - [ ] Open each duplicate in Bricks editor
+   - [ ] Verify section/container structure
+   - [ ] Check responsive views
+   - [ ] Verify images and media
+   - [ ] Test links and buttons
+   - [ ] Recreate flagged modules
+   - [ ] Set up Bricks templates for header/footer (if switching from Divi theme)
+   - [ ] Rebuild contact forms using Bricks form element or plugin
+   - [ ] Compare with Divi original
+   - [ ] Check for any 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 switch implications if using Divi theme
+
+## Honest Disclaimer
+
+This skill converts Divi page content to Bricks format and creates draft duplicates for review.
+
+It cannot:
+- Migrate Divi specialty sections with perfect layout fidelity
+- Convert global modules to Bricks templates automatically
+- Handle third-party Divi plugin modules
+- Migrate Divi theme customizer settings
+- Replace forms, popups, or animation setup
+- Guarantee pixel-perfect results from shortcode-to-JSON conversion
+
+It can:
+- Parse complex Divi shortcode hierarchies including encoded content
+- Convert 75-85% of standard Divi modules to Bricks elements
+- Preserve all text, images, links, and core styling
+- Take advantage of Bricks' modern, faster rendering
+- Save days of manual page rebuilding
+- Flag everything that needs manual attention
+- 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-bricks`
+- 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-bricks

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

@@ -0,0 +1,328 @@
+# Migrate Divi 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 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-block 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.
+
+Converts Divi-built WordPress pages to native Gutenberg blocks. Parses Divi's shortcode-based content from post_content, maps each module to its closest core block equivalent, generates a migration plan for approval, and writes clean block markup to the target pages. Use this skill whenever someone wants to move from Divi to Gutenberg, eliminate the Divi dependency, switch to native blocks, or simplify their WordPress stack by removing Elegant Themes' builder.
+
+## What This Skill Does
+
+Divi stores everything as nested shortcodes directly in `post_content` — a fundamentally different approach from JSON-based builders. The content is a hierarchy of `[et_pb_section]`, `[et_pb_row]`, `[et_pb_column]`, and `[et_pb_module]` shortcodes with settings as attributes. Converting this to Gutenberg blocks means parsing that shortcode tree, extracting content and settings, and generating the equivalent `<!-- wp:block -->` markup.
+
+This is one of the more complex migrations because Divi shortcodes often contain escaped HTML, base64-encoded content, and deeply nested attribute strings that need careful parsing.
+
+**Handles:**
+- et_pb_section → Group block with layout settings
+- et_pb_row/et_pb_column → Columns and Column blocks
+- et_pb_text → Paragraph blocks (with inline HTML preserved)
+- et_pb_blurb → Group block with Image + Heading + Paragraph
+- et_pb_image → Image block
+- et_pb_button → Buttons block
+- et_pb_video → Video or Embed block
+- et_pb_divider → Separator block
+- et_pb_slider/et_pb_slide → Gallery or Group blocks (simplified)
+- et_pb_accordion/et_pb_accordion_item → Details blocks (WP 6.3+)
+- et_pb_tabs/et_pb_tab → Group with heading blocks
+- et_pb_toggle → Details block (WP 6.3+)
+- et_pb_code → Custom HTML block
+- et_pb_sidebar → Widget block
+- et_pb_gallery → Gallery block
+- et_pb_counters → HTML approximation
+- Fullwidth variants (et_pb_fullwidth_*) → full-width Group blocks
+
+**Preserves:**
+- All text content and inline HTML formatting
+- Image URLs, alt text, and links
+- Heading text and hierarchy
+- Button labels, URLs, and targets
+- Video URLs and embed sources
+- List content
+- Code block contents
+- Basic color settings where Gutenberg supports them
+
+## What This Skill Does NOT Do
+
+- **Divi's visual design layer** — Divi applies extensive CSS through its settings (gradient backgrounds, custom fonts from 800+ Google Fonts choices, box shadows with specific blur/spread, text shadow, filters, transforms). Gutenberg supports some of these; many will be simplified or lost.
+- **Specialty sections** — Divi's specialty section layouts (sidebar + content combinations) have no direct Gutenberg equivalent.
+- **Global modules** — Stored as `et_pb_layout` post type. These are resolved to inline content during migration; Gutenberg reusable blocks can be created manually afterward.
+- **Divi Builder plugin modules** — Modules added by Divi-specific plugins (Divi Toolbox, Divi Supreme, etc.) are flagged.
+- **Theme customizer settings** — Divi theme customizer values (global fonts, colors, sizing) don't transfer to block themes.
+- **Dynamic content** — Divi's dynamic content features need separate solutions.
+- **Contact forms** — et_pb_contact_form needs a forms plugin (WPForms, etc.).
+- **Divi Library layouts** — Template library layouts stored in et_pb_layout post type are not auto-migrated.
+- **Advanced design settings** — Rounded corners, CSS filters, blend modes, and transforms have limited Gutenberg support.
+
+## 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)
+- WordPress 6.0+ (6.3+ recommended for Details block support)
+- A block-compatible theme ready for post-migration (if switching from Divi theme)
+- Read access to scan Divi content
+- Write access to create duplicates with Gutenberg content
+
+## Trigger Phrase
+
+- "migrate divi to gutenberg"
+
+## Alternative Triggers
+
+- "convert divi to blocks"
+- "switch from divi to gutenberg"
+- "remove divi builder"
+- "rebuild divi pages with blocks"
+- "divi to block editor"
+- "decommission divi"
+- "get off divi"
+
+## Source Builder: Divi
+
+Divi stores content as shortcodes in `post_content`. The module structure follows a strict hierarchy:
+
+```
+[et_pb_section fb_built="1" _builder_version="4.x"]
+  [et_pb_row _builder_version="4.x"]
+    [et_pb_column type="4_4" _builder_version="4.x"]
+      [et_pb_text _builder_version="4.x"]
+        <p>Your content here</p>
+      [/et_pb_text]
+      [et_pb_image src="image.jpg" alt="Alt text" _builder_version="4.x"][/et_pb_image]
+      [et_pb_button button_text="Click Me" button_url="https://..." _builder_version="4.x"][/et_pb_button]
+    [/et_pb_column]
+  [/et_pb_row]
+[/et_pb_section]
+```
+
+Key Divi specifics:
+- **Section types**: regular, fullwidth, specialty (with predefined column layouts)
+- **Column types**: defined by `type` attribute — `4_4` (full), `1_2` (half), `1_3` (third), `2_3` (two-thirds), `1_4` (quarter), `3_4` (three-quarters)
+- **Settings as attributes**: `background_color`, `text_orientation`, `custom_margin`, `custom_padding`, etc.
+- **Builder version tracking**: `_builder_version` attribute on every element
+- **Content encoding**: Text content may contain escaped HTML entities, newline placeholders (`%22`, `%91`, `%93`), and occasional base64
+- **Global modules**: Referenced via `global_module` attribute pointing to an `et_pb_layout` post
+- **Custom CSS fields**: `custom_css_main_element`, `custom_css_before`, `custom_css_after` attributes
+
+Read Divi content via `respira_extract_builder_content` with `builder=divi`.
+
+## Target: Gutenberg (Block Editor)
+
+Gutenberg stores content in `post_content` as HTML with block comment delimiters:
+
+```html
+<!-- wp:group {"layout":{"type":"constrained"}} -->
+<div class="wp-block-group">
+  <!-- wp:heading {"level":2} -->
+  <h2 class="wp-block-heading">Title Here</h2>
+  <!-- /wp:heading -->
+  <!-- wp:paragraph -->
+  <p>Content text.</p>
+  <!-- /wp:paragraph -->
+</div>
+<!-- /wp:group -->
+```
+
+Key Gutenberg specifics:
+- Block attributes in opening comment JSON
+- Layout blocks: `wp:group`, `wp:columns`, `wp:column`
+- Inline styles via `style` attribute in block JSON
+- Columns use percentage widths
+- Everything lives in `post_content` — no separate meta
+
+Write Gutenberg content via `respira_update_page` or `respira_update_post` targeting the `content` field.
+
+## 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 (theme or plugin) via `respira_list_plugins` and `respira_get_site_context`.
+3. Check WordPress version (6.0+ required, 6.3+ ideal).
+4. **Important**: If using Divi theme (not just plugin), note that the user will need an alternative theme post-migration.
+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. For each Divi page, extract content via `respira_extract_builder_content` with `builder=divi`
+7. Build an inventory:
+   - Total pages/posts using Divi
+   - Module types used (frequency count)
+   - Specialty sections detected (high complexity)
+   - Global modules referenced
+   - Third-party Divi modules
+   - Content encoding issues found
+   - Complexity per page (simple/moderate/complex)
+
+### Phase 2: Migration Plan
+
+Present a plan that sets realistic expectations:
+
+```
+## Divi → Gutenberg Migration Plan
+
+### Important Context
+Divi and Gutenberg have very different design philosophies. Divi offers
+extensive visual customization through its settings panel; Gutenberg
+prioritizes clean, semantic content. Expect simpler but faster-loading pages.
+
+If you are using the Divi theme (not just the plugin), you will need a
+block-compatible theme (e.g., Twenty Twenty-Four, Astra, Kadence).
+
+### Site Inventory
+- Total Divi pages: X
+- Total modules to convert: X
+- Direct equivalents: X (Y%)
+- Approximate equivalents: X (Y%)
+- Manual recreation needed: X (Y%)
+
+### Module Mapping Summary
+| Divi Module       | Gutenberg Block  | Fidelity     |
+|------------------|-----------------|--------------|
+| et_pb_text       | wp:paragraph    | Exact        |
+| et_pb_image      | wp:image        | Exact        |
+| et_pb_blurb      | wp:group combo  | Approximate  |
+| et_pb_slider     | wp:group/gallery| Simplified   |
+| et_pb_contact    | —               | Manual       |
+
+### Shortcode Parsing Notes
+- [Any encoding issues found]
+- [Specialty sections that need layout interpretation]
+- [Global modules that will be inlined]
+
+### Page-by-Page Plan
+1. **[Page Title]** — X modules, [complexity]
+2. ...
+```
+
+Ask for confirmation:
+> Divi → Gutenberg is a significant simplification. Pages will be cleaner but less visually elaborate.
+> 1. Migrate all pages
+> 2. Migrate specific pages
+> 3. Start with a test page (strongly recommended)
+> 4. Just keep this plan
+
+### Phase 3: Page-by-Page Migration
+
+For each approved page:
+
+1. Read full Divi content via `respira_extract_builder_content` with `builder=divi`
+2. Parse the Divi shortcode tree:
+   - Identify section/row/column hierarchy
+   - Decode any encoded content (HTML entities, percent-encoding)
+   - Resolve global module references to inline content
+3. Map each module:
+   - `et_pb_section` → `<!-- wp:group -->` (with full-width if fullwidth section)
+   - `et_pb_row` + `et_pb_column` → `<!-- wp:columns -->` + `<!-- wp:column {"width":"X%"} -->`
+   - Column type mapping: `4_4`→100%, `1_2`→50%, `1_3`→33.33%, `2_3`→66.66%, `1_4`→25%, `3_4`→75%
+   - `et_pb_text` → `<!-- wp:paragraph -->` (or multiple blocks if content has headings)
+   - `et_pb_blurb` → Group containing Image + Heading + Paragraph
+   - `et_pb_image` → `<!-- wp:image -->`
+   - `et_pb_button` → `<!-- wp:buttons --><!-- wp:button -->`
+   - Map background colors to Group block style attributes
+   - Flag unmappable modules with `<!-- MIGRATION NOTE: ... -->`
+4. Assemble complete block markup
+5. Take a `respira_get_snapshot` checkpoint of the target before any write, so the page can be restored exactly if the conversion needs unwinding
+6. Create duplicate via `respira_create_page_duplicate` or `respira_create_post_duplicate`
+7. Write the block markup to the duplicate via `respira_update_page` or `respira_update_post`
+8. Surgical fixes (not a rewrite): when a single block lands wrong — a heading, a button label, a column width — 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.
+9. Report: modules converted, items flagged, layout changes made
+
+### Phase 4: Post-Migration Verification
+
+1. Summarize all migrations
+2. For each migrated page:
+   - Link to edit in Gutenberg
+   - Flagged items
+   - Layout simplification notes
+3. Post-migration checklist:
+   - [ ] Open each duplicate in block editor — verify blocks parse correctly
+   - [ ] Check responsive preview
+   - [ ] Verify all images and media
+   - [ ] Test links and buttons
+   - [ ] Recreate forms with a dedicated forms plugin
+   - [ ] Recreate sliders if needed (or use a block-based slider)
+   - [ ] Plan theme switch if on Divi theme (do this after all pages are verified)
+   - [ ] Check page speed improvement
+   - [ ] Review for Divi shortcode remnants in content
+
+## 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 dependency if using Divi theme
+
+## Honest Disclaimer
+
+This skill converts Divi page content to Gutenberg blocks and creates draft duplicates for review.
+
+It cannot:
+- Replicate Divi's visual design precision in Gutenberg
+- Convert specialty section layouts perfectly
+- Migrate contact forms, sliders, or animations
+- Handle third-party Divi plugin modules
+- Switch your theme for you (if on Divi theme)
+- Replace manual review and fine-tuning
+
+It can:
+- Convert 60-75% of standard Divi modules to clean blocks
+- Extract all text, images, and links from shortcode markup
+- Eliminate Divi dependency for simpler pages
+- Dramatically improve page load speed
+- Parse complex Divi shortcode encoding
+- Provide a clear map of manual work needed
+- 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_find_builder_targets`
+- `respira_create_page_duplicate`
+- `respira_create_post_duplicate`
+- `respira_update_page`
+- `respira_update_post`
+- `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-gutenberg`
+- site/version context
+- duration and success
+- pages migrated, blocks created, modules flagged counts
+- tools used
+
+Never block user flow on telemetry failure.
+
+## Related Skills
+
+- WordPress Site DNA (understand site structure and theme dependency before migrating)
+- Internal Link Builder (verify internal links post-migration)
+- SEO & AEO Amplifier (verify SEO preservation post-migration)
+- Technical Debt Audit (find and clean Divi shortcode remnants)
+
+---
+
+Built by Respira Team
+https://respira.press/skills/migrate-divi-to-gutenberg