From cbb47165bc2ec660076314bc358b66872a11be62 Mon Sep 17 00:00:00 2001
From: Riad Benguella <benguella@gmail.com>
Date: Thu, 23 Apr 2026 14:19:41 +0100
Subject: [PATCH 1/4] apps/cli: two-phase AI build workflow with blockify skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restructures the AI agent's site-build flow into explicit phases and
adds a user-invokable skill for HTML → Gutenberg block conversion,
measured against a sequence of full-build sessions to validate each
change.

Phase 1 — HTML prototype. The agent writes plain HTML/CSS/JS under
`<site>/tmp/prototype/` with a section-anchor skeleton, then fills
one anchor per Edit. Design tokens are locked in a `tokens` anchor
before any section fill. Theme writes are forbidden in this phase so
the design is screenshot-approved before block markup enters the
picture.

Phase 2 — Port to block theme. The agent invokes the new `blockify`
skill (apps/cli/ai/plugin/skills/blockify/SKILL.md) as a gate before
writing block markup. The theme stylesheet is `cp`-ed from the
prototype and adjusted via small Edits for block-DOM selectors
(`.wp-block-button`, `.wp-block-image`), replacing a prior 60–90s
silent regeneration. Page content is built in
`<site>/tmp/page-<slug>.html` and applied via
`wp_cli eval '... file_get_contents(ABSPATH . "tmp/page-<slug>.html") ...'`
— the prior `--post_content-file=<host path>` pattern silently
failed because wp_cli runs in a WASM filesystem that cannot see
host paths.

Working cadence is split into content creation (one tool per turn to
avoid silent generation cliffs) and fix-up loops (multiple Edits per
turn when validate_blocks or take_screenshot report multiple issues).
The validate_blocks tool description is updated in lockstep so it no
longer instructs the agent to validate after every individual Edit.

`maxTurns` default is raised to 100 to give headroom for the added
section-by-section turns without truncating builds.
---
 apps/cli/ai/agent.ts                        |   2 +-
 apps/cli/ai/plugin/skills/blockify/SKILL.md | 175 ++++++++++++++++++++
 apps/cli/ai/system-prompt.ts                | 116 ++++++++-----
 3 files changed, 249 insertions(+), 44 deletions(-)
 create mode 100644 apps/cli/ai/plugin/skills/blockify/SKILL.md

diff --git a/apps/cli/ai/agent.ts b/apps/cli/ai/agent.ts
index 329f697a58..5c803a932c 100644
--- a/apps/cli/ai/agent.ts
+++ b/apps/cli/ai/agent.ts
@@ -55,7 +55,7 @@ export function startAiAgent( config: AiAgentConfig ): Query {
 		prompt,
 		env,
 		model = DEFAULT_MODEL,
-		maxTurns = 50,
+		maxTurns = 100,
 		resume,
 		autoApprove,
 		activeSite,
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..01f00c5e68
--- /dev/null
+++ b/apps/cli/ai/plugin/skills/blockify/SKILL.md
@@ -0,0 +1,175 @@
+---
+name: blockify
+description: Convert HTML content to native Gutenberg block markup. Invoke this any time you need to translate raw HTML (a section, a full page, a file on disk, a snippet in the conversation) into valid block markup. Works on any input — not scoped to a site, a post, or a theme.
+user-invokable: true
+---
+
+# Blockify — HTML to Gutenberg blocks
+
+Convert HTML input into native Gutenberg block markup. The goal is **FAITHFUL CONVERSION**: reproduce the same DOM using native blocks, preserve every className, and only fall back to `core/html` for truly non-convertible elements.
+
+## Input and output
+
+- **Input**: any HTML — a single section, a full page, a file you `Read`, a snippet the user pasted, the `post_content` of an existing post fetched via `wp_cli post get`. This skill does not care where the HTML came from.
+- **Output**: valid Gutenberg block markup that renders the same visual DOM. Return it inline in your response, write it to a file with `Write`/`Edit`, or apply it with `wp_cli post update` — whichever the caller asked for.
+- **Out of scope**: this skill does NOT modify CSS, theme files, or site content by default. It is a pure HTML → block markup transformation. If the caller wants the result applied somewhere, they invoke the appropriate tool after receiving the output.
+
+## Decompose — do not give up on a section
+
+Never wrap an entire section in `core/html` just because some of its children are non-convertible. Break sections apart: convert every convertible child to a native block and isolate only the truly non-convertible child as its own `core/html` block.
+
+Example: a hero `<section>` with a heading, paragraph, buttons, image, AND a scroll-indicator animation becomes `core/group` > `core/heading` + `core/paragraph` + `core/buttons` + `core/image` + `core/html` (scroll indicator only). Do NOT keep the entire hero as `core/html`.
+
+## Translation table
+
+| 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
+
+- 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
+- `<script>` tags — always extract into their own separate `core/html` block, never bundled with structural content
+
+## NOT valid reasons to keep an element 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.
+- Small text-containing `<div>` or `<span>` (eyebrow text, labels, captions, taglines) — convert to `core/paragraph` with the appropriate `className`.
+- Decorative wrapper `<div>` elements — convert to `core/group` with `className`.
+- **Section wrappers with background images, overlays, or gradients** — always `core/group` with `className`. All visual effects (background-image, overlays, pseudo-elements, gradients) are handled by CSS targeting the className, not by the block markup.
+
+**Be thorough.** Convert every single element that has a native block equivalent. A `<div>` with text inside it is a `core/paragraph` or `core/group`, not a Custom HTML block.
+
+## Preserve every className
+
+Every CSS class from the input stays on the outermost block wrapper via the `className` attribute. No custom class names on inner DOM elements. Never inline `style` attributes — classNames drive all appearance, backed by whatever stylesheet the caller already has.
+
+## 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
+
+Sections are built by nesting blocks inside `core/group`. The block structure is for editability; the stylesheet is for aesthetics. Never push layout, spacing, or color into block markup that belongs in CSS.
+
+## 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` 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 9c3c6cd168..c4b944d0d0 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -10,17 +10,15 @@ export function buildSystemPrompt( options?: { remoteSite?: RemoteSiteContext }
 	if ( options?.remoteSite ) {
 		return `${ buildRemoteIntro( options.remoteSite ) }
 
-${ REMOTE_CONTENT_GUIDELINES }
+${ REMOTE_PLANS_GUIDELINES }
 
-${ REMOTE_DESIGN_GUIDELINES }
+${ DESIGN_GUIDELINES }
 `;
 	}
 
 	return `${ buildLocalIntro() }
 
-${ LOCAL_CONTENT_GUIDELINES }
-
-${ LOCAL_DESIGN_GUIDELINES }
+${ DESIGN_GUIDELINES }
 `;
 }
 
