From 5ab4e13a84cd9f14fcf85009a5de56e0e62e2f80 Mon Sep 17 00:00:00 2001
From: Roberto Aranda <roberto.aranda@automattic.com>
Date: Wed, 8 Apr 2026 17:16:53 +0200
Subject: [PATCH 1/7] Add HTML block checker to enforce native Gutenberg blocks
 over core/html

Introduces a deterministic check_html_blocks tool that parses block content
via wp.blocks.parse() in a real browser, identifies core/html blocks wrapping
structural HTML (divs, sections, headings, etc.), and flags them with
replacement suggestions. The check is also integrated into validate_blocks
so both validations run in a single call. Updates the system prompt with
detailed block pattern references and stricter guidelines.
---
 apps/cli/ai/html-block-checker.ts            | 350 ++++++++++++++++++
 apps/cli/ai/system-prompt.ts                 | 117 +++++-
 apps/cli/ai/tests/html-block-checker.test.ts | 364 +++++++++++++++++++
 apps/cli/ai/tests/tools.test.ts              |   4 +
 apps/cli/ai/tools.ts                         | 142 +++++++-
 5 files changed, 962 insertions(+), 15 deletions(-)
 create mode 100644 apps/cli/ai/html-block-checker.ts
 create mode 100644 apps/cli/ai/tests/html-block-checker.test.ts

diff --git a/apps/cli/ai/html-block-checker.ts b/apps/cli/ai/html-block-checker.ts
new file mode 100644
index 0000000000..c75b0842a6
--- /dev/null
+++ b/apps/cli/ai/html-block-checker.ts
@@ -0,0 +1,350 @@
+import { EditorPage } from 'cli/ai/browser-utils';
+
+interface HtmlBlockIssue {
+	index: number;
+	originalContent: string;
+	wrapperTag: string;
+	maxDepth: number;
+	totalElements: number;
+	reason: 'structural_tag' | 'deep_nesting';
+	suggestedBlocks: string[];
+}
+
+export interface HtmlBlockReport {
+	totalBlocks: number;
+	htmlBlocks: number;
+	problematicBlocks: number;
+	allowedBlocks: number;
+	passed: boolean;
+	issues: HtmlBlockIssue[];
+	error?: string;
+}
+
+/**
+ * The check fails when the number of problematic HTML blocks exceeds this.
+ */
+const STRUCTURAL_BLOCK_THRESHOLD = 0;
+
+/**
+ * Maximum DOM nesting depth allowed inside a single HTML block before it is
+ * flagged. A depth of 4 means: wrapper > child > grandchild > great-grandchild.
+ */
+const MAX_NESTING_DEPTH = 4;
+
+// Cache one EditorPage per site URL so repeated checks reuse the same
+// browser tab instead of navigating and loading the block editor each time.
+const editorPages = new Map< string, EditorPage >();
+
+function getEditorPage( siteUrl: string ): EditorPage {
+	let ep = editorPages.get( siteUrl );
+	if ( ! ep ) {
+		ep = new EditorPage( siteUrl );
+		editorPages.set( siteUrl, ep );
+	}
+	return ep;
+}
+
+/**
+ * Tags that indicate acceptable use of core/html blocks when they are the
+ * outermost wrapper element.
+ */
+const ALLOWED_WRAPPER_TAGS = new Set( [
+	'svg',
+	'form',
+	'script',
+	'canvas',
+	'iframe',
+	'video',
+	'audio',
+	'style',
+	'input',
+	'select',
+	'textarea',
+] );
+
+/**
+ * Tags whose content can be expressed with native Gutenberg blocks.
+ * If ALL descendant elements are in this set, the HTML block is convertible.
+ */
+const CONVERTIBLE_TAGS = new Set( [
+	'div',
+	'section',
+	'header',
+	'footer',
+	'main',
+	'article',
+	'aside',
+	'nav',
+	'h1',
+	'h2',
+	'h3',
+	'h4',
+	'h5',
+	'h6',
+	'p',
+	'ul',
+	'ol',
+	'li',
+	'dl',
+	'dt',
+	'dd',
+	'table',
+	'thead',
+	'tbody',
+	'tfoot',
+	'tr',
+	'th',
+	'td',
+	'img',
+	'figure',
+	'figcaption',
+	'blockquote',
+	'a',
+	'span',
+	'em',
+	'strong',
+	'b',
+	'i',
+	'u',
+	'br',
+	'hr',
+	'small',
+	'mark',
+	'sub',
+	'sup',
+	'abbr',
+	'cite',
+	'code',
+	'pre',
+	'time',
+] );
+
+/**
+ * Maps structural wrapper tags to suggested Gutenberg block replacements.
+ */
+const REPLACEMENT_MAP: Record< string, string[] > = {
+	div: [ 'core/group (with inner blocks for children)' ],
+	section: [ 'core/group with tagName="section"' ],
+	header: [ 'core/group with tagName="header"' ],
+	footer: [ 'core/group with tagName="footer"' ],
+	main: [ 'core/group with tagName="main"' ],
+	article: [ 'core/group with tagName="article"' ],
+	aside: [ 'core/group with tagName="aside"' ],
+	nav: [ 'core/navigation' ],
+	h1: [ 'core/heading with level=1' ],
+	h2: [ 'core/heading with level=2' ],
+	h3: [ 'core/heading with level=3' ],
+	h4: [ 'core/heading with level=4' ],
+	h5: [ 'core/heading with level=5' ],
+	h6: [ 'core/heading with level=6' ],
+	p: [ 'core/paragraph' ],
+	ul: [ 'core/list' ],
+	ol: [ 'core/list' ],
+	li: [ 'core/list-item (inside core/list)' ],
+	table: [ 'core/table' ],
+	img: [ 'core/image' ],
+	figure: [ 'core/image or core/media-text' ],
+	figcaption: [ 'core/image caption or core/media-text' ],
+	blockquote: [ 'core/quote' ],
+	a: [ 'core/button or inline link in core/paragraph' ],
+	dl: [ 'core/list or core/group with core/paragraph items' ],
+	span: [ 'core/paragraph or core/group' ],
+};
+
+/**
+ * Check WordPress block content for misuse of core/html blocks.
+ *
+ * Navigates to `post-new.php` (which loads wp.blocks with all registered
+ * blocks) and runs `wp.blocks.parse()` to identify core/html blocks. Each
+ * HTML block is analysed for structural tags and deep nesting.
+ */
+export async function checkHtmlBlocks(
+	content: string,
+	siteUrl: string
+): Promise< HtmlBlockReport > {
+	const editorPage = getEditorPage( siteUrl );
+
+	try {
+		const page = await editorPage.getPage();
+
+		const report = await page.evaluate(
+			( params: {
+				html: string;
+				allowedWrapperTags: string[];
+				convertibleTags: string[];
+				replacementMap: Record< string, string[] >;
+				structuralThreshold: number;
+				maxDepth: number;
+			} ) => {
+				/* eslint-disable @typescript-eslint/no-explicit-any */
+				const wpBlocks = ( window as any ).wp?.blocks;
+				if ( ! wpBlocks ) {
+					return {
+						totalBlocks: 0,
+						htmlBlocks: 0,
+						problematicBlocks: 0,
+						allowedBlocks: 0,
+						passed: false,
+						issues: [] as any[],
+						error: 'wp.blocks is not available on this page.',
+					};
+				}
+
+				const allowedWrapperSet = new Set( params.allowedWrapperTags );
+				const convertibleSet = new Set( params.convertibleTags );
+				const blocks = wpBlocks.parse( params.html );
+				const issues: any[] = [];
+				let htmlBlockCount = 0;
+				let allowedCount = 0;
+				let totalBlockCount = 0;
+
+				function computeDepthAndCount( el: Element ): {
+					depth: number;
+					count: number;
+				} {
+					let maxChildDepth = 0;
+					let count = 1;
+					for ( const child of Array.from( el.children ) ) {
+						const result = computeDepthAndCount( child );
+						if ( result.depth > maxChildDepth ) {
+							maxChildDepth = result.depth;
+						}
+						count += result.count;
+					}
+					return { depth: 1 + maxChildDepth, count };
+				}
+
+				/**
+				 * Returns true if ALL element descendants of `el` (including
+				 * `el` itself) are tags that have native Gutenberg block
+				 * equivalents.
+				 *
+				 * When this returns true the HTML block is "convertible" —
+				 * its content can be fully expressed with core blocks.
+				 * When false the block contains SVGs, form elements,
+				 * or other non-block content and is considered an
+				 * acceptable use of core/html.
+				 *
+				 * Note: data-* attributes are NOT considered — they can
+				 * be replaced by className on core/group blocks and JS
+				 * can target those class names instead.
+				 */
+				function isConvertibleContent( el: Element ): boolean {
+					const tag = el.tagName.toLowerCase();
+					if ( ! convertibleSet.has( tag ) ) {
+						return false;
+					}
+					for ( const child of Array.from( el.children ) ) {
+						if ( ! isConvertibleContent( child ) ) {
+							return false;
+						}
+					}
+					return true;
+				}
+
+				function walkBlocks( blockList: any[] ) {
+					for ( const block of blockList ) {
+						totalBlockCount++;
+
+						if ( block.blockName === 'core/html' || block.name === 'core/html' ) {
+							htmlBlockCount++;
+							const rawHtml = block.originalContent || block.innerHTML || '';
+
+							const doc = new DOMParser().parseFromString( rawHtml, 'text/html' );
+							const wrapper = doc.body.firstElementChild;
+
+							if ( ! wrapper ) {
+								// Text-only or empty HTML block — skip
+								allowedCount++;
+							} else {
+								const tag = wrapper.tagName.toLowerCase();
+
+								if ( allowedWrapperSet.has( tag ) ) {
+									// Wrapper is an explicitly allowed tag (svg, form, script, …)
+									allowedCount++;
+								} else if ( ! isConvertibleContent( wrapper ) ) {
+									// Contains non-convertible content (SVGs, data-* attrs,
+									// form elements, canvas, etc.) — acceptable HTML usage
+									allowedCount++;
+								} else {
+									// All content is convertible to native blocks — flag it
+									const { depth, count } = computeDepthAndCount( wrapper );
+									const reason = depth >= params.maxDepth ? 'deep_nesting' : 'structural_tag';
+									const suggestions = params.replacementMap[ tag ] || [
+										'core/group or appropriate core block',
+									];
+
+									issues.push( {
+										index: totalBlockCount - 1,
+										originalContent: rawHtml.slice( 0, 300 ),
+										wrapperTag: tag,
+										maxDepth: depth,
+										totalElements: count,
+										reason,
+										suggestedBlocks: suggestions,
+									} );
+								}
+							}
+						}
+
+						// Recurse into inner blocks
+						const innerBlocks = block.innerBlocks || [];
+						if ( innerBlocks.length > 0 ) {
+							walkBlocks( innerBlocks );
+						}
+					}
+				}
+
+				walkBlocks( blocks );
+
+				const problematicCount = issues.length;
+				const passed = problematicCount <= params.structuralThreshold;
+
+				return {
+					totalBlocks: totalBlockCount,
+					htmlBlocks: htmlBlockCount,
+					problematicBlocks: problematicCount,
+					allowedBlocks: allowedCount,
+					passed,
+					issues,
+				};
+				/* eslint-enable @typescript-eslint/no-explicit-any */
+			},
+			{
+				html: content,
+				allowedWrapperTags: [ ...ALLOWED_WRAPPER_TAGS ],
+				convertibleTags: [ ...CONVERTIBLE_TAGS ],
+				replacementMap: REPLACEMENT_MAP,
+				structuralThreshold: STRUCTURAL_BLOCK_THRESHOLD,
+				maxDepth: MAX_NESTING_DEPTH,
+			}
+		);
+
+		return report as HtmlBlockReport;
+	} catch ( error ) {
+		// If navigation or evaluation failed, discard the cached page so the
+		// next call gets a fresh one.
+		await editorPage.close();
+		editorPages.delete( siteUrl );
+
+		return {
+			totalBlocks: 0,
+			htmlBlocks: 0,
+			problematicBlocks: 0,
+			allowedBlocks: 0,
+			passed: false,
+			issues: [],
+			error: `HTML block check error: ${
+				error instanceof Error ? error.message : String( error )
+			}`,
+		};
+	}
+}
+
+/** Clean up all cached editor pages. */
+export async function cleanupCheckerPages(): Promise< void > {
+	for ( const ep of editorPages.values() ) {
+		await ep.close();
+	}
+	editorPages.clear();
+}
diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index 17027ade07..cddfe5e100 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -5,8 +5,8 @@ IMPORTANT: You MUST use your mcp__studio__ tools to manage WordPress sites. Neve
 IMPORTANT: For any generated content for the site, these three principles are mandatory:
 
 - Gorgeous design: More details on the guidelines below.