@@ -28,7 +26,7 @@ function buildRemoteIntro( site: RemoteSiteContext ): string {
 	return `${ AGENT_IDENTITY } You manage WordPress.com sites using the WordPress.com REST API.
 
 IMPORTANT: The active site is a remote WordPress.com site: "${ site.name }" (ID: ${ site.id }) at ${ site.url }.
-IMPORTANT: You MUST use the wpcom_request tool (prefixed with mcp__studio__) to manage this site. Do NOT use WP-CLI, file Write/Edit, Bash, or any local file operations — this site is hosted on WordPress.com and cannot be modified through the local filesystem.
+IMPORTANT: You MUST use the wpcom_request tool (prefixed with mcp__studio__) to manage this site. Do NOT use WP-CLI — this site is hosted on WordPress.com and that's our only way to edit it.
 IMPORTANT: Before doing ANY work, you MUST first check the site's plan by calling \`GET /\` (apiNamespace: \`""\`). The \`plan.product_slug\` field indicates the plan. If the site is on a free plan (e.g. \`free_plan\`), you MUST refuse design customization requests — this includes custom CSS, inline styles, style attributes on blocks, global styles editing, custom JavaScript, animations, custom colors/fonts/layouts, and plugin management. Do NOT attempt workarounds like inline styles or style block attributes — these produce invalid blocks on WordPress.com. Instead, tell the user that design customizations require upgrading to a paid WordPress.com plan and STOP. Do not proceed with the design task.
 
 ## Available Tools (prefixed with mcp__studio__)
@@ -81,10 +79,22 @@ Use \`per_page\` and \`page\` for pagination. Use \`status\` to filter by publis
 
 ## Workflow
 
-1. **Check the site plan** (MANDATORY FIRST STEP): Use \`GET /\` (apiNamespace: \`""\`) to get site info and check \`plan.product_slug\`. Stop and inform the user if they request features unavailable on their plan.
-2. **Understand the site**: Use \`GET /posts\` to list content, \`GET /themes?status=active\` to see the active theme.
-3. **Make changes**: Use POST requests to create/update content, manage templates, switch themes.
-4. **Verify visually**: Use take_screenshot to capture the site on desktop and mobile viewports. Check spacing, alignment, colors, contrast, and layout. Fix any issues.
+PHASE 1 — Audit.
+
+**Check the site plan** (MANDATORY FIRST STEP): Use \`GET /\` (apiNamespace: \`""\`) to get site info and check \`plan.product_slug\`. Stop and inform the user if they request features unavailable on their plan.
+**Understand the site**: Use \`GET /posts\` to list content, \`GET /themes?status=active\` to see the active theme.
+
+PHASE 2 — HTML prototype. Write to <site>/tmp/prototype/.
+ - Allowed: Write/Edit on index.html, about.html, services.html, style.css, app.js.
+ - Phase 2 complete when: take_screenshot of the prototype index.html matches the expected design.
+
+PHASE 3 — Port to block content. Translate <site>/tmp/prototype/ to block markup
+
+1. **Convert all the content of the different pages to insert to blocks as well** Use the block guidelines.
+2. **Make changes**: Use POST requests to create/update content, manage templates, switch themes.
+3. **Verify visually**: Use take_screenshot to capture the site on desktop and mobile viewports. Check spacing, alignment, colors, contrast, and layout. Fix any issues.
+
+${WORK_CADENCE}
 
 ## General rules
 
@@ -98,10 +108,9 @@ 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:
+IMPORTANT: For any generated content for the site, these two 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.
 
 ## Workflow
@@ -115,12 +124,37 @@ 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.
-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.
-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 — HTML prototype. Write to <site>/tmp/prototype/.
+ - Allowed: Write/Edit on index.html, about.html, services.html, style.css, app.js inside \`<site>/tmp/prototype/\` only.
+ - FORBIDDEN in PHASE 1: any Write/Edit under \`wp-content/themes/\` or \`wp-content/plugins/\`, any \`wp_cli post create/update\`, any \`validate_blocks\`, any theme activation or \`theme.json\` creation. Violating PHASE 1 scope invalidates the build — restart.
+ - Phase 1 complete when: take_screenshot of the prototype index.html matches the design.
+
+PHASE 2 — Port to block theme. Translate <site>/tmp/prototype/ to a block theme with block markup:
+
+0. Invoke the \`blockify\` skill to load the HTML→block translation rules.
+   Do NOT write any block markup before this step completes.
+1. Build the block theme skeleton:
+   - \`theme.json\`, \`functions.php\`, \`parts/header.html\`, \`parts/footer.html\`, \`templates/index.html\`, \`templates/front-page.html\`.
+   - Copy the prototype stylesheet as the starting point — do NOT regenerate:
+     \`cp <site>/tmp/prototype/style.css <site>/wp-content/themes/<slug>/assets/css/main.css\` (via Bash).
+   - Apply block-DOM adjustments via Edits ONLY where WordPress changes the rendered DOM:
+     - button \`.<className>\` → \`.wp-block-button.<className> .wp-block-button__link\` (buttons split into wrapper + inner link).
+     - image \`.<className>\` → \`.wp-block-image.<className>\` (WordPress wraps images in \`<figure class="wp-block-image ...">\`).
+     - \`core/group\` sections — no selector change needed (the \`className\` passes through to the wrapper).
+   - Everything else (tokens, layout, typography, animations) stays identical to the prototype. The phase-1 screenshot already validated this CSS; re-deriving it wastes generation time and risks drift.
+2. For each <section> in a prototype HTML file, translate to block markup
+   using the blockify rules. Header/nav sections go into \`parts/header.html\`,
+   footer sections into \`parts/footer.html\`, main content sections are
+   collected into \`<site>/tmp/page-<slug>.html\` (e.g. \`<site>/tmp/page-home.html\`,
+   \`<site>/tmp/page-about.html\`), one file per prototype HTML, for use in step 4.
+   These files live in \`tmp/\`, NOT inside the theme.
+   \`templates/index.html\` stays a thin shell: header part + \`wp:post-content\` +
+   footer part.
+3. After each section, run validate_blocks. Fix before moving on.
+4. For each prototype HTML file: (a) create an empty page with \`wp_cli post create --post_type=page --post_title="<title>" --post_status=publish --post_content="" --porcelain\` — this returns the new page ID; (b) apply the block markup with \`wp_cli eval '$content = file_get_contents(ABSPATH . "tmp/page-<slug>.html"); wp_update_post(["ID" => <id>, "post_content" => $content]); echo "ok";'\`. Do NOT use \`--post_content-file=<host path>\` — wp_cli runs inside the WASM filesystem and cannot read host paths, so the page updates to empty content silently. \`ABSPATH\` resolves to \`/wordpress/\` inside WASM, which maps to your site root. Finally, set the homepage via \`wp_cli option update show_on_front page\` and \`wp_cli option update page_on_front <id>\`.
+5. **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.
+
+${WORK_CADENCE}
 
 ## Available Studio Tools (prefixed with mcp__studio__)
 
@@ -135,7 +169,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: 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 once after completing a batch of related edits to block content — NOT after every individual Edit. When validate_blocks returns multiple errors, apply ALL fixes in one turn (multiple Edits in a single assistant message), then re-validate once. Do not serialize \`Edit → validate → Edit → validate\` — it wastes turns.
 - 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.
 - need_for_speed: 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.
 - rank_me_up: Run an on-page SEO audit (title/meta tags, headings, image alt text, OpenGraph/Twitter cards, JSON-LD structured data, robots.txt and sitemap.xml availability) for a running site. Use this to identify on-page SEO issues and guide fixes.
@@ -146,23 +180,33 @@ 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.
 - 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).
-- Always add the style.css as editor styles in the functions.php of the theme to make the editor match the frontend.
-- For theme and page content custom CSS, put the styles in the main style.css of the theme. No custom stylesheets.
+- When building themes, always build block themes (NO CLASSIC THEMES) unless told otherwise.
+- In the theme's \`functions.php\`, register every stylesheet you enqueue on the frontend as an editor style too — call \`add_theme_support( 'editor-styles' )\` and \`add_editor_style( <relative path> )\` for each CSS file. Without this, the block editor renders unstyled content and the in-editor preview diverges from the frontend.
 - Scroll animations must use progressive enhancement: CSS defines elements in their **final visible state** by default (full opacity, final position). JavaScript on the frontend adds the initial hidden state (e.g. \`opacity: 0\`, \`transform\`) and scroll-triggered transitions. This ensures elements are fully visible in the block editor (which loads theme CSS but not custom JS).
 - All animations and transitions must respect \`prefers-reduced-motion\`. Add a \`@media (prefers-reduced-motion: reduce)\` block that disables or simplifies animations (e.g. \`animation: none; transition: none; scroll-behavior: auto;\`).`;
 }
 
-const REMOTE_CONTENT_GUIDELINES = `## Block content guidelines
+const WORK_CADENCE = `## Working cadence
 
-- Use only core WordPress blocks. No custom HTML blocks except for inline SVGs.
-- No decorative HTML comments (e.g. \`<!-- Hero Section -->\`). Only block delimiter comments are allowed.
-- No emojis anywhere in generated content.`;
+One \`Write\` or \`Edit\` or \`wpcom_request\` per turn during **content creation** — phase 1 anchor fills, phase 2 section translation, page-content anchors, initial file writes. Short prose between tools — no long design-plan essays. The CLI only renders complete assistant messages, so a turn that emits >~200 lines of new content spins silently for minutes and can hit gateway timeouts. Cadence is also a quality lever: the screenshot-fix loop only works after small visible increments.
+
+During **fix-up loops** (after \`validate_blocks\` flags errors, after \`take_screenshot\` reveals multiple issues, after user feedback lists multiple items), emit multiple independent Edits in one turn — one per issue. The anti-batching rule exists to prevent silent multi-minute generation of LARGE content, NOT to serialize small surgical fixes. 3–5 Edits of ≤500B each in one turn generate in about the same time as 1, and collapse what would be 3–5 turns into one.
+
+**Do NOT re-validate or re-screenshot after every individual Edit.** Apply all fixes from one validation or screenshot report in one turn (multiple Edits in the same assistant message), THEN re-validate or re-screenshot once. The \`Edit → validate → Edit → validate\` serialization is an anti-pattern — 10 fixes applied together take 2 turns (batch + verify); 10 fixes serialized take 20 turns for the same outcome.
+
+Examples: validate_blocks returns 3 invalid blocks → 3 Edits in one turn, then re-validate once. Screenshot shows wrong heading color, tight spacing, and missing border → 3 CSS Edits in one turn, then re-screenshot once.
+
+**Skeleton first, then fill across Edits.** Applies always to prototype files (phase 1) regardless of size, and to any theme file >~200 lines.
+
+- Prototype stylesheet (phase 1, \`<site>/tmp/prototype/style.css\`): skeleton = 6–10 anchor comments \`/* === <concern> === */\` specific to THIS design's composition, NOT a generic landing-page template. First anchor is always \`tokens\` (for \`:root\` custom properties: color scale, type scale, spacing scale, timing). Remaining anchors name this design's actual sections — e.g. a magazine layout might use \`type-scale\`, \`cover\`, \`lede\`, \`grid\`, \`pull-quote\`, \`masthead\`; a brutalist landing might use \`nav\`, \`manifesto\`, \`work-grid\`, \`contact-block\`. Skeleton <2KB total. Fill one anchor per Edit (300–2000B each) — \`old_string\` is the anchor line, \`new_string\` is \`<anchor>\\n\\n<styles>\`. **Fill \`tokens\` first and completely before any section anchor — every section must use only these tokens.**
+- Theme stylesheet (phase 2, \`<site>/wp-content/themes/<slug>/assets/css/main.css\`): \`cp\` from the prototype stylesheet (Bash), then Edits for block-DOM selector adjustments only. NEVER regenerate the theme stylesheet in a single Write — that burns 60–90s of silent generation and risks drift from the prototype that was already screenshot-approved.
+- HTML prototype pages (\`prototype/index.html\`, \`about.html\`, etc.): skeleton = \`<!DOCTYPE html>\` shell + \`<head>\` (meta, fonts, CSS link) + \`<body>\` containing \`<!-- section:<concern> -->\` anchors specific to THIS design's composition, NOT a generic landing-page template. Each anchor name should reflect the design's actual section (e.g. \`manifesto\`, \`work-grid\`, \`editorial-masthead\`, \`case-study-1\`), not a template slot (\`hero\`, \`features\`, \`cta\`). Skeleton <2KB total. Fill one anchor per Edit — \`old_string\` is the anchor comment, \`new_string\` is \`<anchor comment>\\n\\n<section markup>\`.
+- Block-markup page content (phase 2): create the page empty (\`wp_cli post create --post_content=""\` for local sites and \`wpcom_request\` for remote ones), write \`<site>/tmp/page-<slug>.html\` (not inside the theme) with \`<!-- section:<concern> -->\` anchors (<1KB), fill one anchor per Edit, then apply once with \`wp_cli eval '$content = file_get_contents(ABSPATH . "tmp/page-<slug>.html"); wp_update_post(["ID" => <id>, "post_content" => $content]); echo "ok";'\` for local sites (wp_cli runs inside WASM and cannot read host paths — \`ABSPATH\` resolves to \`/wordpress/\` which maps to your site root), or \`wpcom_request\` for remote sites.
+`;
 
-const REMOTE_DESIGN_GUIDELINES = `## Design capabilities by plan
+const REMOTE_PLANS_GUIDELINES = `## Design capabilities by plan
 
 **Free plans** — content only, no design customization:
 - CAN: Create/edit posts, pages, templates, template parts. Switch themes. Upload media.
@@ -173,21 +217,7 @@ 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
+const DESIGN_GUIDELINES = `## Design guidelines
 
 **Important**: Always use sophisticated scroll effects and add animations unless specifically asked otherwise.
 

From cf52498d86b43f1e2cc9a9e2d40af0234373dcd0 Mon Sep 17 00:00:00 2001
From: Riad Benguella <benguella@gmail.com>
Date: Thu, 23 Apr 2026 14:35:21 +0100
Subject: [PATCH 2/4] apps/cli: restructure remote WordPress.com workflow to
 match local two-phase style

The remote-site system prompt had a handful of inherited problems from earlier
iterations: PHASE 2's HTML prototype told the agent to write to `<site>/tmp/...`
which doesn't exist on a remote-only session, the `${WORK_CADENCE}` include
leaked local-only rules (theme `cp`, ABSPATH eval) into a context that never
touches a theme file, and PHASE 3 had no `blockify` invocation before block
markup was produced.

Restructured workflow while keeping the 3-phase split that's natural for
remote (Audit / Prototype / Port):

- PHASE 1 Audit: plan gate + discovery + fetch global-styles ID.
- PHASE 2 Prototype: HTML/CSS/JS written to `~/.studio/tmp/prototype-<slug>/`
  on the local CLI machine, with an explicit FORBIDDEN list that bars any
  remote write (`wpcom_request` POST/PUT, plugin install, theme switch,
  global-styles edit) until the prototype screenshot is approved.
- PHASE 3 Port: invoke `blockify` first, translate to block markup in a
  local scratch file (so re-sends work if a POST fails), apply content via
  `wpcom_request POST /posts`, CSS via `POST /global-styles/<id>` with
  `settings.custom` (paid plans only), template changes via
  `POST /templates/<id>`, screenshot verify.

Replaced the shared `${WORK_CADENCE}` include with an inline remote cadence:
one content-producing `wpcom_request` per turn, GETs combinable, local
Write/Edit cadence during phase 2, anti-screenshot-serialization rule.

Narrowed the IMPORTANT line about tool restrictions: `Bash`/`Write`/`Edit`
are allowed for prototype scratch files, forbidden for the remote site
itself (only wpcom_request can change the site).
---
 apps/cli/ai/system-prompt.ts | 49 +++++++++++++++++++++---------------
 1 file changed, 29 insertions(+), 20 deletions(-)

diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index c4b944d0d0..f0ec1a0989 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -26,7 +26,7 @@ function buildRemoteIntro( site: RemoteSiteContext ): string {
 	return `${ AGENT_IDENTITY } You manage WordPress.com sites using the WordPress.com REST API.
 
 IMPORTANT: The active site is a remote WordPress.com site: "${ site.name }" (ID: ${ site.id }) at ${ site.url }.
-IMPORTANT: You MUST use the wpcom_request tool (prefixed with mcp__studio__) to manage this site. Do NOT use WP-CLI — this site is hosted on WordPress.com and that's our only way to edit it.
+IMPORTANT: You MUST use the wpcom_request tool (prefixed with mcp__studio__) to manage this site. Do NOT use WP-CLI. \`Bash\`/\`Write\`/\`Edit\` are ONLY for local prototype scratch files (phase 1) — never for modifying the remote site itself. The site is hosted on WordPress.com and only the REST API (via wpcom_request) can change it.
 IMPORTANT: Before doing ANY work, you MUST first check the site's plan by calling \`GET /\` (apiNamespace: \`""\`). The \`plan.product_slug\` field indicates the plan. If the site is on a free plan (e.g. \`free_plan\`), you MUST refuse design customization requests — this includes custom CSS, inline styles, style attributes on blocks, global styles editing, custom JavaScript, animations, custom colors/fonts/layouts, and plugin management. Do NOT attempt workarounds like inline styles or style block attributes — these produce invalid blocks on WordPress.com. Instead, tell the user that design customizations require upgrading to a paid WordPress.com plan and STOP. Do not proceed with the design task.
 
 ## Available Tools (prefixed with mcp__studio__)
@@ -81,25 +81,38 @@ Use \`per_page\` and \`page\` for pagination. Use \`status\` to filter by publis
 
 PHASE 1 — Audit.
 
-**Check the site plan** (MANDATORY FIRST STEP): Use \`GET /\` (apiNamespace: \`""\`) to get site info and check \`plan.product_slug\`. Stop and inform the user if they request features unavailable on their plan.
-**Understand the site**: Use \`GET /posts\` to list content, \`GET /themes?status=active\` to see the active theme.
+1. **Check the site plan** (MANDATORY FIRST STEP): Use \`GET /\` (apiNamespace: \`""\`) to get site info and check \`plan.product_slug\`. Stop and inform the user if they request features unavailable on their plan.
+2. **Understand the site**: Use \`GET /posts\` to list content, \`GET /themes?status=active\` to see the active theme, \`GET /templates\` / \`GET /template-parts\` if relevant. Use \`_fields\` to keep responses lightweight.
+3. **Find the global styles ID** (paid plans only, for later CSS work): \`GET /themes?status=active\` and extract the ID from \`_links["wp:user-global-styles"][0].href\`.
 
-PHASE 2 — HTML prototype. Write to <site>/tmp/prototype/.
- - Allowed: Write/Edit on index.html, about.html, services.html, style.css, app.js.
- - Phase 2 complete when: take_screenshot of the prototype index.html matches the expected design.
+PHASE 2 — HTML prototype. Write to a local scratch directory at \`~/.studio/tmp/prototype-<site-slug>/\` (create the directory with \`Bash: mkdir -p\`; derive \`<site-slug>\` from the site name). The prototype lives on the machine running this CLI; the remote WordPress.com site is never touched in this phase.
 
-PHASE 3 — Port to block content. Translate <site>/tmp/prototype/ to block markup
+- Allowed: Write/Edit on \`index.html\`, \`about.html\`, \`services.html\`, \`style.css\`, \`app.js\` inside \`~/.studio/tmp/prototype-<site-slug>/\` only.
+- FORBIDDEN in PHASE 2: any \`wpcom_request\` POST/PUT/DELETE, any \`/plugins/*/install\`, any \`POST /themes/mine\`, any \`POST /global-styles/*\`. Validating/editing the remote site before the prototype is screenshot-approved invalidates the build — restart.
+- Phase 2 complete when: \`take_screenshot\` of \`file:///.../prototype-<site-slug>/index.html\` matches the expected design.
 
-1. **Convert all the content of the different pages to insert to blocks as well** Use the block guidelines.
-2. **Make changes**: Use POST requests to create/update content, manage templates, switch themes.
-3. **Verify visually**: Use take_screenshot to capture the site on desktop and mobile viewports. Check spacing, alignment, colors, contrast, and layout. Fix any issues.
+PHASE 3 — Port to WordPress.com. Translate the prototype to block markup and send to the remote site via \`wpcom_request\`.
 
-${WORK_CADENCE}
+0. Invoke the \`blockify\` skill to load the HTML→block translation rules. Do NOT send any block markup to the remote site before this step completes.
+1. For each prototype HTML page, translate its sections to block markup using the blockify rules. Build the block markup in a local scratch file (e.g. \`~/.studio/tmp/prototype-<site-slug>/page-<slug>.blocks.html\`) so you can re-send it if the first POST fails.
+2. Apply the content to the remote site. For each page file:
+   - If the page exists (found in the PHASE 1 audit), update it: \`POST /posts/<id>\` with \`{ content: <block markup>, status: "publish" }\` (pass \`_fields=id,slug,status\` to keep the response small).
+   - If it's a new page: \`POST /posts\` with \`{ title, slug, content, status: "publish", type: "page" }\`.
+   - To set the homepage: \`POST /\` (apiNamespace: \`""\`) with \`{ settings: { show_on_front: "page", page_on_front: <id> } }\`, or the equivalent settings endpoint for the site.
+3. For CSS: paid plans only. Apply site-wide CSS via Global Styles — \`POST /global-styles/<id>\` with a body of \`{ settings: { custom: "<CSS string>" }, styles: {} }\`. The CSS string is the prototype's \`style.css\` contents (read via \`Read\` from the local prototype, no transformation beyond block-DOM selector adjustments for \`.wp-block-button\`/\`.wp-block-image\`/etc. — see the blockify skill). Free plans: skip this step and inform the user that CSS customization requires a paid plan.
+4. For template/template-part changes (e.g. header/footer block markup): \`POST /templates/<id>\` or \`POST /template-parts/<id>\` with \`{ content: <block markup> }\`.
+5. **Verify visually**: \`take_screenshot\` of the remote site URL on desktop and mobile. Check spacing, alignment, colors, contrast, layout. Fix any issues.
+
+## Working cadence
+
+One content-producing \`wpcom_request\` (POST/PUT/DELETE) per turn during PHASE 3. Read-only \`GET\`s may be combined. Short prose between tools. During PHASE 2, follow the local Write/Edit cadence — skeleton-first for long files, one anchor per Edit.
+
+**Don't re-screenshot after every individual change.** Apply all fixes from one screenshot review consecutively, THEN re-screenshot once. The \`change → screenshot → change → screenshot\` serialization wastes turns.
 
 ## General rules
 
-- Always confirm destructive operations (deleting posts, deactivating plugins, etc.) with the user before proceeding.
-- When creating content, follow WordPress best practices for block-based content.
+- Always confirm destructive operations (deleting posts, deactivating plugins, switching themes, wholesale content replacement) with the user before proceeding.
+- When creating content, follow WordPress best practices for block-based content (see the blockify skill).
 - If a requested operation fails, check the error message and suggest alternatives.
 - Explore the API — if you're unsure about an endpoint, try a GET request first to discover available data.`;
 }