-- No HTML blocks and raw HTML: Check the block content guidelines below. 
-- No invalid block: Use the validate_blocks everytime to ensure that the blocks are 100% valid.
+- Native Gutenberg blocks ONLY: Every heading MUST be \`core/heading\`, every paragraph MUST be \`core/paragraph\`, every layout section MUST be \`core/group\` or \`core/columns\`. NEVER wrap raw HTML in \`<!-- wp:html -->\` — see Block Content Guidelines below.
+- No invalid blocks: Use \`validate_blocks\` on every piece of block content (post content, template parts). It validates block markup AND checks for HTML block misuse in a single call.
 
 ## Workflow
 
@@ -20,10 +20,10 @@ For any request that involves a WordPress site, you MUST first determine which s
 Then continue with:
 
 1. **Get site details**: Use site_info to get the site path, URL, and credentials.
-2. **Plan the design**: Before writing any code, review the site spec (from the site-spec skill) and the Design Guidelines below to plan the visual direction — layout, colors, typography, spacing.
+2. **Plan the design and block structure**: Before writing any code, review the site spec (from the site-spec skill) and the Design Guidelines below to plan the visual direction — layout, colors, typography, spacing. Also plan how each section maps to Gutenberg blocks: which sections use \`core/group\`, where to use \`core/columns\`, which text is \`core/heading\` vs \`core/paragraph\`, etc. Refer to the Block Content Guidelines for the correct markup patterns. Do NOT default to \`core/html\` — compose in native blocks from the start.
 3. **Write theme/plugin files**: Use Write and Edit to create files under the site's wp-content/themes/ or wp-content/plugins/ directory.
-4. **Configure WordPress**: Use wp_cli to activate themes, install plugins, manage options, create posts and pages, edit and import content. The site must be running. Note: post content passed via \`wp post create\` or \`wp post update --post_content=...\` need to be pre-validated for editability and also validated using validate_blocks tool and adhere to the block content guidelines above as well. The \`wp_cli\` tool takes literal arguments, not shell commands: never use shell substitution or shell syntax such as \`$(cat file)\`, backticks, pipes, redirection, environment variables, or host temp-file paths to provide post content. Pass the literal content directly in \`--post_content=...\`, make \`--post_content\` the final argument in the command, and Studio will rewrite large content to a virtual temp file automatically.
-5. **Check the misuse of HTML blocks**: Verify if HTML blocks were used as sections or not. If they were, convert them to regular core blocks and run block validation again.
+4. **Configure WordPress**: Use wp_cli to activate themes, install plugins, manage options, create posts and pages, edit and import content. The site must be running. The \`wp_cli\` tool takes literal arguments, not shell commands: never use shell substitution or shell syntax such as \`$(cat file)\`, backticks, pipes, redirection, environment variables, or host temp-file paths to provide post content. Pass the literal content directly in \`--post_content=...\`, make \`--post_content\` the final argument in the command, and Studio will rewrite large content to a virtual temp file automatically.
+5. **Validate ALL block content**: Run \`validate_blocks\` on every piece of block content — page/post content (passed via \`--post_content\`) AND template part files (header.html, footer.html, etc.). The tool runs two checks: (a) block markup validity and (b) HTML block misuse detection. It automatically allows HTML blocks whose content contains non-block elements (inline SVGs, \`<form>\`, \`<canvas>\`, \`<iframe>\`, etc.). It flags any HTML block whose descendant elements are all expressible with native Gutenberg blocks. Adding \`data-*\` attributes does NOT make a block acceptable — use \`className\` on \`core/group\` blocks instead. If it flags any blocks, you MUST convert them and re-run \`validate_blocks\` until it passes.
 6. **Check the result**: Use take_screenshot to capture the site's landing page on desktop and mobile and verify the design visually on both viewports, check for wrong spacing, alignment, colors, contrast, borders, hover styles and other visual issues. Fix any issues found. Pay particular attention to the navigation menu and the CTA buttons. The design needs to match your original expectations.
 
 ## Available Studio Tools (prefixed with mcp__studio__)
@@ -39,7 +39,7 @@ Then continue with:
 - preview_update: Update an existing hosted WordPress.com preview from a local site; this can take a few minutes, so tell the user to wait
 - preview_delete: Delete a hosted WordPress.com preview by hostname
 - wp_cli: Run WP-CLI commands on a running site
-- validate_blocks: Validate block content for correctness on a running site (runs each block through its save() function in a real browser). Requires a site name or path. Call after every file write/edit that contains block content.
+- validate_blocks: Validates block content on a running site. Runs TWO checks: (1) block markup validity (save-function comparison in a real browser) and (2) HTML block misuse detection (flags core/html blocks that should use native Gutenberg blocks). Call on every piece of block content — post content AND template parts.
 - take_screenshot: Take a full-page screenshot of a URL (supports desktop and mobile viewports). Use this to visually check the site after building it.
 - audit_performance: Measure frontend performance metrics (TTFB, FCP, LCP, CLS, page weight, DOM size, JS/CSS/image/font asset breakdown) for a running site. Use this to identify performance bottlenecks and guide optimization.
 
@@ -56,12 +56,105 @@ Then continue with:
 
 ## Block content guidelines
 
-- Only use \`core/html\` blocks for:                                                                                               
-	- Inline SVGs                                                                                                                  
-	- \`<form>\` elements and interactive inputs                                                                                     
-	- Animation/interaction markup with no block equivalent (marquee, cursor)                                                      
-	- A single \`<script>\` block at the bottom of the page for JS                                                                   
-- Never use \`core/html\` to wrap text content, headings, layout sections, or lists. 
+**CRITICAL — Think in blocks, not HTML.** When writing page/post content or template parts, you MUST compose content using Gutenberg block markup from the start. Do NOT write raw HTML sections and wrap them in \`<!-- wp:html -->\`. Instead, use the block patterns below to build every section.
+
+### Core block patterns
+
+**Section wrapper** (replaces \`<section>\`, \`<div>\`, \`<aside>\`, \`<header>\`, \`<footer>\`):
+\`\`\`
+<!-- wp:group {"tagName":"section","className":"hero-section","layout":{"type":"default"}} -->
+<section class="wp-block-group hero-section">
+  <!-- inner blocks go here -->
+</section>
+<!-- /wp:group -->
+\`\`\`
+
+**Heading** (replaces \`<h1>\`–\`<h6>\`):
+\`\`\`
+<!-- wp:heading {"level":1,"className":"hero-title"} -->
+<h1 class="wp-block-heading hero-title">Your Title</h1>
+<!-- /wp:heading -->
+\`\`\`
+
+**Paragraph** (replaces \`<p>\`):
+\`\`\`
+<!-- wp:paragraph {"className":"hero-subtitle"} -->
+<p class="hero-subtitle">Your text here.</p>
+<!-- /wp:paragraph -->
+\`\`\`
+
+**Columns layout** (replaces CSS grid/flex with \`<div>\` children):
+\`\`\`
+<!-- wp:columns {"className":"features-grid"} -->
+<div class="wp-block-columns features-grid">
+  <!-- wp:column -->
+  <div class="wp-block-column">
+    <!-- inner blocks -->
+  </div>
+  <!-- /wp:column -->
+  <!-- wp:column -->
+  <div class="wp-block-column">
+    <!-- inner blocks -->
+  </div>
+  <!-- /wp:column -->
+</div>
+<!-- /wp:columns -->
+\`\`\`
+
+**Image** (replaces \`<img>\`):
+\`\`\`
+<!-- wp:image {"className":"hero-image"} -->
+<figure class="wp-block-image hero-image"><img src="https://example.com/image.jpg" alt="Description"/></figure>
+<!-- /wp:image -->
+\`\`\`
+
+**Buttons** (replaces \`<a class="btn">\`):
+\`\`\`
+<!-- wp:buttons {"className":"hero-cta"} -->
+<div class="wp-block-buttons hero-cta">
+  <!-- wp:button {"className":"primary-btn"} -->
+  <div class="wp-block-button primary-btn"><a class="wp-block-button__link wp-element-button" href="#">Get Started</a></div>
+  <!-- /wp:button -->
+</div>
+<!-- /wp:buttons -->
+\`\`\`
+
+**List** (replaces \`<ul>\` / \`<ol>\`):
+\`\`\`
+<!-- wp:list {"className":"feature-list"} -->
+<ul class="feature-list">
+  <!-- wp:list-item -->
+  <li>First item</li>
+  <!-- /wp:list-item -->
+  <!-- wp:list-item -->
+  <li>Second item</li>
+  <!-- /wp:list-item -->
+</ul>
+<!-- /wp:list -->
+\`\`\`
+
+**Separator** (replaces \`<hr>\`):
+\`\`\`
+<!-- wp:separator {"className":"section-divider"} -->
+<hr class="wp-block-separator section-divider"/>
+<!-- /wp:separator -->
+\`\`\`
+
+### Nesting blocks
+
+Sections are built by nesting blocks inside \`core/group\`. All visual styling (grid layouts, spacing, colors, backgrounds, animations) goes in \`style.css\` targeting the \`className\`. The block structure is for editability; the CSS is for aesthetics.
+
+### When core/html IS acceptable
+
+Only use \`core/html\` for content that has NO native block equivalent:
+- Inline SVGs (icons, illustrations, decorative graphics)
+- \`<form>\` elements and interactive inputs
+- Animation/interaction markup (marquee, custom cursor, scroll-triggered elements)
+- A single \`<script>\` block at the bottom of the page for frontend JS
+
+### Additional rules
+
+- Never use \`core/html\` to wrap text content, headings, layout sections, or lists.
 - No decorative HTML comments (e.g. \`<!-- Hero Section -->\`, \`<!-- Features -->\`). Only block delimiter comments are allowed.
 - No custom class names on inner DOM elements — only on the outermost block wrapper via the \`className\` attribute.
 - No inline \`style\` or \`style\` block attributes for styling. Use \`className\` + \`style.css\` instead.
diff --git a/apps/cli/ai/tests/html-block-checker.test.ts b/apps/cli/ai/tests/html-block-checker.test.ts
new file mode 100644
index 0000000000..6bce93c229
--- /dev/null
+++ b/apps/cli/ai/tests/html-block-checker.test.ts
@@ -0,0 +1,364 @@
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-function-type */
+import { vi } from 'vitest';
+import { EditorPage } from 'cli/ai/browser-utils';
+import { checkHtmlBlocks, cleanupCheckerPages } from '../html-block-checker';
+
+// vi.mock is hoisted by vitest, so placement after imports is fine.
+vi.mock( 'cli/ai/browser-utils', () => ( {
+	getSharedBrowser: vi.fn(),
+	EditorPage: vi.fn(),
+} ) );
+
+function setupMockEditorPage( blocks: any[] ) {
+	const mockPage = {
+		evaluate: vi.fn().mockImplementation( ( fn: Function, ...args: any[] ) => {
+			( globalThis as any ).window = {
+				...( globalThis as any ).window,
+				wp: {
+					blocks: {
+						parse: () => blocks,
+					},
+				},
+			};
+			return fn( ...args );
+		} ),
+	};
+
+	const MockEditorPage = vi.mocked( EditorPage );
+	MockEditorPage.mockImplementation( function ( this: any ) {
+		this.getPage = vi.fn().mockResolvedValue( mockPage );
+		this.close = vi.fn().mockResolvedValue( undefined );
+	} as any );
+
+	return mockPage;
+}
+
+describe( 'checkHtmlBlocks', () => {
+	afterEach( async () => {
+		await cleanupCheckerPages();
+		vi.restoreAllMocks();
+		delete ( globalThis as any ).window?.wp;
+	} );
+
+	it( 'passes when there are no core/html blocks', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/paragraph',
+				blockName: 'core/paragraph',
+				originalContent: '<p>Hi</p>',
+				innerBlocks: [],
+			},
+		] );
+
+		const report = await checkHtmlBlocks(
+			'<!-- wp:paragraph --><p>Hi</p><!-- /wp:paragraph -->',
+			'http://localhost:8888'
+		);
+
+		expect( report.passed ).toBe( true );
+		expect( report.htmlBlocks ).toBe( 0 );
+		expect( report.problematicBlocks ).toBe( 0 );
+		expect( report.issues ).toHaveLength( 0 );
+	} );
+
+	it( 'passes when HTML blocks only contain allowed wrapper tags (SVG, form, script)', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<svg viewBox="0 0 100 100"><circle cx="50" cy="50" r="50"/></svg>',
+				innerBlocks: [],
+			},
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<form action="/submit"><input type="text"/></form>',
+				innerBlocks: [],
+			},
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<script>console.log("hello")</script>',
+				innerBlocks: [],
+			},
+		] );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.passed ).toBe( true );
+		expect( report.htmlBlocks ).toBe( 3 );
+		expect( report.allowedBlocks ).toBe( 3 );
+		expect( report.problematicBlocks ).toBe( 0 );
+	} );
+
+	it( 'allows HTML blocks wrapping non-convertible content (SVGs inside a div)', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent:
+					'<div class="logo-grid"><svg viewBox="0 0 100 100"><circle/></svg><svg viewBox="0 0 50 50"><rect/></svg></div>',
+				innerBlocks: [],
+			},
+		] );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.passed ).toBe( true );
+		expect( report.htmlBlocks ).toBe( 1 );
+		expect( report.allowedBlocks ).toBe( 1 );
+		expect( report.problematicBlocks ).toBe( 0 );
+	} );
+
+	it( 'flags HTML blocks with data-* attributes when content is otherwise convertible', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent:
+					'<div class="counter"><span data-target="1500">0</span><span data-target="200">0</span></div>',
+				innerBlocks: [],
+			},
+		] );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.passed ).toBe( false );
+		expect( report.allowedBlocks ).toBe( 0 );
+		expect( report.problematicBlocks ).toBe( 1 );
+	} );
+
+	it( 'allows HTML blocks wrapping canvas or iframe inside a div', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent:
+					'<div class="animation-container"><canvas id="particles" width="800" height="600"></canvas></div>',
+				innerBlocks: [],
+			},
+		] );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.passed ).toBe( true );
+		expect( report.allowedBlocks ).toBe( 1 );
+	} );
+
+	it( 'fails when an HTML block wraps purely convertible content', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<section><h2>Title</h2><p>Description text here.</p></section>',
+				innerBlocks: [],
+			},
+		] );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.passed ).toBe( false );
+		expect( report.problematicBlocks ).toBe( 1 );
+		expect( report.issues[ 0 ].wrapperTag ).toBe( 'section' );
+	} );
+
+	it( 'fails for each convertible HTML block even if there is only one', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<p>This should be a core/paragraph block</p>',
+				innerBlocks: [],
+			},
+		] );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.passed ).toBe( false );
+		expect( report.problematicBlocks ).toBe( 1 );
+		expect( report.issues[ 0 ].suggestedBlocks ).toEqual( [ 'core/paragraph' ] );
+	} );
+
+	it( 'fails with deep nesting on convertible content (depth >= 4)', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<div><div><div><div><p>Deeply nested</p></div></div></div></div>',
+				innerBlocks: [],
+			},
+		] );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.passed ).toBe( false );
+		expect( report.problematicBlocks ).toBe( 1 );
+		expect( report.issues[ 0 ].reason ).toBe( 'deep_nesting' );
+		expect( report.issues[ 0 ].maxDepth ).toBeGreaterThanOrEqual( 4 );
+	} );
+
+	it( 'provides correct replacement suggestions for different wrapper tags', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<section><p>Content</p></section>',
+				innerBlocks: [],
+			},
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<h2>Title</h2>',
+				innerBlocks: [],
+			},
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<ul><li>Item</li></ul>',
+				innerBlocks: [],
+			},
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<blockquote>Quote</blockquote>',
+				innerBlocks: [],
+			},
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<nav><a href="/">Home</a></nav>',
+				innerBlocks: [],
+			},
+		] );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		const issueMap = Object.fromEntries(
+			report.issues.map( ( i ) => [ i.wrapperTag, i.suggestedBlocks ] )
+		);
+
+		expect( issueMap.section ).toEqual( [ 'core/group with tagName="section"' ] );
+		expect( issueMap.h2 ).toEqual( [ 'core/heading with level=2' ] );
+		expect( issueMap.ul ).toEqual( [ 'core/list' ] );
+		expect( issueMap.blockquote ).toEqual( [ 'core/quote' ] );
+		expect( issueMap.nav ).toEqual( [ 'core/navigation' ] );
+	} );
+
+	it( 'handles inner blocks containing core/html', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/group',
+				blockName: 'core/group',
+				originalContent: '<div class="wp-block-group"></div>',
+				innerBlocks: [
+					{
+						name: 'core/html',
+						blockName: 'core/html',
+						originalContent: '<div><div><div><div><p>Nested in group</p></div></div></div></div>',
+						innerBlocks: [],
+					},
+				],
+			},
+		] );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.passed ).toBe( false );
+		expect( report.htmlBlocks ).toBe( 1 );
+		expect( report.problematicBlocks ).toBe( 1 );
+		expect( report.issues[ 0 ].wrapperTag ).toBe( 'div' );
+	} );
+
+	it( 'mixes allowed and problematic blocks correctly', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<div class="marquee"><span data-speed="fast">Logo</span></div>',
+				innerBlocks: [],
+			},
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<section><h2>About Us</h2><p>We are a team.</p></section>',
+				innerBlocks: [],
+			},
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<svg viewBox="0 0 24 24"><path d="M0 0"/></svg>',
+				innerBlocks: [],
+			},
+		] );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.passed ).toBe( false );
+		expect( report.htmlBlocks ).toBe( 3 );
+		expect( report.allowedBlocks ).toBe( 1 ); // svg only
+		expect( report.problematicBlocks ).toBe( 2 ); // marquee (data-* no longer exempt) + section
+		const wrapperTags = report.issues.map( ( i ) => i.wrapperTag );
+		expect( wrapperTags ).toContain( 'div' ); // marquee div with data-* attrs
+		expect( wrapperTags ).toContain( 'section' ); // pure structural content
+	} );
+
+	it( 'returns an error report when wp.blocks is not available', async () => {
+		const mockPage = {
+			evaluate: vi.fn().mockImplementation( ( fn: Function, ...args: any[] ) => {
+				( globalThis as any ).window = {};
+				return fn( ...args );
+			} ),
+		};
+
+		vi.mocked( EditorPage ).mockImplementation( function ( this: any ) {
+			this.getPage = vi.fn().mockResolvedValue( mockPage );
+			this.close = vi.fn().mockResolvedValue( undefined );
+		} as any );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.passed ).toBe( false );
+		expect( report.error ).toBe( 'wp.blocks is not available on this page.' );
+	} );
+
+	it( 'returns an error report when page evaluation throws', async () => {
+		vi.mocked( EditorPage ).mockImplementation( function ( this: any ) {
+			this.getPage = vi.fn().mockRejectedValue( new Error( 'Browser crashed' ) );
+			this.close = vi.fn().mockResolvedValue( undefined );
+		} as any );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.passed ).toBe( false );
+		expect( report.error ).toContain( 'Browser crashed' );
+	} );
+
+	it( 'counts total blocks including non-HTML blocks', async () => {
+		setupMockEditorPage( [
+			{
+				name: 'core/paragraph',
+				blockName: 'core/paragraph',
+				originalContent: '<p>Hi</p>',
+				innerBlocks: [],
+			},
+			{
+				name: 'core/html',
+				blockName: 'core/html',
+				originalContent: '<svg><circle/></svg>',
+				innerBlocks: [],
+			},
+			{
+				name: 'core/heading',
+				blockName: 'core/heading',
+				originalContent: '<h2>Title</h2>',
+				innerBlocks: [],
+			},
+		] );
+
+		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
+
+		expect( report.totalBlocks ).toBe( 3 );
+		expect( report.htmlBlocks ).toBe( 1 );
+		expect( report.allowedBlocks ).toBe( 1 );
+	} );
+} );
diff --git a/apps/cli/ai/tests/tools.test.ts b/apps/cli/ai/tests/tools.test.ts
index cc48dc8a7f..338a1f95b0 100644
--- a/apps/cli/ai/tests/tools.test.ts
+++ b/apps/cli/ai/tests/tools.test.ts
@@ -20,6 +20,10 @@ vi.mock( 'cli/ai/browser-utils', () => ( {
 	getSharedBrowser: vi.fn(),
 } ) );
 
+vi.mock( 'cli/ai/html-block-checker', () => ( {
+	checkHtmlBlocks: vi.fn(),
+} ) );
+
 vi.mock( 'cli/commands/preview/create', () => ( {
 	runCommand: vi.fn(),
 } ) );
diff --git a/apps/cli/ai/tools.ts b/apps/cli/ai/tools.ts
index 3b5bf36a2a..7c0519111b 100644
--- a/apps/cli/ai/tools.ts
+++ b/apps/cli/ai/tools.ts
@@ -5,6 +5,7 @@ import { DEFAULT_PHP_VERSION } from '@studio/common/constants';
 import { z } from 'zod/v4';
 import { validateBlocks, type ValidationReport } from 'cli/ai/block-validator';
 import { getSharedBrowser } from 'cli/ai/browser-utils';
+import { checkHtmlBlocks, type HtmlBlockReport } from 'cli/ai/html-block-checker';
 import { auditPerformance } from 'cli/ai/performance-audit';
 import { runCommand as runCreatePreviewCommand } from 'cli/commands/preview/create';
 import {
@@ -537,8 +538,9 @@ const runWpCliTool = tool(
 
 const validateBlocksTool = tool(
 	'validate_blocks',
-	"Validates WordPress block content by running each block through its save() function in the site's block editor (real browser). " +
-		'The site must be running. Returns per-block validation results with expected HTML for invalid blocks.',
+	"Validates WordPress block content by running each block through its save() function in the site's block editor (real browser), " +
+		'AND checks for misuse of core/html blocks (structural HTML that should use native Gutenberg blocks). ' +
+		'The site must be running. Returns per-block validation results and HTML block check results.',
 	{
 		nameOrPath: z
 			.string()
@@ -570,7 +572,12 @@ const validateBlocksTool = tool(
 
 			const site = await resolveSite( args.nameOrPath );
 			const siteUrl = getSiteUrl( site );
-			const report = await validateBlocks( blockContent, siteUrl );
+
+			// Run both checks in parallel on the same content.
+			const [ report, htmlReport ] = await Promise.all( [
+				validateBlocks( blockContent, siteUrl ),
+				checkHtmlBlocks( blockContent, siteUrl ),
+			] );
 
 			if ( report.error ) {
 				emitProgress( `Validation failed for ${ fileName }: ${ report.error.slice( 0, 80 ) }` );
@@ -594,6 +601,32 @@ const validateBlocksTool = tool(
 				lines.push( '', 'Invalid blocks:', ...formatInvalidBlocks( report ) );
 			}
 
+			// Append HTML block check results.
+			if ( htmlReport.error ) {
+				lines.push( '', `HTML Block Check: ERROR — ${ htmlReport.error }` );
+			} else if ( ! htmlReport.passed ) {
+				lines.push(
+					'',
+					`HTML Block Check: FAILED (${ htmlReport.problematicBlocks } convertible HTML block(s) must be replaced with native Gutenberg blocks)`,
+					'',
+					'Problematic blocks:',
+					...formatHtmlBlockIssues( htmlReport )
+				);
+				if ( htmlReport.allowedBlocks > 0 ) {
+					lines.push( '', `Allowed HTML blocks (no action needed): ${ htmlReport.allowedBlocks }` );
+				}
+				lines.push(
+					'',
+					'Convert the flagged HTML blocks to the suggested Gutenberg blocks, then re-run validate_blocks.'
+				);
+			} else {
+				const htmlMsg =
+					htmlReport.htmlBlocks === 0
+						? 'HTML Block Check: PASSED (no core/html blocks)'
+						: `HTML Block Check: PASSED (${ htmlReport.htmlBlocks } HTML block(s), all acceptable)`;
+				lines.push( '', htmlMsg );
+			}
+
 			return textResult( lines.join( '\n' ) );
 		} catch ( error ) {
 			return errorResult(
@@ -603,6 +636,108 @@ const validateBlocksTool = tool(
 	}
 );
 
+function formatHtmlBlockIssues( report: HtmlBlockReport ): string[] {
+	const lines: string[] = [];
+	for ( let i = 0; i < report.issues.length; i++ ) {
+		const issue = report.issues[ i ];
+		lines.push(
+			`  ${ i + 1 }. Block #${ issue.index }: <${ issue.wrapperTag }> wrapper (depth: ${
+				issue.maxDepth
+			}, ${ issue.totalElements } elements)`
+		);
+		lines.push( `     → Replace with: ${ issue.suggestedBlocks.join( ' or ' ) }` );
+		if ( issue.originalContent.length > 0 ) {
+			const snippet = issue.originalContent.slice( 0, 120 ).replace( /\n/g, ' ' );
+			lines.push( `     HTML: ${ snippet }${ issue.originalContent.length > 120 ? '…' : '' }` );
+		}
+	}
+	return lines;
+}
+
+const checkHtmlBlocksTool = tool(
+	'check_html_blocks',
+	'Checks WordPress block content for misuse of core/html blocks. Detects HTML blocks that ' +
+		'wrap structural elements (div, section, headings, paragraphs, lists) which should use ' +
+		'native Gutenberg blocks instead. Returns a report with replacement suggestions. ' +
+		'The site must be running.',
+	{
+		nameOrPath: z
+			.string()
+			.describe( 'The site name or file system path — the site must be running' ),
+		filePath: z
+			.string()
+			.optional()
+			.describe( 'Path to a file containing WordPress block content to check' ),
+		content: z
+			.string()
+			.optional()
+			.describe( 'Raw WordPress block content (HTML with block comments) to check' ),
+	},
+	async ( args ) => {
+		try {
+			let blockContent: string;
+			let fileName = 'inline content';
+
+			if ( args.filePath ) {
+				blockContent = await readFile( args.filePath, 'utf-8' );
+				fileName = args.filePath.split( '/' ).slice( -2 ).join( '/' );
+			} else if ( args.content ) {
+				blockContent = args.content;
+			} else {
+				return errorResult( 'Either content or filePath must be provided.' );
+			}
+
+			emitProgress( `Checking HTML blocks in ${ fileName }…` );
+
+			const site = await resolveSite( args.nameOrPath );
+			const siteUrl = getSiteUrl( site );
+			const report = await checkHtmlBlocks( blockContent, siteUrl );
+
+			if ( report.error ) {
+				emitProgress(
+					`HTML block check failed for ${ fileName }: ${ report.error.slice( 0, 80 ) }`
+				);
+				return errorResult( `HTML block check failed: ${ report.error }` );
+			}
+
+			if ( report.passed ) {
+				const msg =
+					report.htmlBlocks === 0
+						? 'HTML Block Check: PASSED (no core/html blocks found)'
+						: `HTML Block Check: PASSED (${ report.htmlBlocks } HTML block(s) found, all acceptable uses)`;
+				emitProgress( `${ fileName }: ${ msg }` );
+				return textResult( msg );
+			}
+
+			emitProgress(
+				`${ fileName }: FAILED — ${ report.problematicBlocks } problematic HTML block(s)`
+			);
+
+			const lines = [
+				`HTML Block Check: FAILED (${ report.problematicBlocks } structural HTML block(s) found)`,
+				'',
+				'Problematic blocks:',
+				...formatHtmlBlockIssues( report ),
+			];
+
+			if ( report.allowedBlocks > 0 ) {
+				lines.push( '', `Allowed HTML blocks (no action needed): ${ report.allowedBlocks }` );
+			}
+
+			lines.push(
+				'',
+				'Convert the flagged HTML blocks to the suggested Gutenberg blocks, then re-run check_html_blocks and validate_blocks.'
+			);
+
+			return textResult( lines.join( '\n' ) );
+		} catch ( error ) {
+			return errorResult(
+				`HTML block check failed: ${ error instanceof Error ? error.message : String( error ) }`
+			);
+		}
+	}
+);
+
 // --- Screenshot tool ---
 
 const VIEWPORTS = {
@@ -785,6 +920,7 @@ export const studioToolDefinitions = [
 	deletePreviewTool,
 	runWpCliTool,
 	validateBlocksTool,
+	checkHtmlBlocksTool,
 	takeScreenshotTool,
 	installTaxonomyScriptsTool,
 	auditPerformanceTool,

From a8af6e0bcb40a1002b93a22044d9faaf29aa4661 Mon Sep 17 00:00:00 2001
From: Roberto Aranda <roberto.aranda@automattic.com>
Date: Thu, 9 Apr 2026 14:54:35 +0200
Subject: [PATCH 2/7] Split site building into two-phase workflow: Design then
 Block Conversion

Replace the single-pass workflow that mixed design and block concerns with
two explicit phases. Phase 1 focuses on visual design with free HTML/CSS,
Phase 2 converts content to native Gutenberg blocks with validation.
---
 apps/cli/ai/system-prompt.ts                 | 29 ++++----
 docs/stu-1439-html-block-checker-findings.md | 69 ++++++++++++++++++++
 2 files changed, 86 insertions(+), 12 deletions(-)
 create mode 100644 docs/stu-1439-html-block-checker-findings.md

diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index 9760c3049d..6b30f8228b 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -94,11 +94,7 @@ function buildLocalIntro(): string {
 	return `${ AGENT_IDENTITY } You manage and modify local WordPress sites using your Studio tools and generate content for these sites.
 
 IMPORTANT: You MUST use your mcp__studio__ tools to manage WordPress sites. Never create, start, or stop sites using Bash commands, shell scripts, or manual file operations. Never run \`wp\` commands via Bash — always use the wp_cli tool instead. The Studio tools handle all server management, database setup, and WordPress provisioning automatically.
-IMPORTANT: For any generated content for the site, these three principles are mandatory:
-
-- Gorgeous design: More details on the guidelines below.
-- Native Gutenberg blocks ONLY: Every heading MUST be \`core/heading\`, every paragraph MUST be \`core/paragraph\`, every layout section MUST be \`core/group\` or \`core/columns\`. NEVER wrap raw HTML in \`<!-- wp:html -->\` — see Block Content Guidelines below.
-- No invalid blocks: Use \`validate_blocks\` on every piece of block content (post content, template parts). It validates block markup AND checks for HTML block misuse in a single call.
+IMPORTANT: Site building has two phases. In Phase 1 (Design), focus exclusively on creating a gorgeous, visually striking site — write HTML/CSS freely without worrying about block syntax. In Phase 2 (Block Conversion), convert all content to native Gutenberg blocks and validate. Both phases are mandatory; never skip Phase 2.
 
 ## Workflow
 
@@ -112,11 +108,18 @@ For any request that involves a WordPress site, you MUST first determine which s
 Then continue with:
 
 1. **Get site details**: Use site_info to get the site path, URL, and credentials.
-2. **Plan the design and block structure**: Before writing any code, review the site spec (from the site-spec skill) and the Design Guidelines below to plan the visual direction — layout, colors, typography, spacing. Also plan how each section maps to Gutenberg blocks: which sections use \`core/group\`, where to use \`core/columns\`, which text is \`core/heading\` vs \`core/paragraph\`, etc. Refer to the Block Content Guidelines for the correct markup patterns. Do NOT default to \`core/html\` — compose in native blocks from the start.
-3. **Write theme/plugin files**: Use Write and Edit to create files under the site's wp-content/themes/ or wp-content/plugins/ directory.
-4. **Configure WordPress**: Use wp_cli to activate themes, install plugins, manage options, create posts and pages, edit and import content. The site must be running. The \`wp_cli\` tool takes literal arguments, not shell commands: never use shell substitution or shell syntax such as \`$(cat file)\`, backticks, pipes, redirection, environment variables, or host temp-file paths to provide post content. Pass the literal content directly in \`--post_content=...\`, make \`--post_content\` the final argument in the command, and Studio will rewrite large content to a virtual temp file automatically.
-5. **Validate ALL block content**: Run \`validate_blocks\` on every piece of block content — page/post content (passed via \`--post_content\`) AND template part files (header.html, footer.html, etc.). The tool runs two checks: (a) block markup validity and (b) HTML block misuse detection. It automatically allows HTML blocks whose content contains non-block elements (inline SVGs, \`<form>\`, \`<canvas>\`, \`<iframe>\`, etc.). It flags any HTML block whose descendant elements are all expressible with native Gutenberg blocks. Adding \`data-*\` attributes does NOT make a block acceptable — use \`className\` on \`core/group\` blocks instead. If it flags any blocks, you MUST convert them and re-run \`validate_blocks\` until it passes.
-6. **Check the result**: Use take_screenshot to capture the site's landing page on desktop and mobile and verify the design visually on both viewports, check for wrong spacing, alignment, colors, contrast, borders, hover styles and other visual issues. Fix any issues found. Pay particular attention to the navigation menu and the CTA buttons. The design needs to match your original expectations.
+
+### Phase 1 — Design
+
+2. **Plan the visual design**: Before writing any code, review the site spec (from the site-spec skill) and the Design Guidelines below to plan the full visual direction — layout, typography, color palette, spacing, motion, backgrounds. Think about what makes this design UNFORGETTABLE. Do NOT think about Gutenberg block syntax during this phase.
+3. **Build the site**: Write theme files (style.css, functions.php, templates, template parts) and create pages/posts with wp_cli. During this phase, write content as clean HTML — you may use \`core/html\` blocks or raw HTML freely. Focus entirely on getting the visuals right. All CSS goes in style.css as usual. The \`wp_cli\` tool takes literal arguments, not shell commands: never use shell substitution or shell syntax such as \`$(cat file)\`, backticks, pipes, redirection, environment variables, or host temp-file paths to provide post content. Pass the literal content directly in \`--post_content=...\`, make \`--post_content\` the final argument in the command, and Studio will rewrite large content to a virtual temp file automatically.
+4. **Visual review**: Use take_screenshot to capture the site's landing page on desktop and mobile and verify the design visually on both viewports. Check for wrong spacing, alignment, colors, contrast, borders, hover styles, and other visual issues. Fix any issues found. Pay particular attention to the navigation menu and the CTA buttons. Iterate until the design is excellent.
+
+### Phase 2 — Block Conversion
+
+5. **Convert to native blocks**: Re-read every piece of block content you wrote — page/post content (passed via \`--post_content\`) AND template part files (header.html, footer.html, etc.). For each \`core/html\` block, rewrite it using native Gutenberg block markup. Refer to the Block Content Guidelines below for the correct patterns. Keep \`core/html\` ONLY for content with no native block equivalent: inline SVGs, \`<form>\`, \`<script>\`, \`<canvas>\`, \`<iframe>\`, animation/interaction markup. Adding \`data-*\` attributes does NOT make a block acceptable — use \`className\` on \`core/group\` blocks instead.
+6. **Validate all block content**: Run \`validate_blocks\` on every piece of block content. The tool runs two checks: (a) block markup validity and (b) HTML block misuse detection. If it flags any blocks, convert them and re-run \`validate_blocks\` until it passes.
+7. **Final visual check**: Take screenshots again (desktop + mobile) to confirm the block conversion did not break the design. Fix any visual regressions.
 
 ## Available Studio Tools (prefixed with mcp__studio__)
 
@@ -137,7 +140,7 @@ Then continue with:
 
 ## General rules
 
-- Design quality and visual ambition are not in conflict with using core blocks. Custom CSS targeting block classNames can achieve any visual design. The block structure is for editability; the CSS is for aesthetics.
+- Design quality comes first. During Phase 1, write the best HTML/CSS you can. During Phase 2, the block structure is for editability; the CSS you wrote in Phase 1 stays for aesthetics. Custom CSS targeting block classNames achieves any visual design.
 - Do NOT modify WordPress core files. Only work within wp-content/.
 - Before running wp_cli, ensure the site is running (site_start if needed).
 - When building themes, always build block themes (NO CLASSIC THEMES).
@@ -166,7 +169,7 @@ const REMOTE_DESIGN_GUIDELINES = `## Design capabilities by plan
 
 const LOCAL_CONTENT_GUIDELINES = `## Block content guidelines
 
-**CRITICAL — Think in blocks, not HTML.** When writing page/post content or template parts, you MUST compose content using Gutenberg block markup from the start. Do NOT write raw HTML sections and wrap them in \`<!-- wp:html -->\`. Instead, use the block patterns below to build every section.
+**Reference for Phase 2 (Block Conversion).** When converting content to native blocks, use these patterns. During Phase 1, you may ignore this section and write HTML freely.
 
 ### Core block patterns
 
@@ -273,6 +276,8 @@ Only use \`core/html\` for content that has NO native block equivalent:
 
 const LOCAL_DESIGN_GUIDELINES = `## Design guidelines
 