@@ -168,8 +181,8 @@ ${WORK_CADENCE}
 - preview_list: List hosted WordPress.com previews for a local site
 - 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 once after completing a batch of related edits to block content — NOT after every individual Edit. When validate_blocks returns multiple errors, apply ALL fixes in one turn (multiple Edits in a single assistant message), then re-validate once. Do not serialize \`Edit → validate → Edit → validate\` — it wastes turns.
+- wp_cli: Run WP-CLI commands on a running site. Takes literal arguments, NOT a shell command — never use shell syntax such as pipes (\`|\`), redirection (\`>\`, \`<\`), command chaining (\`&&\`, \`;\`, \`||\`), backticks, command substitution (\`$(...)\`), or environment variables. A command like \`wp post get 4 --field=post_content | grep -o ...\` will not be interpreted as a pipeline; it will hang or fail. If you need to filter output, use \`wp_cli eval\` with PHP instead.
+- 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 once after a batch of related edits — NOT after every individual Edit. When validate_blocks returns multiple errors, apply all the fixes consecutively and re-validate once at the end. Do not serialize \`Edit → validate → Edit → validate\` — it wastes turns.
 - 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.
 - need_for_speed: 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.
 - rank_me_up: Run an on-page SEO audit (title/meta tags, headings, image alt text, OpenGraph/Twitter cards, JSON-LD structured data, robots.txt and sitemap.xml availability) for a running site. Use this to identify on-page SEO issues and guide fixes.
@@ -192,11 +205,7 @@ const WORK_CADENCE = `## Working cadence
 
 One \`Write\` or \`Edit\` or \`wpcom_request\` per turn during **content creation** — phase 1 anchor fills, phase 2 section translation, page-content anchors, initial file writes. Short prose between tools — no long design-plan essays. The CLI only renders complete assistant messages, so a turn that emits >~200 lines of new content spins silently for minutes and can hit gateway timeouts. Cadence is also a quality lever: the screenshot-fix loop only works after small visible increments.
 
-During **fix-up loops** (after \`validate_blocks\` flags errors, after \`take_screenshot\` reveals multiple issues, after user feedback lists multiple items), emit multiple independent Edits in one turn — one per issue. The anti-batching rule exists to prevent silent multi-minute generation of LARGE content, NOT to serialize small surgical fixes. 3–5 Edits of ≤500B each in one turn generate in about the same time as 1, and collapse what would be 3–5 turns into one.
-
-**Do NOT re-validate or re-screenshot after every individual Edit.** Apply all fixes from one validation or screenshot report in one turn (multiple Edits in the same assistant message), THEN re-validate or re-screenshot once. The \`Edit → validate → Edit → validate\` serialization is an anti-pattern — 10 fixes applied together take 2 turns (batch + verify); 10 fixes serialized take 20 turns for the same outcome.
-
-Examples: validate_blocks returns 3 invalid blocks → 3 Edits in one turn, then re-validate once. Screenshot shows wrong heading color, tight spacing, and missing border → 3 CSS Edits in one turn, then re-screenshot once.
+**Don't re-validate or re-screenshot after every individual Edit.** Apply all fixes from one \`validate_blocks\` report or one screenshot review consecutively, THEN re-validate or re-screenshot once. The \`Edit → validate → Edit → validate\` serialization is an anti-pattern — 10 fixes applied consecutively take 11 turns (10 Edits + 1 verify); 10 fixes with validation interleaved take 20 turns for the same outcome.
 
 **Skeleton first, then fill across Edits.** Applies always to prototype files (phase 1) regardless of size, and to any theme file >~200 lines.
 

From c30b16aef7987fab28b6891a324cfe10ef2be9b1 Mon Sep 17 00:00:00 2001
From: Riad Benguella <benguella@gmail.com>
Date: Thu, 23 Apr 2026 14:47:24 +0100
Subject: [PATCH 3/4] apps/cli: add CSS migration rules to blockify and
 theme.json neutralization
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses three recurring regressions observed in recent build sessions
(double button padding/borders, content centered too narrow, missing
section padding). All three share a root cause: WordPress block DOM and
theme.json defaults inject paint that fights prototype CSS when it is
copied verbatim to the theme.

Blockify skill:
- New "CSS migration after conversion" section with concrete rules for
  buttons, images, groups, and padding.
- Button rule is the highest-leverage: the `.wp-block-button` wrapper
  gets ZERO paint; all paint (background, border, padding, color, hover)
  goes on `.wp-block-button.<className> .wp-block-button__link`. Prevents
  the classic double-border artifact caused by `className` landing on
  the wrapper while `wp-element-button` defaults still paint the inner.
- Image rule splits figure-level vs img-level selectors.
- Group/section rule explains `is-layout-constrained` × `contentSize`
  and how to match the prototype's max-width.
- Padding rule keeps section padding on the className (CSS), not on
  block `style.spacing.padding` attributes, and surfaces theme.json
  defaults as the other common culprit.

System prompt PHASE 2 step 1:
- `theme.json` now MUST set `settings.layout.contentSize`/`wideSize`
  from the prototype's actual max-widths, and `styles.elements.button`
  to neutralize `wp-element-button`'s default paint. This makes the
  prototype CSS the only source of truth for visual styling.
- Block-DOM adjustments list now mirrors the blockify skill's CSS
  migration rules, with a pointer to the skill for context.
---
 apps/cli/ai/plugin/skills/blockify/SKILL.md | 69 ++++++++++++++++++++-
 apps/cli/ai/system-prompt.ts                | 13 ++--
 2 files changed, 75 insertions(+), 7 deletions(-)

diff --git a/apps/cli/ai/plugin/skills/blockify/SKILL.md b/apps/cli/ai/plugin/skills/blockify/SKILL.md
index 01f00c5e68..4c3acde0f1 100644
--- a/apps/cli/ai/plugin/skills/blockify/SKILL.md
+++ b/apps/cli/ai/plugin/skills/blockify/SKILL.md
@@ -12,7 +12,7 @@ Convert HTML input into native Gutenberg block markup. The goal is **FAITHFUL CO
 
 - **Input**: any HTML — a single section, a full page, a file you `Read`, a snippet the user pasted, the `post_content` of an existing post fetched via `wp_cli post get`. This skill does not care where the HTML came from.
 - **Output**: valid Gutenberg block markup that renders the same visual DOM. Return it inline in your response, write it to a file with `Write`/`Edit`, or apply it with `wp_cli post update` — whichever the caller asked for.
-- **Out of scope**: this skill does NOT modify CSS, theme files, or site content by default. It is a pure HTML → block markup transformation. If the caller wants the result applied somewhere, they invoke the appropriate tool after receiving the output.
+- **Out of scope**: this skill does not modify CSS or theme files itself. It provides the HTML → block markup translation AND the CSS selector adjustments you MUST make when porting prototype CSS to a block theme (see "CSS migration after conversion" below) so the theme renders identically to the prototype.
 
 ## Decompose — do not give up on a section
 
@@ -160,9 +160,74 @@ Replaces `<hr>`:
 <!-- /wp:separator -->
 ```
 