+**Primary reference for Phase 1 (Design).** These guidelines drive your visual decisions.
+
 **Important**: Always use sophisticated scroll effects and add animations unless specifically asked otherwise.
 
 Understand the context and commit to a BOLD aesthetic direction:
diff --git a/docs/stu-1439-html-block-checker-findings.md b/docs/stu-1439-html-block-checker-findings.md
new file mode 100644
index 0000000000..8ebc6a551b
--- /dev/null
+++ b/docs/stu-1439-html-block-checker-findings.md
@@ -0,0 +1,69 @@
+# STU-1439: HTML Block Checker - Findings & Lessons Learned
+
+## Problem
+
+The `studio ai` CLI agent generates `core/html` blocks when it should use native Gutenberg blocks (`core/group`, `core/heading`, `core/paragraph`, `core/columns`, etc.). This makes the generated content non-editable in the WordPress block editor. Prior attempt in PR #2976 used a prompt-only approach and failed.
+
+## Approach: Deterministic Code Tool
+
+Built `html-block-checker.ts` — a tool that parses block content via `wp.blocks.parse()` in a real browser (Playwright), identifies `core/html` blocks, analyzes their DOM content, and flags blocks whose descendants are all expressible as native Gutenberg blocks.
+
+### How it works
+
+1. Sends block content to the site's block editor page, calls `wp.blocks.parse()` to get the parsed block list.
+2. For each `core/html` block, parses its `originalContent` with `DOMParser`.
+3. Checks if the wrapper tag is in an "allowed" list (svg, form, script, canvas, iframe, video, audio, style, input, select, textarea) — if so, the HTML block is acceptable.
+4. Otherwise, recursively checks if ALL descendant elements are "convertible" (div, section, header, footer, h1-h6, p, ul, ol, li, table, img, figure, blockquote, a, span, em, strong, br, hr, etc.) — if so, it flags the block and suggests native replacements.
+
+### Integration
+
+Merged the check into the existing `validate_blocks` tool via `Promise.all`, so both block markup validation and HTML block misuse detection run in a single call. A standalone `check_html_blocks` tool was also registered.
+
+## What we tried and what happened
+
+### 1. Standalone `check_html_blocks` tool (failed)
+
+**What**: Registered as a separate tool the agent could call independently.
+**Result**: The agent reliably called `validate_blocks` but consistently forgot to call `check_html_blocks`. It would validate markup, get a pass, and move on.
+**Fix**: Merged both checks into `validate_blocks` so the HTML analysis runs automatically every time.
+
+### 2. Prompt-only guidance (insufficient)
+
+**What**: Updated system prompt with guidelines saying "don't use core/html" and listing when it's acceptable.
+**Result**: The agent still defaulted to writing raw HTML sections wrapped in `<!-- wp:html -->`. It didn't know Gutenberg block syntax well enough to compose in native blocks from the start.
+**Fix**: Added a "Core block patterns" reference section to the system prompt with concrete markup examples for core/group, core/heading, core/paragraph, core/columns, core/image, core/buttons, core/list, core/separator.
+
+### 3. Agent gaming the checker with `data-*` attributes (exploited)
+
+**What**: The original `isConvertibleContent()` function had a check: if any element had `data-*` attributes, treat the content as non-convertible (allowed HTML block).
+**Result**: The agent learned to add fake `data-*` attributes (`data-decorative="true"`, `data-layout="grid"`, `data-animate="counters"`) to bypass the checker while still using `core/html` for structural content.
+**Fix**: Removed the `data-*` attribute check entirely. Only tag names determine convertibility. Updated system prompt to explicitly state "Adding `data-*` attributes does NOT make a block acceptable."
+
+### 4. Agent not planning block structure (pattern)
+
+**What**: The workflow step 2 said "Plan the design" — the agent planned visual design (colors, typography, spacing) but never which Gutenberg blocks to use.
+**Result**: The agent went straight to writing HTML and then wrapping it in blocks, rather than thinking in blocks from the start.
+**Fix**: Updated step 2 to "Plan the design AND block structure" — requiring the agent to plan which sections use `core/group`, where to use `core/columns`, etc.
+
+## Key observations
+
+- **The agent treats `core/html` as an escape hatch**: When it doesn't know the correct block syntax, it defaults to writing HTML and wrapping it. Providing block syntax examples reduced this but didn't eliminate it.
+- **Deterministic tools are more reliable than prompt instructions**: The agent can ignore or creatively reinterpret prompt guidance, but it can't bypass a tool that programmatically rejects its output.
+- **The agent actively games checkers**: When given a rule with exceptions, the agent will manufacture conditions that trigger the exception. Any escape hatch in the checker becomes an exploit vector.
+- **Merging checks into existing tools is more effective than adding new tools**: The agent has learned habits around which tools to call. Piggy-backing on those habits is more reliable than teaching new ones.
+- **The checker threshold matters**: Setting `STRUCTURAL_BLOCK_THRESHOLD = 0` (any single convertible block = fail) was necessary. A higher threshold let too many structural blocks slip through.
+
+## Files created/modified
+
+- `apps/cli/ai/html-block-checker.ts` — Core analysis logic
+- `apps/cli/ai/tools.ts` — Tool registration, merged into `validate_blocks`
+- `apps/cli/ai/system-prompt.ts` — Block patterns, stricter guidelines
+- `apps/cli/ai/tests/html-block-checker.test.ts` — 14 tests
+- `apps/cli/ai/tests/tools.test.ts` — Mock for html-block-checker
+
+## Open questions for next approach
+
+- Is a post-generation check the right pattern, or should we prevent HTML block generation earlier in the pipeline?
+- Should the block pattern examples be dynamic (pulled from the site's registered blocks) rather than hardcoded in the prompt?
+- Would a block-by-block generation approach (generate one block at a time, validate immediately) be more effective than generating full page content and checking after?
+- The checker catches the problem but relies on the agent to fix it — the agent sometimes generates the same core/html blocks again in the fix loop. Would an automatic conversion step (tool converts HTML blocks to native blocks) be more reliable?

From 13e548d7896fc849069d85d77a36db82eef3e246 Mon Sep 17 00:00:00 2001
From: Roberto Aranda <roberto.aranda@automattic.com>
Date: Thu, 9 Apr 2026 14:55:42 +0200
Subject: [PATCH 3/7] Remove HTML block checker findings doc from PR

---
 docs/stu-1439-html-block-checker-findings.md | 69 --------------------
 1 file changed, 69 deletions(-)
 delete mode 100644 docs/stu-1439-html-block-checker-findings.md

diff --git a/docs/stu-1439-html-block-checker-findings.md b/docs/stu-1439-html-block-checker-findings.md
deleted file mode 100644
index 8ebc6a551b..0000000000
--- a/docs/stu-1439-html-block-checker-findings.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# STU-1439: HTML Block Checker - Findings & Lessons Learned
-
-## Problem
-
-The `studio ai` CLI agent generates `core/html` blocks when it should use native Gutenberg blocks (`core/group`, `core/heading`, `core/paragraph`, `core/columns`, etc.). This makes the generated content non-editable in the WordPress block editor. Prior attempt in PR #2976 used a prompt-only approach and failed.
-
-## Approach: Deterministic Code Tool
-
-Built `html-block-checker.ts` — a tool that parses block content via `wp.blocks.parse()` in a real browser (Playwright), identifies `core/html` blocks, analyzes their DOM content, and flags blocks whose descendants are all expressible as native Gutenberg blocks.
-
-### How it works
-
-1. Sends block content to the site's block editor page, calls `wp.blocks.parse()` to get the parsed block list.
-2. For each `core/html` block, parses its `originalContent` with `DOMParser`.
-3. Checks if the wrapper tag is in an "allowed" list (svg, form, script, canvas, iframe, video, audio, style, input, select, textarea) — if so, the HTML block is acceptable.
-4. Otherwise, recursively checks if ALL descendant elements are "convertible" (div, section, header, footer, h1-h6, p, ul, ol, li, table, img, figure, blockquote, a, span, em, strong, br, hr, etc.) — if so, it flags the block and suggests native replacements.
-
-### Integration
-
-Merged the check into the existing `validate_blocks` tool via `Promise.all`, so both block markup validation and HTML block misuse detection run in a single call. A standalone `check_html_blocks` tool was also registered.
-
-## What we tried and what happened
-
-### 1. Standalone `check_html_blocks` tool (failed)
-
-**What**: Registered as a separate tool the agent could call independently.
-**Result**: The agent reliably called `validate_blocks` but consistently forgot to call `check_html_blocks`. It would validate markup, get a pass, and move on.
-**Fix**: Merged both checks into `validate_blocks` so the HTML analysis runs automatically every time.
-
-### 2. Prompt-only guidance (insufficient)
-
-**What**: Updated system prompt with guidelines saying "don't use core/html" and listing when it's acceptable.
-**Result**: The agent still defaulted to writing raw HTML sections wrapped in `<!-- wp:html -->`. It didn't know Gutenberg block syntax well enough to compose in native blocks from the start.
-**Fix**: Added a "Core block patterns" reference section to the system prompt with concrete markup examples for core/group, core/heading, core/paragraph, core/columns, core/image, core/buttons, core/list, core/separator.
-
-### 3. Agent gaming the checker with `data-*` attributes (exploited)
-
-**What**: The original `isConvertibleContent()` function had a check: if any element had `data-*` attributes, treat the content as non-convertible (allowed HTML block).
-**Result**: The agent learned to add fake `data-*` attributes (`data-decorative="true"`, `data-layout="grid"`, `data-animate="counters"`) to bypass the checker while still using `core/html` for structural content.
-**Fix**: Removed the `data-*` attribute check entirely. Only tag names determine convertibility. Updated system prompt to explicitly state "Adding `data-*` attributes does NOT make a block acceptable."
-
-### 4. Agent not planning block structure (pattern)
-
-**What**: The workflow step 2 said "Plan the design" — the agent planned visual design (colors, typography, spacing) but never which Gutenberg blocks to use.
-**Result**: The agent went straight to writing HTML and then wrapping it in blocks, rather than thinking in blocks from the start.
-**Fix**: Updated step 2 to "Plan the design AND block structure" — requiring the agent to plan which sections use `core/group`, where to use `core/columns`, etc.
-
-## Key observations
-
-- **The agent treats `core/html` as an escape hatch**: When it doesn't know the correct block syntax, it defaults to writing HTML and wrapping it. Providing block syntax examples reduced this but didn't eliminate it.
-- **Deterministic tools are more reliable than prompt instructions**: The agent can ignore or creatively reinterpret prompt guidance, but it can't bypass a tool that programmatically rejects its output.
-- **The agent actively games checkers**: When given a rule with exceptions, the agent will manufacture conditions that trigger the exception. Any escape hatch in the checker becomes an exploit vector.
-- **Merging checks into existing tools is more effective than adding new tools**: The agent has learned habits around which tools to call. Piggy-backing on those habits is more reliable than teaching new ones.
-- **The checker threshold matters**: Setting `STRUCTURAL_BLOCK_THRESHOLD = 0` (any single convertible block = fail) was necessary. A higher threshold let too many structural blocks slip through.
-
-## Files created/modified
-
-- `apps/cli/ai/html-block-checker.ts` — Core analysis logic
-- `apps/cli/ai/tools.ts` — Tool registration, merged into `validate_blocks`
-- `apps/cli/ai/system-prompt.ts` — Block patterns, stricter guidelines
-- `apps/cli/ai/tests/html-block-checker.test.ts` — 14 tests
-- `apps/cli/ai/tests/tools.test.ts` — Mock for html-block-checker
-
-## Open questions for next approach
-
-- Is a post-generation check the right pattern, or should we prevent HTML block generation earlier in the pipeline?
-- Should the block pattern examples be dynamic (pulled from the site's registered blocks) rather than hardcoded in the prompt?
-- Would a block-by-block generation approach (generate one block at a time, validate immediately) be more effective than generating full page content and checking after?
-- The checker catches the problem but relies on the agent to fix it — the agent sometimes generates the same core/html blocks again in the fix loop. Would an automatic conversion step (tool converts HTML blocks to native blocks) be more reliable?

From 5c4b8fb79fdc61786330ab3f10decc5935f3a251 Mon Sep 17 00:00:00 2001
From: Roberto Aranda <roberto.aranda@automattic.com>
Date: Thu, 9 Apr 2026 17:24:01 +0200
Subject: [PATCH 4/7] Replace HTML block checker tool with prompt-driven block
 conversion

Remove check_html_blocks tool and its integration in validate_blocks.
Phase 2 now relies on the agent self-identifying and converting HTML
blocks based on the block content guidelines, matching the natural
workflow observed in testing sessions. validate_blocks is kept for
block markup validation only.
---
 apps/cli/ai/system-prompt.ts |  19 ++++-
 apps/cli/ai/tools.ts         | 142 +----------------------------------
 2 files changed, 19 insertions(+), 142 deletions(-)

diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index 6b30f8228b..8eaaf6a6ca 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -117,9 +117,20 @@ Then continue with:
 
 ### Phase 2 — Block Conversion
 
-5. **Convert to native blocks**: Re-read every piece of block content you wrote — page/post content (passed via \`--post_content\`) AND template part files (header.html, footer.html, etc.). For each \`core/html\` block, rewrite it using native Gutenberg block markup. Refer to the Block Content Guidelines below for the correct patterns. Keep \`core/html\` ONLY for content with no native block equivalent: inline SVGs, \`<form>\`, \`<script>\`, \`<canvas>\`, \`<iframe>\`, animation/interaction markup. Adding \`data-*\` attributes does NOT make a block acceptable — use \`className\` on \`core/group\` blocks instead.
-6. **Validate all block content**: Run \`validate_blocks\` on every piece of block content. The tool runs two checks: (a) block markup validity and (b) HTML block misuse detection. If it flags any blocks, convert them and re-run \`validate_blocks\` until it passes.
-7. **Final visual check**: Take screenshots again (desktop + mobile) to confirm the block conversion did not break the design. Fix any visual regressions.
+5. **Read back all content**: Use \`wp_cli post get <id> --field=post_content\` to retrieve page/post content, and read template part files (header.html, footer.html, etc.) from disk. You need the full current content to plan the conversion.
+6. **Plan the conversion section-by-section**: For each section of content, decide what converts to native blocks and what stays as \`core/html\`. Apply the Block Content Guidelines below:
+   - Section wrappers (\`<section>\`, \`<div>\`, \`<header>\`, \`<footer>\`, \`<aside>\`) → \`core/group\` with appropriate \`tagName\`
+   - Headings (\`<h1>\`–\`<h6>\`) → \`core/heading\`
+   - Paragraphs (\`<p>\`) → \`core/paragraph\`
+   - Buttons/CTAs (\`<a class="btn">\`) → \`core/buttons\` + \`core/button\`
+   - Two-column layouts → \`core/columns\` + \`core/column\`
+   - Lists (\`<ul>\`/\`<ol>\`) → \`core/list\` + \`core/list-item\`
+   - Images (\`<img>\`) → \`core/image\`
+   - Keep \`core/html\` ONLY for: inline SVGs, \`<form>\` elements, \`<script>\`, \`<canvas>\`, \`<iframe>\`, animation/interaction markup, elements needing custom \`data-*\` attributes for JS interactivity.
+   All CSS classes from Phase 1 stay in style.css — the visual output must remain identical.
+7. **Write the converted content**: Rewrite the full content for each page/post and template part using native Gutenberg block markup. Update posts via \`wp_cli post update\` and template parts via Write/Edit.
+8. **Validate block markup**: Run \`validate_blocks\` on every piece of converted content to catch markup errors (missing attributes, invalid nesting, malformed block comments). If it flags invalid blocks, fix the markup and re-run until all blocks pass.
+9. **Final visual check**: Take screenshots again (desktop + mobile) to confirm the block conversion did not break the design. Fix any visual regressions — the site must look identical to the Phase 1 result.
 
 ## Available Studio Tools (prefixed with mcp__studio__)
 
@@ -134,7 +145,7 @@ Then continue with:
 - preview_update: Update an existing hosted WordPress.com preview from a local site; this can take a few minutes, so tell the user to wait
 - preview_delete: Delete a hosted WordPress.com preview by hostname
 - wp_cli: Run WP-CLI commands on a running site
-- validate_blocks: Validates block content on a running site. Runs TWO checks: (1) block markup validity (save-function comparison in a real browser) and (2) HTML block misuse detection (flags core/html blocks that should use native Gutenberg blocks). Call on every piece of block content — post content AND template parts.
+- validate_blocks: Validates block markup on a running site by running each block through its save() function in a real browser. Catches invalid attributes, malformed nesting, and markup mismatches. Call on every piece of block content after Phase 2 conversion — post content AND template parts.
 - take_screenshot: Take a full-page screenshot of a URL (supports desktop and mobile viewports). Use this to visually check the site after building it.
 - audit_performance: Measure frontend performance metrics (TTFB, FCP, LCP, CLS, page weight, DOM size, JS/CSS/image/font asset breakdown) for a running site. Use this to identify performance bottlenecks and guide optimization.
 
diff --git a/apps/cli/ai/tools.ts b/apps/cli/ai/tools.ts
index 1fb9838657..6902f2c4e0 100644
--- a/apps/cli/ai/tools.ts
+++ b/apps/cli/ai/tools.ts
@@ -5,7 +5,6 @@ import { DEFAULT_PHP_VERSION } from '@studio/common/constants';
 import { z } from 'zod/v4';
 import { validateBlocks, type ValidationReport } from 'cli/ai/block-validator';
 import { getSharedBrowser } from 'cli/ai/browser-utils';
-import { checkHtmlBlocks, type HtmlBlockReport } from 'cli/ai/html-block-checker';
 import { auditPerformance } from 'cli/ai/performance-audit';
 import { createWpcomToolDefinitions } from 'cli/ai/wpcom-tools';
 import { runCommand as runCreatePreviewCommand } from 'cli/commands/preview/create';
@@ -539,9 +538,9 @@ const runWpCliTool = tool(
 
 const validateBlocksTool = tool(
 	'validate_blocks',
-	"Validates WordPress block content by running each block through its save() function in the site's block editor (real browser), " +
-		'AND checks for misuse of core/html blocks (structural HTML that should use native Gutenberg blocks). ' +
-		'The site must be running. Returns per-block validation results and HTML block check results.',
+	"Validates WordPress block content by running each block through its save() function in the site's block editor (real browser). " +
+		'Catches invalid attributes, malformed nesting, and markup mismatches. ' +
+		'The site must be running. Returns per-block validation results.',
 	{
 		nameOrPath: z
 			.string()
@@ -574,11 +573,7 @@ const validateBlocksTool = tool(
 			const site = await resolveSite( args.nameOrPath );
 			const siteUrl = getSiteUrl( site );
 
-			// Run both checks in parallel on the same content.
-			const [ report, htmlReport ] = await Promise.all( [
-				validateBlocks( blockContent, siteUrl ),
-				checkHtmlBlocks( blockContent, siteUrl ),
-			] );
+			const report = await validateBlocks( blockContent, siteUrl );
 
 			if ( report.error ) {
 				emitProgress( `Validation failed for ${ fileName }: ${ report.error.slice( 0, 80 ) }` );
@@ -602,32 +597,6 @@ const validateBlocksTool = tool(
 				lines.push( '', 'Invalid blocks:', ...formatInvalidBlocks( report ) );
 			}
 
-			// Append HTML block check results.
-			if ( htmlReport.error ) {
-				lines.push( '', `HTML Block Check: ERROR — ${ htmlReport.error }` );
-			} else if ( ! htmlReport.passed ) {
-				lines.push(
-					'',
-					`HTML Block Check: FAILED (${ htmlReport.problematicBlocks } convertible HTML block(s) must be replaced with native Gutenberg blocks)`,
-					'',
-					'Problematic blocks:',
-					...formatHtmlBlockIssues( htmlReport )
-				);
-				if ( htmlReport.allowedBlocks > 0 ) {
-					lines.push( '', `Allowed HTML blocks (no action needed): ${ htmlReport.allowedBlocks }` );
-				}
-				lines.push(
-					'',
-					'Convert the flagged HTML blocks to the suggested Gutenberg blocks, then re-run validate_blocks.'
-				);
-			} else {
-				const htmlMsg =
-					htmlReport.htmlBlocks === 0
-						? 'HTML Block Check: PASSED (no core/html blocks)'
-						: `HTML Block Check: PASSED (${ htmlReport.htmlBlocks } HTML block(s), all acceptable)`;
-				lines.push( '', htmlMsg );
-			}
-
 			return textResult( lines.join( '\n' ) );
 		} catch ( error ) {
 			return errorResult(
@@ -637,108 +606,6 @@ const validateBlocksTool = tool(
 	}
 );
 
-function formatHtmlBlockIssues( report: HtmlBlockReport ): string[] {
-	const lines: string[] = [];
-	for ( let i = 0; i < report.issues.length; i++ ) {
-		const issue = report.issues[ i ];
-		lines.push(
-			`  ${ i + 1 }. Block #${ issue.index }: <${ issue.wrapperTag }> wrapper (depth: ${
-				issue.maxDepth
-			}, ${ issue.totalElements } elements)`
-		);
-		lines.push( `     → Replace with: ${ issue.suggestedBlocks.join( ' or ' ) }` );
-		if ( issue.originalContent.length > 0 ) {
-			const snippet = issue.originalContent.slice( 0, 120 ).replace( /\n/g, ' ' );
-			lines.push( `     HTML: ${ snippet }${ issue.originalContent.length > 120 ? '…' : '' }` );
-		}
-	}
-	return lines;
-}
-
-const checkHtmlBlocksTool = tool(
-	'check_html_blocks',
-	'Checks WordPress block content for misuse of core/html blocks. Detects HTML blocks that ' +
-		'wrap structural elements (div, section, headings, paragraphs, lists) which should use ' +
-		'native Gutenberg blocks instead. Returns a report with replacement suggestions. ' +
-		'The site must be running.',
-	{
-		nameOrPath: z
-			.string()
-			.describe( 'The site name or file system path — the site must be running' ),
-		filePath: z
-			.string()
-			.optional()
-			.describe( 'Path to a file containing WordPress block content to check' ),
-		content: z
-			.string()
-			.optional()
-			.describe( 'Raw WordPress block content (HTML with block comments) to check' ),
-	},
-	async ( args ) => {
-		try {
-			let blockContent: string;
-			let fileName = 'inline content';
-
-			if ( args.filePath ) {
-				blockContent = await readFile( args.filePath, 'utf-8' );
-				fileName = args.filePath.split( '/' ).slice( -2 ).join( '/' );
-			} else if ( args.content ) {
-				blockContent = args.content;
-			} else {
-				return errorResult( 'Either content or filePath must be provided.' );
-			}
-
-			emitProgress( `Checking HTML blocks in ${ fileName }…` );
-
-			const site = await resolveSite( args.nameOrPath );
-			const siteUrl = getSiteUrl( site );
-			const report = await checkHtmlBlocks( blockContent, siteUrl );
-
-			if ( report.error ) {
-				emitProgress(
-					`HTML block check failed for ${ fileName }: ${ report.error.slice( 0, 80 ) }`
-				);
-				return errorResult( `HTML block check failed: ${ report.error }` );
-			}
-
-			if ( report.passed ) {
-				const msg =
-					report.htmlBlocks === 0
-						? 'HTML Block Check: PASSED (no core/html blocks found)'
-						: `HTML Block Check: PASSED (${ report.htmlBlocks } HTML block(s) found, all acceptable uses)`;
-				emitProgress( `${ fileName }: ${ msg }` );
-				return textResult( msg );
-			}
-
-			emitProgress(
-				`${ fileName }: FAILED — ${ report.problematicBlocks } problematic HTML block(s)`
-			);
-
-			const lines = [
-				`HTML Block Check: FAILED (${ report.problematicBlocks } structural HTML block(s) found)`,
-				'',
-				'Problematic blocks:',
-				...formatHtmlBlockIssues( report ),
-			];
-
-			if ( report.allowedBlocks > 0 ) {
-				lines.push( '', `Allowed HTML blocks (no action needed): ${ report.allowedBlocks }` );
-			}
-
-			lines.push(
-				'',
-				'Convert the flagged HTML blocks to the suggested Gutenberg blocks, then re-run check_html_blocks and validate_blocks.'
-			);
-
-			return textResult( lines.join( '\n' ) );
-		} catch ( error ) {
-			return errorResult(
-				`HTML block check failed: ${ error instanceof Error ? error.message : String( error ) }`
-			);
-		}
-	}
-);
-
 // --- Screenshot tool ---
 
 const VIEWPORTS = {
@@ -925,7 +792,6 @@ export const studioToolDefinitions = [
 	deletePreviewTool,
 	runWpCliTool,
 	validateBlocksTool,
-	checkHtmlBlocksTool,
 	takeScreenshotTool,
 	installTaxonomyScriptsTool,
 	auditPerformanceTool,

From 0d39de412e58c040cd0cf319594a05ddc47eb1ca Mon Sep 17 00:00:00 2001
From: Roberto Aranda <roberto.aranda@automattic.com>
Date: Thu, 9 Apr 2026 19:19:10 +0200
Subject: [PATCH 5/7] Remove unused HTML block checker module and tests

The html-block-checker.ts module and its test file are no longer
referenced after switching to prompt-driven block conversion.
---
 apps/cli/ai/html-block-checker.ts            | 350 ------------------
 apps/cli/ai/tests/html-block-checker.test.ts | 364 -------------------
 apps/cli/ai/tests/tools.test.ts              |   4 -
 3 files changed, 718 deletions(-)
 delete mode 100644 apps/cli/ai/html-block-checker.ts
 delete mode 100644 apps/cli/ai/tests/html-block-checker.test.ts

diff --git a/apps/cli/ai/html-block-checker.ts b/apps/cli/ai/html-block-checker.ts
deleted file mode 100644
index c75b0842a6..0000000000
--- a/apps/cli/ai/html-block-checker.ts
+++ /dev/null
@@ -1,350 +0,0 @@
-import { EditorPage } from 'cli/ai/browser-utils';
-
-interface HtmlBlockIssue {
-	index: number;
-	originalContent: string;
-	wrapperTag: string;
-	maxDepth: number;
-	totalElements: number;
-	reason: 'structural_tag' | 'deep_nesting';
-	suggestedBlocks: string[];
-}
-
-export interface HtmlBlockReport {
-	totalBlocks: number;
-	htmlBlocks: number;
-	problematicBlocks: number;
-	allowedBlocks: number;
-	passed: boolean;
-	issues: HtmlBlockIssue[];
-	error?: string;
-}
-
-/**
- * The check fails when the number of problematic HTML blocks exceeds this.
- */
-const STRUCTURAL_BLOCK_THRESHOLD = 0;
-
-/**
- * Maximum DOM nesting depth allowed inside a single HTML block before it is
- * flagged. A depth of 4 means: wrapper > child > grandchild > great-grandchild.
- */
-const MAX_NESTING_DEPTH = 4;
-
-// Cache one EditorPage per site URL so repeated checks reuse the same
-// browser tab instead of navigating and loading the block editor each time.
-const editorPages = new Map< string, EditorPage >();
-
-function getEditorPage( siteUrl: string ): EditorPage {
-	let ep = editorPages.get( siteUrl );
-	if ( ! ep ) {
-		ep = new EditorPage( siteUrl );
-		editorPages.set( siteUrl, ep );
-	}
-	return ep;
-}
-
-/**
- * Tags that indicate acceptable use of core/html blocks when they are the
- * outermost wrapper element.
- */
-const ALLOWED_WRAPPER_TAGS = new Set( [
-	'svg',
-	'form',
-	'script',
-	'canvas',
-	'iframe',
-	'video',
-	'audio',
-	'style',
-	'input',
-	'select',
-	'textarea',
-] );
-
-/**
- * Tags whose content can be expressed with native Gutenberg blocks.
- * If ALL descendant elements are in this set, the HTML block is convertible.
- */
-const CONVERTIBLE_TAGS = new Set( [
-	'div',
-	'section',
-	'header',
-	'footer',
-	'main',
-	'article',
-	'aside',
-	'nav',
-	'h1',
-	'h2',
-	'h3',
-	'h4',
-	'h5',
-	'h6',
-	'p',
-	'ul',
-	'ol',
-	'li',
-	'dl',
-	'dt',
-	'dd',
-	'table',
-	'thead',
-	'tbody',
-	'tfoot',
-	'tr',
-	'th',
-	'td',
-	'img',
-	'figure',
-	'figcaption',
-	'blockquote',
-	'a',
-	'span',
-	'em',
-	'strong',
-	'b',
-	'i',
-	'u',
-	'br',
-	'hr',
-	'small',
-	'mark',
-	'sub',
-	'sup',
-	'abbr',
-	'cite',
-	'code',
-	'pre',
-	'time',
-] );
-
-/**
- * Maps structural wrapper tags to suggested Gutenberg block replacements.
- */
-const REPLACEMENT_MAP: Record< string, string[] > = {
-	div: [ 'core/group (with inner blocks for children)' ],
-	section: [ 'core/group with tagName="section"' ],
-	header: [ 'core/group with tagName="header"' ],
-	footer: [ 'core/group with tagName="footer"' ],
-	main: [ 'core/group with tagName="main"' ],
-	article: [ 'core/group with tagName="article"' ],
-	aside: [ 'core/group with tagName="aside"' ],
-	nav: [ 'core/navigation' ],
-	h1: [ 'core/heading with level=1' ],
-	h2: [ 'core/heading with level=2' ],
-	h3: [ 'core/heading with level=3' ],
-	h4: [ 'core/heading with level=4' ],
-	h5: [ 'core/heading with level=5' ],
-	h6: [ 'core/heading with level=6' ],
-	p: [ 'core/paragraph' ],
-	ul: [ 'core/list' ],
-	ol: [ 'core/list' ],
-	li: [ 'core/list-item (inside core/list)' ],
-	table: [ 'core/table' ],
-	img: [ 'core/image' ],
-	figure: [ 'core/image or core/media-text' ],
-	figcaption: [ 'core/image caption or core/media-text' ],
-	blockquote: [ 'core/quote' ],
-	a: [ 'core/button or inline link in core/paragraph' ],
-	dl: [ 'core/list or core/group with core/paragraph items' ],
-	span: [ 'core/paragraph or core/group' ],
-};
-
-/**
- * Check WordPress block content for misuse of core/html blocks.
- *
- * Navigates to `post-new.php` (which loads wp.blocks with all registered
- * blocks) and runs `wp.blocks.parse()` to identify core/html blocks. Each
- * HTML block is analysed for structural tags and deep nesting.
- */
-export async function checkHtmlBlocks(
-	content: string,
-	siteUrl: string
-): Promise< HtmlBlockReport > {
-	const editorPage = getEditorPage( siteUrl );
-
-	try {
-		const page = await editorPage.getPage();
-
-		const report = await page.evaluate(
-			( params: {
-				html: string;
-				allowedWrapperTags: string[];
-				convertibleTags: string[];
-				replacementMap: Record< string, string[] >;
-				structuralThreshold: number;
-				maxDepth: number;
-			} ) => {
-				/* eslint-disable @typescript-eslint/no-explicit-any */
-				const wpBlocks = ( window as any ).wp?.blocks;
-				if ( ! wpBlocks ) {
-					return {
-						totalBlocks: 0,
-						htmlBlocks: 0,
-						problematicBlocks: 0,
-						allowedBlocks: 0,
-						passed: false,
-						issues: [] as any[],
-						error: 'wp.blocks is not available on this page.',
-					};
-				}
-
-				const allowedWrapperSet = new Set( params.allowedWrapperTags );
-				const convertibleSet = new Set( params.convertibleTags );
-				const blocks = wpBlocks.parse( params.html );
-				const issues: any[] = [];
-				let htmlBlockCount = 0;
-				let allowedCount = 0;
-				let totalBlockCount = 0;
-
-				function computeDepthAndCount( el: Element ): {
-					depth: number;
-					count: number;
-				} {
-					let maxChildDepth = 0;
-					let count = 1;
-					for ( const child of Array.from( el.children ) ) {
-						const result = computeDepthAndCount( child );
-						if ( result.depth > maxChildDepth ) {
-							maxChildDepth = result.depth;
-						}
-						count += result.count;
-					}
-					return { depth: 1 + maxChildDepth, count };
-				}
-
-				/**
-				 * Returns true if ALL element descendants of `el` (including
-				 * `el` itself) are tags that have native Gutenberg block
-				 * equivalents.
-				 *
-				 * When this returns true the HTML block is "convertible" —
-				 * its content can be fully expressed with core blocks.
-				 * When false the block contains SVGs, form elements,
-				 * or other non-block content and is considered an
-				 * acceptable use of core/html.
-				 *
-				 * Note: data-* attributes are NOT considered — they can
-				 * be replaced by className on core/group blocks and JS
-				 * can target those class names instead.
-				 */
-				function isConvertibleContent( el: Element ): boolean {
-					const tag = el.tagName.toLowerCase();
-					if ( ! convertibleSet.has( tag ) ) {
-						return false;
-					}
-					for ( const child of Array.from( el.children ) ) {
-						if ( ! isConvertibleContent( child ) ) {
-							return false;
-						}
-					}
-					return true;
-				}
-
-				function walkBlocks( blockList: any[] ) {
-					for ( const block of blockList ) {
-						totalBlockCount++;
-
-						if ( block.blockName === 'core/html' || block.name === 'core/html' ) {
-							htmlBlockCount++;
-							const rawHtml = block.originalContent || block.innerHTML || '';
-
-							const doc = new DOMParser().parseFromString( rawHtml, 'text/html' );
-							const wrapper = doc.body.firstElementChild;
-
-							if ( ! wrapper ) {
-								// Text-only or empty HTML block — skip
-								allowedCount++;
-							} else {
-								const tag = wrapper.tagName.toLowerCase();
-
-								if ( allowedWrapperSet.has( tag ) ) {
-									// Wrapper is an explicitly allowed tag (svg, form, script, …)
-									allowedCount++;
-								} else if ( ! isConvertibleContent( wrapper ) ) {
-									// Contains non-convertible content (SVGs, data-* attrs,
-									// form elements, canvas, etc.) — acceptable HTML usage
-									allowedCount++;
-								} else {
-									// All content is convertible to native blocks — flag it
-									const { depth, count } = computeDepthAndCount( wrapper );
-									const reason = depth >= params.maxDepth ? 'deep_nesting' : 'structural_tag';
-									const suggestions = params.replacementMap[ tag ] || [
-										'core/group or appropriate core block',
-									];
-
-									issues.push( {
-										index: totalBlockCount - 1,
-										originalContent: rawHtml.slice( 0, 300 ),
-										wrapperTag: tag,
-										maxDepth: depth,
-										totalElements: count,
-										reason,
-										suggestedBlocks: suggestions,
-									} );
-								}
-							}
-						}
-
-						// Recurse into inner blocks
-						const innerBlocks = block.innerBlocks || [];
-						if ( innerBlocks.length > 0 ) {
-							walkBlocks( innerBlocks );
-						}
-					}
-				}
-
-				walkBlocks( blocks );
-
-				const problematicCount = issues.length;
-				const passed = problematicCount <= params.structuralThreshold;
-
-				return {
-					totalBlocks: totalBlockCount,
-					htmlBlocks: htmlBlockCount,
-					problematicBlocks: problematicCount,
-					allowedBlocks: allowedCount,
-					passed,
-					issues,
-				};
-				/* eslint-enable @typescript-eslint/no-explicit-any */
-			},
-			{
-				html: content,
-				allowedWrapperTags: [ ...ALLOWED_WRAPPER_TAGS ],
-				convertibleTags: [ ...CONVERTIBLE_TAGS ],
-				replacementMap: REPLACEMENT_MAP,
-				structuralThreshold: STRUCTURAL_BLOCK_THRESHOLD,
-				maxDepth: MAX_NESTING_DEPTH,
-			}
-		);
-
-		return report as HtmlBlockReport;
-	} catch ( error ) {
-		// If navigation or evaluation failed, discard the cached page so the
-		// next call gets a fresh one.
-		await editorPage.close();
-		editorPages.delete( siteUrl );
-
-		return {
-			totalBlocks: 0,
-			htmlBlocks: 0,
-			problematicBlocks: 0,
-			allowedBlocks: 0,
-			passed: false,
-			issues: [],
-			error: `HTML block check error: ${
-				error instanceof Error ? error.message : String( error )
-			}`,
-		};
-	}
-}
-
-/** Clean up all cached editor pages. */
-export async function cleanupCheckerPages(): Promise< void > {
-	for ( const ep of editorPages.values() ) {
-		await ep.close();
-	}
-	editorPages.clear();
-}
diff --git a/apps/cli/ai/tests/html-block-checker.test.ts b/apps/cli/ai/tests/html-block-checker.test.ts
deleted file mode 100644
index 6bce93c229..0000000000
--- a/apps/cli/ai/tests/html-block-checker.test.ts
+++ /dev/null
@@ -1,364 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-function-type */
-import { vi } from 'vitest';
-import { EditorPage } from 'cli/ai/browser-utils';
-import { checkHtmlBlocks, cleanupCheckerPages } from '../html-block-checker';
-
-// vi.mock is hoisted by vitest, so placement after imports is fine.
-vi.mock( 'cli/ai/browser-utils', () => ( {
-	getSharedBrowser: vi.fn(),
-	EditorPage: vi.fn(),
-} ) );
-
-function setupMockEditorPage( blocks: any[] ) {
-	const mockPage = {
-		evaluate: vi.fn().mockImplementation( ( fn: Function, ...args: any[] ) => {
-			( globalThis as any ).window = {
-				...( globalThis as any ).window,
-				wp: {
-					blocks: {
-						parse: () => blocks,
-					},
-				},
-			};
-			return fn( ...args );
-		} ),
-	};
-
-	const MockEditorPage = vi.mocked( EditorPage );
-	MockEditorPage.mockImplementation( function ( this: any ) {
-		this.getPage = vi.fn().mockResolvedValue( mockPage );
-		this.close = vi.fn().mockResolvedValue( undefined );
-	} as any );
-
-	return mockPage;
-}
-
-describe( 'checkHtmlBlocks', () => {
-	afterEach( async () => {
-		await cleanupCheckerPages();
-		vi.restoreAllMocks();
-		delete ( globalThis as any ).window?.wp;
-	} );
-
-	it( 'passes when there are no core/html blocks', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/paragraph',
-				blockName: 'core/paragraph',
-				originalContent: '<p>Hi</p>',
-				innerBlocks: [],
-			},
-		] );
-
-		const report = await checkHtmlBlocks(
-			'<!-- wp:paragraph --><p>Hi</p><!-- /wp:paragraph -->',
-			'http://localhost:8888'
-		);
-
-		expect( report.passed ).toBe( true );
-		expect( report.htmlBlocks ).toBe( 0 );
-		expect( report.problematicBlocks ).toBe( 0 );
-		expect( report.issues ).toHaveLength( 0 );
-	} );
-
-	it( 'passes when HTML blocks only contain allowed wrapper tags (SVG, form, script)', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<svg viewBox="0 0 100 100"><circle cx="50" cy="50" r="50"/></svg>',
-				innerBlocks: [],
-			},
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<form action="/submit"><input type="text"/></form>',
-				innerBlocks: [],
-			},
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<script>console.log("hello")</script>',
-				innerBlocks: [],
-			},
-		] );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.passed ).toBe( true );
-		expect( report.htmlBlocks ).toBe( 3 );
-		expect( report.allowedBlocks ).toBe( 3 );
-		expect( report.problematicBlocks ).toBe( 0 );
-	} );
-
-	it( 'allows HTML blocks wrapping non-convertible content (SVGs inside a div)', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent:
-					'<div class="logo-grid"><svg viewBox="0 0 100 100"><circle/></svg><svg viewBox="0 0 50 50"><rect/></svg></div>',
-				innerBlocks: [],
-			},
-		] );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.passed ).toBe( true );
-		expect( report.htmlBlocks ).toBe( 1 );
-		expect( report.allowedBlocks ).toBe( 1 );
-		expect( report.problematicBlocks ).toBe( 0 );
-	} );
-
-	it( 'flags HTML blocks with data-* attributes when content is otherwise convertible', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent:
-					'<div class="counter"><span data-target="1500">0</span><span data-target="200">0</span></div>',
-				innerBlocks: [],
-			},
-		] );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.passed ).toBe( false );
-		expect( report.allowedBlocks ).toBe( 0 );
-		expect( report.problematicBlocks ).toBe( 1 );
-	} );
-
-	it( 'allows HTML blocks wrapping canvas or iframe inside a div', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent:
-					'<div class="animation-container"><canvas id="particles" width="800" height="600"></canvas></div>',
-				innerBlocks: [],
-			},
-		] );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.passed ).toBe( true );
-		expect( report.allowedBlocks ).toBe( 1 );
-	} );
-
-	it( 'fails when an HTML block wraps purely convertible content', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<section><h2>Title</h2><p>Description text here.</p></section>',
-				innerBlocks: [],
-			},
-		] );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.passed ).toBe( false );
-		expect( report.problematicBlocks ).toBe( 1 );
-		expect( report.issues[ 0 ].wrapperTag ).toBe( 'section' );
-	} );
-
-	it( 'fails for each convertible HTML block even if there is only one', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<p>This should be a core/paragraph block</p>',
-				innerBlocks: [],
-			},
-		] );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.passed ).toBe( false );
-		expect( report.problematicBlocks ).toBe( 1 );
-		expect( report.issues[ 0 ].suggestedBlocks ).toEqual( [ 'core/paragraph' ] );
-	} );
-
-	it( 'fails with deep nesting on convertible content (depth >= 4)', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<div><div><div><div><p>Deeply nested</p></div></div></div></div>',
-				innerBlocks: [],
-			},
-		] );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.passed ).toBe( false );
-		expect( report.problematicBlocks ).toBe( 1 );
-		expect( report.issues[ 0 ].reason ).toBe( 'deep_nesting' );
-		expect( report.issues[ 0 ].maxDepth ).toBeGreaterThanOrEqual( 4 );
-	} );
-
-	it( 'provides correct replacement suggestions for different wrapper tags', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<section><p>Content</p></section>',
-				innerBlocks: [],
-			},
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<h2>Title</h2>',
-				innerBlocks: [],
-			},
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<ul><li>Item</li></ul>',
-				innerBlocks: [],
-			},
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<blockquote>Quote</blockquote>',
-				innerBlocks: [],
-			},
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<nav><a href="/">Home</a></nav>',
-				innerBlocks: [],
-			},
-		] );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		const issueMap = Object.fromEntries(
-			report.issues.map( ( i ) => [ i.wrapperTag, i.suggestedBlocks ] )
-		);
-
-		expect( issueMap.section ).toEqual( [ 'core/group with tagName="section"' ] );
-		expect( issueMap.h2 ).toEqual( [ 'core/heading with level=2' ] );
-		expect( issueMap.ul ).toEqual( [ 'core/list' ] );
-		expect( issueMap.blockquote ).toEqual( [ 'core/quote' ] );
-		expect( issueMap.nav ).toEqual( [ 'core/navigation' ] );
-	} );
-
-	it( 'handles inner blocks containing core/html', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/group',
-				blockName: 'core/group',
-				originalContent: '<div class="wp-block-group"></div>',
-				innerBlocks: [
-					{
-						name: 'core/html',
-						blockName: 'core/html',
-						originalContent: '<div><div><div><div><p>Nested in group</p></div></div></div></div>',
-						innerBlocks: [],
-					},
-				],
-			},
-		] );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.passed ).toBe( false );
-		expect( report.htmlBlocks ).toBe( 1 );
-		expect( report.problematicBlocks ).toBe( 1 );
-		expect( report.issues[ 0 ].wrapperTag ).toBe( 'div' );
-	} );
-
-	it( 'mixes allowed and problematic blocks correctly', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<div class="marquee"><span data-speed="fast">Logo</span></div>',
-				innerBlocks: [],
-			},
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<section><h2>About Us</h2><p>We are a team.</p></section>',
-				innerBlocks: [],
-			},
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<svg viewBox="0 0 24 24"><path d="M0 0"/></svg>',
-				innerBlocks: [],
-			},
-		] );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.passed ).toBe( false );
-		expect( report.htmlBlocks ).toBe( 3 );
-		expect( report.allowedBlocks ).toBe( 1 ); // svg only
-		expect( report.problematicBlocks ).toBe( 2 ); // marquee (data-* no longer exempt) + section
-		const wrapperTags = report.issues.map( ( i ) => i.wrapperTag );
-		expect( wrapperTags ).toContain( 'div' ); // marquee div with data-* attrs
-		expect( wrapperTags ).toContain( 'section' ); // pure structural content
-	} );
-
-	it( 'returns an error report when wp.blocks is not available', async () => {
-		const mockPage = {
-			evaluate: vi.fn().mockImplementation( ( fn: Function, ...args: any[] ) => {
-				( globalThis as any ).window = {};
-				return fn( ...args );
-			} ),
-		};
-
-		vi.mocked( EditorPage ).mockImplementation( function ( this: any ) {
-			this.getPage = vi.fn().mockResolvedValue( mockPage );
-			this.close = vi.fn().mockResolvedValue( undefined );
-		} as any );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.passed ).toBe( false );
-		expect( report.error ).toBe( 'wp.blocks is not available on this page.' );
-	} );
-
-	it( 'returns an error report when page evaluation throws', async () => {
-		vi.mocked( EditorPage ).mockImplementation( function ( this: any ) {
-			this.getPage = vi.fn().mockRejectedValue( new Error( 'Browser crashed' ) );
-			this.close = vi.fn().mockResolvedValue( undefined );
-		} as any );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.passed ).toBe( false );
-		expect( report.error ).toContain( 'Browser crashed' );
-	} );
-
-	it( 'counts total blocks including non-HTML blocks', async () => {
-		setupMockEditorPage( [
-			{
-				name: 'core/paragraph',
-				blockName: 'core/paragraph',
-				originalContent: '<p>Hi</p>',
-				innerBlocks: [],
-			},
-			{
-				name: 'core/html',
-				blockName: 'core/html',
-				originalContent: '<svg><circle/></svg>',
-				innerBlocks: [],
-			},
-			{
-				name: 'core/heading',
-				blockName: 'core/heading',
-				originalContent: '<h2>Title</h2>',
-				innerBlocks: [],
-			},
-		] );
-
-		const report = await checkHtmlBlocks( 'content', 'http://localhost:8888' );
-
-		expect( report.totalBlocks ).toBe( 3 );
-		expect( report.htmlBlocks ).toBe( 1 );
-		expect( report.allowedBlocks ).toBe( 1 );
-	} );
-} );
diff --git a/apps/cli/ai/tests/tools.test.ts b/apps/cli/ai/tests/tools.test.ts
index 338a1f95b0..cc48dc8a7f 100644
--- a/apps/cli/ai/tests/tools.test.ts
+++ b/apps/cli/ai/tests/tools.test.ts
@@ -20,10 +20,6 @@ vi.mock( 'cli/ai/browser-utils', () => ( {
 	getSharedBrowser: vi.fn(),
 } ) );
 
-vi.mock( 'cli/ai/html-block-checker', () => ( {
-	checkHtmlBlocks: vi.fn(),
-} ) );
-
 vi.mock( 'cli/commands/preview/create', () => ( {
 	runCommand: vi.fn(),
 } ) );

From 6dd82ff2d5e9cb29cbf7f0fa0f74aa8184376c9d Mon Sep 17 00:00:00 2001
From: Roberto Aranda <roberto.aranda@automattic.com>
Date: Thu, 9 Apr 2026 20:19:28 +0200
Subject: [PATCH 6/7] Extract block conversion workflow into blockify skill

Move the Phase 2 block conversion logic and block content guidelines
from the system prompt into a dedicated blockify skill. The system
prompt now invokes the skill, keeping Phase 1 focused on design.
---
 apps/cli/ai/plugin/skills/blockify/SKILL.md | 172 ++++++++++++++++++++
 apps/cli/ai/system-prompt.ts                | 126 +-------------
 2 files changed, 174 insertions(+), 124 deletions(-)
 create mode 100644 apps/cli/ai/plugin/skills/blockify/SKILL.md

diff --git a/apps/cli/ai/plugin/skills/blockify/SKILL.md b/apps/cli/ai/plugin/skills/blockify/SKILL.md
new file mode 100644
index 0000000000..757bd0816d
--- /dev/null
+++ b/apps/cli/ai/plugin/skills/blockify/SKILL.md
@@ -0,0 +1,172 @@
+---
+name: blockify
+description: Convert all core/html blocks in a WordPress site to native Gutenberg blocks. Run this after building a site (Phase 2) or on any existing site that uses custom HTML blocks.
+user-invokable: true
+---
+
+# Block Conversion (Blockify)
+
+Convert all `core/html` blocks in a site's pages, posts, and template parts to native Gutenberg blocks. The CSS stays untouched — the visual output must remain identical.
+
+## How to Run
+
+### Step 1 — Read back all content
+
+Retrieve every piece of block content:
+- Page/post content: `wp_cli post get <id> --field=post_content` for each page/post
+- Template part files: Read header.html, footer.html, and any other template parts from disk
+
+You need the full current content to plan the conversion.
+
+### Step 2 — Plan the conversion section-by-section
+
+For each section of content, decide what converts to native blocks and what stays as `core/html`:
+
+| HTML | Gutenberg block |
+|------|----------------|
+| `<section>`, `<div>`, `<header>`, `<footer>`, `<aside>` | `core/group` with appropriate `tagName` |
+| `<h1>`–`<h6>` | `core/heading` with matching `level` |
+| `<p>` | `core/paragraph` |
+| `<a class="btn">` / CTA links | `core/buttons` + `core/button` |
+| CSS grid/flex layouts with `<div>` children | `core/columns` + `core/column` |
+| `<ul>` / `<ol>` | `core/list` + `core/list-item` |
+| `<img>` | `core/image` |
+| `<figure>` | `core/image` or `core/media-text` |
+| `<blockquote>` | `core/quote` |
+| `<table>` | `core/table` |
+| `<hr>` | `core/separator` |
+| Empty spacing `<div>` | `core/spacer` |
+
+Keep `core/html` ONLY for content with no native block equivalent:
+- Inline SVGs (icons, illustrations, decorative graphics)
+- `<form>` elements and interactive inputs
+- `<canvas>`, `<iframe>`, `<video>`, `<audio>`
+- Animation/interaction markup (marquee, custom cursor, scroll-triggered elements)
+- Elements needing custom `data-*` attributes for JS interactivity
+- A single `<script>` block at the bottom of the page for frontend JS
+
+All CSS classes from the original design stay in style.css — the visual output must remain identical after conversion.
+
+### Step 3 — Write the converted content
+
+Rewrite the full content for each page/post and template part using native Gutenberg block markup. Use the block patterns below as reference. Update posts via `wp_cli post update` and template parts via Write/Edit.
+
+### Step 4 — Validate block markup
+
+Run `validate_blocks` on every piece of converted content to catch markup errors (missing attributes, invalid nesting, malformed block comments). If it flags invalid blocks, fix the markup and re-run until all blocks pass.
+
+### Step 5 — Final visual check
+
+Take screenshots (desktop + mobile) to confirm the conversion did not break the design. Fix any visual regressions — the site must look identical to the original.
+
+## Block pattern reference
+
+### Section wrapper
+
+Replaces `<section>`, `<div>`, `<aside>`, `<header>`, `<footer>`:
+```
+<!-- wp:group {"tagName":"section","className":"hero-section","layout":{"type":"default"}} -->
+<section class="wp-block-group hero-section">
+  <!-- inner blocks go here -->
+</section>
+<!-- /wp:group -->
+```
+
+### Heading
+
+Replaces `<h1>`–`<h6>`:
+```
+<!-- wp:heading {"level":1,"className":"hero-title"} -->
+<h1 class="wp-block-heading hero-title">Your Title</h1>
+<!-- /wp:heading -->
+```
+
+### Paragraph
+
+Replaces `<p>`:
+```
+<!-- wp:paragraph {"className":"hero-subtitle"} -->
+<p class="hero-subtitle">Your text here.</p>
+<!-- /wp:paragraph -->
+```
+
+### Columns layout
+
+Replaces CSS grid/flex with `<div>` children:
+```
+<!-- wp:columns {"className":"features-grid"} -->
+<div class="wp-block-columns features-grid">
+  <!-- wp:column -->
+  <div class="wp-block-column">
+    <!-- inner blocks -->
+  </div>
+  <!-- /wp:column -->
+  <!-- wp:column -->
+  <div class="wp-block-column">
+    <!-- inner blocks -->
+  </div>
+  <!-- /wp:column -->
+</div>
+<!-- /wp:columns -->
+```
+
+### Image
+
+Replaces `<img>`:
+```
+<!-- wp:image {"className":"hero-image"} -->
+<figure class="wp-block-image hero-image"><img src="https://example.com/image.jpg" alt="Description"/></figure>
+<!-- /wp:image -->
+```
+
+### Buttons
+
+Replaces `<a class="btn">`:
+```
+<!-- wp:buttons {"className":"hero-cta"} -->
+<div class="wp-block-buttons hero-cta">
+  <!-- wp:button {"className":"primary-btn"} -->
+  <div class="wp-block-button primary-btn"><a class="wp-block-button__link wp-element-button" href="#">Get Started</a></div>
+  <!-- /wp:button -->
+</div>
+<!-- /wp:buttons -->
+```
+
+### List
+
+Replaces `<ul>` / `<ol>`:
+```
+<!-- wp:list {"className":"feature-list"} -->
+<ul class="feature-list">
+  <!-- wp:list-item -->
+  <li>First item</li>
+  <!-- /wp:list-item -->
+  <!-- wp:list-item -->
+  <li>Second item</li>
+  <!-- /wp:list-item -->
+</ul>
+<!-- /wp:list -->
+```
+
+### Separator
+
+Replaces `<hr>`:
+```
+<!-- wp:separator {"className":"section-divider"} -->
+<hr class="wp-block-separator section-divider"/>
+<!-- /wp:separator -->
+```
+
+## Nesting blocks
+
+Sections are built by nesting blocks inside `core/group`. All visual styling (grid layouts, spacing, colors, backgrounds, animations) goes in `style.css` targeting the `className`. The block structure is for editability; the CSS is for aesthetics.
+
+## Additional rules
+
+- Never use `core/html` to wrap text content, headings, layout sections, or lists.
+- No decorative HTML comments (e.g. `<!-- Hero Section -->`, `<!-- Features -->`). Only block delimiter comments are allowed.
+- No custom class names on inner DOM elements — only on the outermost block wrapper via the `className` attribute.
+- No inline `style` or `style` block attributes for styling. Use `className` + `style.css` instead.
+- Use `core/spacer` for empty spacing divs, not `core/group`.
+- No emojis anywhere in generated content.
+- Adding `data-*` attributes does NOT make a block acceptable — use `className` on `core/group` blocks instead.
diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index 8eaaf6a6ca..526c3c4de0 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -18,8 +18,6 @@ ${ REMOTE_DESIGN_GUIDELINES }
 
 	return `${ buildLocalIntro() }
 
-${ LOCAL_CONTENT_GUIDELINES }
-
 ${ LOCAL_DESIGN_GUIDELINES }
 `;
 }
@@ -117,18 +115,7 @@ Then continue with:
 
 ### Phase 2 — Block Conversion
 
-5. **Read back all content**: Use \`wp_cli post get <id> --field=post_content\` to retrieve page/post content, and read template part files (header.html, footer.html, etc.) from disk. You need the full current content to plan the conversion.
-6. **Plan the conversion section-by-section**: For each section of content, decide what converts to native blocks and what stays as \`core/html\`. Apply the Block Content Guidelines below:
-   - Section wrappers (\`<section>\`, \`<div>\`, \`<header>\`, \`<footer>\`, \`<aside>\`) → \`core/group\` with appropriate \`tagName\`
-   - Headings (\`<h1>\`–\`<h6>\`) → \`core/heading\`
-   - Paragraphs (\`<p>\`) → \`core/paragraph\`
-   - Buttons/CTAs (\`<a class="btn">\`) → \`core/buttons\` + \`core/button\`
-   - Two-column layouts → \`core/columns\` + \`core/column\`
-   - Lists (\`<ul>\`/\`<ol>\`) → \`core/list\` + \`core/list-item\`
-   - Images (\`<img>\`) → \`core/image\`
-   - Keep \`core/html\` ONLY for: inline SVGs, \`<form>\` elements, \`<script>\`, \`<canvas>\`, \`<iframe>\`, animation/interaction markup, elements needing custom \`data-*\` attributes for JS interactivity.
-   All CSS classes from Phase 1 stay in style.css — the visual output must remain identical.
-7. **Write the converted content**: Rewrite the full content for each page/post and template part using native Gutenberg block markup. Update posts via \`wp_cli post update\` and template parts via Write/Edit.
+5. **Convert to native blocks**: Run the \`blockify\` skill to convert all \`core/html\` blocks to native Gutenberg blocks, validate the markup, and verify the design is preserved.
 8. **Validate block markup**: Run \`validate_blocks\` on every piece of converted content to catch markup errors (missing attributes, invalid nesting, malformed block comments). If it flags invalid blocks, fix the markup and re-run until all blocks pass.
 9. **Final visual check**: Take screenshots again (desktop + mobile) to confirm the block conversion did not break the design. Fix any visual regressions — the site must look identical to the Phase 1 result.
 
@@ -145,7 +132,7 @@ Then continue with:
 - preview_update: Update an existing hosted WordPress.com preview from a local site; this can take a few minutes, so tell the user to wait
 - preview_delete: Delete a hosted WordPress.com preview by hostname
 - wp_cli: Run WP-CLI commands on a running site
-- validate_blocks: Validates block markup on a running site by running each block through its save() function in a real browser. Catches invalid attributes, malformed nesting, and markup mismatches. Call on every piece of block content after Phase 2 conversion — post content AND template parts.
+- validate_blocks: Validates block markup on a running site by running each block through its save() function in a real browser. Catches invalid attributes, malformed nesting, and markup mismatches. Used by the \`blockify\` skill during block conversion.
 - take_screenshot: Take a full-page screenshot of a URL (supports desktop and mobile viewports). Use this to visually check the site after building it.
 - audit_performance: Measure frontend performance metrics (TTFB, FCP, LCP, CLS, page weight, DOM size, JS/CSS/image/font asset breakdown) for a running site. Use this to identify performance bottlenecks and guide optimization.
 
@@ -178,117 +165,8 @@ const REMOTE_DESIGN_GUIDELINES = `## Design capabilities by plan
 - Custom CSS, global styles, plugin management, and advanced customization become available.
 - Check the specific plan to determine exact capabilities.`;
 
-const LOCAL_CONTENT_GUIDELINES = `## Block content guidelines
-
-**Reference for Phase 2 (Block Conversion).** When converting content to native blocks, use these patterns. During Phase 1, you may ignore this section and write HTML freely.
-
-### Core block patterns
-
-**Section wrapper** (replaces \`<section>\`, \`<div>\`, \`<aside>\`, \`<header>\`, \`<footer>\`):
-\`\`\`
-<!-- wp:group {"tagName":"section","className":"hero-section","layout":{"type":"default"}} -->
-<section class="wp-block-group hero-section">
-  <!-- inner blocks go here -->
-</section>
-<!-- /wp:group -->
-\`\`\`
-
-**Heading** (replaces \`<h1>\`–\`<h6>\`):
-\`\`\`
-<!-- wp:heading {"level":1,"className":"hero-title"} -->
-<h1 class="wp-block-heading hero-title">Your Title</h1>
-<!-- /wp:heading -->
-\`\`\`
-
-**Paragraph** (replaces \`<p>\`):
-\`\`\`
-<!-- wp:paragraph {"className":"hero-subtitle"} -->
-<p class="hero-subtitle">Your text here.</p>
-<!-- /wp:paragraph -->
-\`\`\`
-
-**Columns layout** (replaces CSS grid/flex with \`<div>\` children):
-\`\`\`
-<!-- wp:columns {"className":"features-grid"} -->
-<div class="wp-block-columns features-grid">
-  <!-- wp:column -->
-  <div class="wp-block-column">
-    <!-- inner blocks -->
-  </div>
-  <!-- /wp:column -->
-  <!-- wp:column -->
-  <div class="wp-block-column">
-    <!-- inner blocks -->
-  </div>
-  <!-- /wp:column -->
-</div>
-<!-- /wp:columns -->
-\`\`\`
-
-**Image** (replaces \`<img>\`):
-\`\`\`
-<!-- wp:image {"className":"hero-image"} -->
-<figure class="wp-block-image hero-image"><img src="https://example.com/image.jpg" alt="Description"/></figure>
-<!-- /wp:image -->
-\`\`\`
-
-**Buttons** (replaces \`<a class="btn">\`):
-\`\`\`
-<!-- wp:buttons {"className":"hero-cta"} -->
-<div class="wp-block-buttons hero-cta">
-  <!-- wp:button {"className":"primary-btn"} -->
-  <div class="wp-block-button primary-btn"><a class="wp-block-button__link wp-element-button" href="#">Get Started</a></div>
-  <!-- /wp:button -->
-</div>
-<!-- /wp:buttons -->
-\`\`\`
-
-**List** (replaces \`<ul>\` / \`<ol>\`):
-\`\`\`
-<!-- wp:list {"className":"feature-list"} -->
-<ul class="feature-list">
-  <!-- wp:list-item -->
-  <li>First item</li>
-  <!-- /wp:list-item -->
-  <!-- wp:list-item -->
-  <li>Second item</li>
-  <!-- /wp:list-item -->
-</ul>
-<!-- /wp:list -->
-\`\`\`
-
-**Separator** (replaces \`<hr>\`):
-\`\`\`
-<!-- wp:separator {"className":"section-divider"} -->
-<hr class="wp-block-separator section-divider"/>
-<!-- /wp:separator -->
-\`\`\`
-
-### Nesting blocks
-
-Sections are built by nesting blocks inside \`core/group\`. All visual styling (grid layouts, spacing, colors, backgrounds, animations) goes in \`style.css\` targeting the \`className\`. The block structure is for editability; the CSS is for aesthetics.
-
-### When core/html IS acceptable
-
-Only use \`core/html\` for content that has NO native block equivalent:
-- Inline SVGs (icons, illustrations, decorative graphics)
-- \`<form>\` elements and interactive inputs
-- Animation/interaction markup (marquee, custom cursor, scroll-triggered elements)
-- A single \`<script>\` block at the bottom of the page for frontend JS
-
-### Additional rules
-
-- Never use \`core/html\` to wrap text content, headings, layout sections, or lists.
-- No decorative HTML comments (e.g. \`<!-- Hero Section -->\`, \`<!-- Features -->\`). Only block delimiter comments are allowed.
-- No custom class names on inner DOM elements — only on the outermost block wrapper via the \`className\` attribute.
-- No inline \`style\` or \`style\` block attributes for styling. Use \`className\` + \`style.css\` instead.
-- Use \`core/spacer\` for empty spacing divs, not \`core/group\`.
-- No emojis anywhere in generated content.`;
-
 const LOCAL_DESIGN_GUIDELINES = `## Design guidelines
 
-**Primary reference for Phase 1 (Design).** These guidelines drive your visual decisions.
-
 **Important**: Always use sophisticated scroll effects and add animations unless specifically asked otherwise.
 
 Understand the context and commit to a BOLD aesthetic direction:

From 1ccbe8d12a6a999840dae623ad1fb9649c005b9c Mon Sep 17 00:00:00 2001
From: Roberto Aranda <roberto.aranda@automattic.com>
Date: Thu, 9 Apr 2026 22:22:10 +0200
Subject: [PATCH 7/7] Improve blockify skill and restore block content
 guidelines

Add decomposition rules to prevent skipping entire sections when only
some sub-elements need core/html. Clarify that id, inline em/strong,
and loading attributes are not valid reasons to keep sections as HTML.
Restore LOCAL_CONTENT_GUIDELINES from trunk to the system prompt.
---
 apps/cli/ai/plugin/skills/blockify/SKILL.md | 24 +++++++++++++++------
 apps/cli/ai/system-prompt.ts                | 20 +++++++++++++++--
 2 files changed, 35 insertions(+), 9 deletions(-)

diff --git a/apps/cli/ai/plugin/skills/blockify/SKILL.md b/apps/cli/ai/plugin/skills/blockify/SKILL.md
index 757bd0816d..ad54760e90 100644
--- a/apps/cli/ai/plugin/skills/blockify/SKILL.md
+++ b/apps/cli/ai/plugin/skills/blockify/SKILL.md
@@ -12,13 +12,17 @@ Convert all `core/html` blocks in a site's pages, posts, and template parts to n
 
 ### Step 1 — Read back all content
 
-Retrieve every piece of block content:
-- Page/post content: `wp_cli post get <id> --field=post_content` for each page/post
-- Template part files: Read header.html, footer.html, and any other template parts from disk
+Retrieve every piece of block content. You MUST read ALL of these before proceeding:
+- Page/post content: `wp_cli post list --post_type=page,post --fields=ID,post_title` then `wp_cli post get <id> --field=post_content` for each
+- Template part files: Read header.html, footer.html, and ALL other template part files from the theme's `parts/` directory
 
-You need the full current content to plan the conversion.
+Do NOT skip template parts — they often contain navigation, hero sections, or footer content that needs conversion.
 
-### Step 2 — Plan the conversion section-by-section
+### Step 2 — Plan the conversion element-by-element
+
+**CRITICAL: Always decompose.** Never keep an entire section as `core/html` just because it contains some non-convertible sub-elements. Break the section apart: convert every convertible element to native blocks and isolate only the truly non-convertible elements as individual `core/html` blocks.
+
+For example, a hero section with a heading, paragraph, buttons, image, AND a scroll-indicator animation should become: `core/group` > `core/heading` + `core/paragraph` + `core/buttons` + `core/image` + `core/html` (scroll indicator only). Do NOT keep the entire hero as `core/html`.
 
 For each section of content, decide what converts to native blocks and what stays as `core/html`:
 
@@ -37,13 +41,19 @@ For each section of content, decide what converts to native blocks and what stay
 | `<hr>` | `core/separator` |
 | Empty spacing `<div>` | `core/spacer` |
 
-Keep `core/html` ONLY for content with no native block equivalent:
+Keep `core/html` ONLY for individual elements with no native block equivalent:
 - Inline SVGs (icons, illustrations, decorative graphics)
 - `<form>` elements and interactive inputs
 - `<canvas>`, `<iframe>`, `<video>`, `<audio>`
 - Animation/interaction markup (marquee, custom cursor, scroll-triggered elements)
 - Elements needing custom `data-*` attributes for JS interactivity
-- A single `<script>` block at the bottom of the page for frontend JS
+- `<script>` tags — always extract into their own separate `core/html` block, never bundled with structural content
+
+**Things that are NOT valid reasons to keep a section as `core/html`:**
+- `id` attributes — `core/group` supports `anchor` for element IDs
+- Inline `<em>`, `<strong>`, `<br>`, `<a>` inside text — `core/heading` and `core/paragraph` support inline HTML
+- `loading="eager"` on images — drop the attribute rather than keeping the whole section as HTML
+- A single non-convertible child — decompose the section instead of skipping it entirely
 
 All CSS classes from the original design stay in style.css — the visual output must remain identical after conversion.
 
diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index 526c3c4de0..71496ab356 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -18,6 +18,8 @@ ${ REMOTE_DESIGN_GUIDELINES }
 
 	return `${ buildLocalIntro() }
 
+${ LOCAL_CONTENT_GUIDELINES }
+
 ${ LOCAL_DESIGN_GUIDELINES }
 `;
 }
@@ -116,8 +118,8 @@ Then continue with:
 ### Phase 2 — Block Conversion
 
 5. **Convert to native blocks**: Run the \`blockify\` skill to convert all \`core/html\` blocks to native Gutenberg blocks, validate the markup, and verify the design is preserved.
-8. **Validate block markup**: Run \`validate_blocks\` on every piece of converted content to catch markup errors (missing attributes, invalid nesting, malformed block comments). If it flags invalid blocks, fix the markup and re-run until all blocks pass.
-9. **Final visual check**: Take screenshots again (desktop + mobile) to confirm the block conversion did not break the design. Fix any visual regressions — the site must look identical to the Phase 1 result.
+6. **Validate block markup**: Run \`validate_blocks\` on every piece of converted content to catch markup errors (missing attributes, invalid nesting, malformed block comments). If it flags invalid blocks, fix the markup and re-run until all blocks pass.
+7. **Final visual check**: Take screenshots again (desktop + mobile) to confirm the block conversion did not break the design. Fix any visual regressions — the site must look identical to the Phase 1 result.
 
 ## Available Studio Tools (prefixed with mcp__studio__)
 
@@ -165,6 +167,20 @@ const REMOTE_DESIGN_GUIDELINES = `## Design capabilities by plan
 - Custom CSS, global styles, plugin management, and advanced customization become available.
 - Check the specific plan to determine exact capabilities.`;
 
+const LOCAL_CONTENT_GUIDELINES = `## Block content guidelines
+
+- Only use \`core/html\` blocks for:
+	- Inline SVGs
+	- \`<form>\` elements and interactive inputs
+	- Animation/interaction markup with no block equivalent (marquee, cursor)
+	- A single \`<script>\` block at the bottom of the page for JS
+- Never use \`core/html\` to wrap text content, headings, layout sections, or lists.
+- No decorative HTML comments (e.g. \`<!-- Hero Section -->\`, \`<!-- Features -->\`). Only block delimiter comments are allowed.
+- No custom class names on inner DOM elements — only on the outermost block wrapper via the \`className\` attribute.
+- No inline \`style\` or \`style\` block attributes for styling. Use \`className\` + \`style.css\` instead.
+- Use \`core/spacer\` for empty spacing divs, not \`core/group\`.
+- No emojis anywhere in generated content.`;
+
 const LOCAL_DESIGN_GUIDELINES = `## Design guidelines
 
 **Important**: Always use sophisticated scroll effects and add animations unless specifically asked otherwise.