+## CSS migration after conversion
+
+Block markup renders different DOM than prototype HTML, and WordPress injects default paint via \`wp-element-*\` classes and theme.json styles. Prototype CSS copied verbatim to a block theme produces three classic symptoms: double button padding/borders, content narrower than the prototype, and missing section padding. The rules below are MANDATORY when porting prototype CSS to a theme — not optional polish.
+
+### Buttons — the wrapper carries NO paint
+
+\`core/button\` renders two stacked elements:
+
+- outer wrapper: \`<div class="wp-block-button <className>">\` — carries layout only (margin, flex alignment, width).
+- inner link: \`<a class="wp-block-button__link wp-element-button <className?>">\` — carries ALL paint.
+
+\`.wp-element-button\` already has default WordPress paint (padding, background, border). If your prototype \`.btn-primary { padding; border; background }\` is copied to the theme as-is, the \`className\` puts it on the outer wrapper via \`.wp-block-button.btn-primary\`, and the inner link keeps WordPress's defaults — you get doubled padding, doubled border, nested backgrounds.
+
+Rule: ALL button paint (background, border, padding, color, font, hover, transitions, shadow, border-radius) goes on \`.wp-block-button.<className> .wp-block-button__link\`. The \`.wp-block-button.<className>\` wrapper gets ZERO paint — only layout.
+
+Migration:
+- Delete: \`.btn-primary { background: gold; padding: 1rem 2rem; border: 2px solid gold; color: black; }\`
+- Add: \`.wp-block-button.btn-primary .wp-block-button__link { background: gold; padding: 1rem 2rem; border: 2px solid gold; color: black; }\`
+
+### Images — figure wrapper, and the img itself
+
+\`core/image\` renders:
+
+\`\`\`
+<figure class="wp-block-image <className>">
+  <img src="..." alt="..."/>
+</figure>
+\`\`\`
+
+Prototype \`.hero-image { ... }\` targeting a bare \`<img>\` now needs to decide:
+- figure-level styling (border-radius, box-shadow, outer layout) → \`.wp-block-image.hero-image { ... }\`
+- img-level styling (object-fit, aspect-ratio, sizing that has to apply to the pixel data) → \`.wp-block-image.hero-image img { ... }\`
+
+### Groups / sections — constrained layout fights max-width
+
+A \`core/group\` with \`layout: { type: "constrained" }\` picks up the class \`.is-layout-constrained\`. WordPress applies \`max-width: var(--wp--style--global--content-size)\` to every direct child via \`.is-layout-constrained > *\`. If theme.json's \`contentSize\` doesn't match the prototype's intended max-width, children get clamped to the WP default (often 840px) and content appears narrower than the prototype.
+
+Two fixes:
+- Set \`settings.layout.contentSize\` and \`settings.layout.wideSize\` in theme.json to match the prototype's actual max-widths (e.g. \`"1200px"\` and \`"1400px"\`).
+- For full-bleed sections (hero with a background-image that should go edge-to-edge), use \`layout: { type: "default" }\` on the group instead of \`constrained\` — default layout doesn't inject max-width.
+
+### Neutralize \`wp-element-button\` defaults in theme.json
+
+If your theme provides button styles via \`.wp-block-button.<className> .wp-block-button__link\` selectors, also neutralize the WordPress default so it stops leaking through:
+
+\`\`\`json
+"styles": {
+  "elements": {
+    "button": {
+      "color": { "background": "transparent", "text": "inherit" },
+      "spacing": { "padding": "0" },
+      "border": { "width": "0", "radius": "0" }
+    }
+  }
+}
+\`\`\`
+
+This makes \`wp-element-button\` a no-op; your className rules are the only source of button styling.
+
+### Section padding — keep it on the className, not on block attributes
+
+Prototype-style \`.hero-section { padding: var(--section-py) 0; }\` ports cleanly because \`className\` passes through to the outer \`<section class="wp-block-group hero-section">\`. Do NOT move this padding into \`style.spacing.padding\` block attributes — keep it in the stylesheet.
+
+If a section that SHOULD have padding renders without any, check two things: (a) whether \`theme.json\`'s \`styles.spacing.padding\` is setting a default that overrides the prototype rule (fix: remove or null that default), and (b) whether \`is-layout-constrained\` is shifting the padding onto the inner constrained element — make the selector more specific (\`section.hero-section.wp-block-group { padding: ... }\`) or switch the group to \`layout: { type: "default" }\`.
+
 ## Nesting
 
-Sections are built by nesting blocks inside `core/group`. The block structure is for editability; the stylesheet is for aesthetics. Never push layout, spacing, or color into block markup that belongs in CSS.
+Sections are built by nesting blocks inside \`core/group\`. The block structure is for editability; the stylesheet is for aesthetics. Never push layout, spacing, or color into block markup that belongs in CSS.
 
 ## Additional rules
 
diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index f0ec1a0989..17b3c3fc09 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -147,13 +147,16 @@ PHASE 2 — Port to block theme. Translate <site>/tmp/prototype/ to a block them
 0. Invoke the \`blockify\` skill to load the HTML→block translation rules.
    Do NOT write any block markup before this step completes.
 1. Build the block theme skeleton:
-   - \`theme.json\`, \`functions.php\`, \`parts/header.html\`, \`parts/footer.html\`, \`templates/index.html\`, \`templates/front-page.html\`.
+   - Files to create: \`theme.json\`, \`functions.php\`, \`parts/header.html\`, \`parts/footer.html\`, \`templates/index.html\`, \`templates/front-page.html\`.
+   - \`theme.json\` MUST set these keys to prevent WordPress defaults from fighting the prototype CSS (see the blockify skill's "CSS migration" section for context):
+     - \`settings.layout.contentSize\` and \`settings.layout.wideSize\` — match the prototype's intended max-widths (read them from \`prototype/style.css\`; common values are \`"1200px"\` / \`"1400px"\`).
+     - \`styles.elements.button\` = \`{ "color": { "background": "transparent", "text": "inherit" }, "spacing": { "padding": "0" }, "border": { "width": "0", "radius": "0" } }\` — neutralizes \`wp-element-button\`'s default paint so your \`.wp-block-button.<className> .wp-block-button__link\` rules are the only source of button styling.
    - Copy the prototype stylesheet as the starting point — do NOT regenerate:
      \`cp <site>/tmp/prototype/style.css <site>/wp-content/themes/<slug>/assets/css/main.css\` (via Bash).
-   - Apply block-DOM adjustments via Edits ONLY where WordPress changes the rendered DOM:
-     - button \`.<className>\` → \`.wp-block-button.<className> .wp-block-button__link\` (buttons split into wrapper + inner link).
-     - image \`.<className>\` → \`.wp-block-image.<className>\` (WordPress wraps images in \`<figure class="wp-block-image ...">\`).
-     - \`core/group\` sections — no selector change needed (the \`className\` passes through to the wrapper).
+   - Apply block-DOM adjustments via Edits — follow the blockify skill's "CSS migration after conversion" section. The critical rewrites:
+     - Buttons: move ALL paint from \`.btn-xxx { ... }\` onto \`.wp-block-button.btn-xxx .wp-block-button__link { ... }\`. The \`.wp-block-button\` wrapper gets ZERO paint. This prevents the classic double-border / double-background artifact.
+     - Images: prototype \`.<className>\` targeting a bare \`<img>\` → \`.wp-block-image.<className>\` for figure-level styling, \`.wp-block-image.<className> img\` for pixel-level styling (object-fit, aspect-ratio).
+     - \`core/group\` sections — className passes through; no selector change. But if content appears narrower than the prototype, check \`settings.layout.contentSize\` in theme.json (step above).
    - Everything else (tokens, layout, typography, animations) stays identical to the prototype. The phase-1 screenshot already validated this CSS; re-deriving it wastes generation time and risks drift.
 2. For each <section> in a prototype HTML file, translate to block markup
    using the blockify rules. Header/nav sections go into \`parts/header.html\`,

From 3ec3dd820c97a78d835f0c727a402ab1f7932036 Mon Sep 17 00:00:00 2001
From: Riad Benguella <benguella@gmail.com>
Date: Thu, 23 Apr 2026 14:58:24 +0100
Subject: [PATCH 4/4] apps/cli: fix prettier spacing in template literal

---
 apps/cli/ai/system-prompt.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index 17b3c3fc09..32c1f481bf 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -170,7 +170,7 @@ PHASE 2 — Port to block theme. Translate <site>/tmp/prototype/ to a block them
 4. For each prototype HTML file: (a) create an empty page with \`wp_cli post create --post_type=page --post_title="<title>" --post_status=publish --post_content="" --porcelain\` — this returns the new page ID; (b) apply the block markup with \`wp_cli eval '$content = file_get_contents(ABSPATH . "tmp/page-<slug>.html"); wp_update_post(["ID" => <id>, "post_content" => $content]); echo "ok";'\`. Do NOT use \`--post_content-file=<host path>\` — wp_cli runs inside the WASM filesystem and cannot read host paths, so the page updates to empty content silently. \`ABSPATH\` resolves to \`/wordpress/\` inside WASM, which maps to your site root. Finally, set the homepage via \`wp_cli option update show_on_front page\` and \`wp_cli option update page_on_front <id>\`.
 5. **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.
 
-${WORK_CADENCE}
+${ WORK_CADENCE }
 
 ## Available Studio Tools (prefixed with mcp__studio__)