From d4fdb7142e898b03653b898306324ef90e9cb382 Mon Sep 17 00:00:00 2001
From: Chris Huber <chubes@chubes.net>
Date: Thu, 30 Apr 2026 17:37:18 -0400
Subject: [PATCH 1/7] Draft BFB-backed raw HTML site builds

---
 apps/cli/ai/system-prompt.ts          |  20 ++--
 apps/cli/scripts/studio-bfb-smoke.mjs | 149 ++++++++++++++++++++++++++
 tools/common/lib/mu-plugins.ts        |  42 +++++++-
 3 files changed, 200 insertions(+), 11 deletions(-)
 create mode 100644 apps/cli/scripts/studio-bfb-smoke.mjs

diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index ee0a0e2a45..9765e43a71 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -98,7 +98,7 @@ Use \`per_page\` and \`page\` for pagination. Use \`status\` to filter by publis
 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.
+4. **Finish promptly**: Summarize what changed and let the user review the result. Do not run visual screenshot loops unless the user explicitly asks.
 
 ## General rules
 
@@ -134,8 +134,7 @@ 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.
+- Raw HTML/CSS for content: Check the content guidelines below.
 
 ## Workflow
 
@@ -151,20 +150,20 @@ 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.
+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. For static content, post content passed via \`wp post create\` or \`wp post update --post_content=...\` should be a raw HTML body fragment; block conversion happens automatically when WordPress stores it. The stored result still needs to be pre-validated for editability, validated using validate_blocks tool, and kept aligned with the block content guidelines above. 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. **Width check**: any section that was meant to be full-width (heroes, banners, edge-to-edge galleries, full-bleed footers) must visibly span the entire viewport in the desktop screenshot. If a "full-width" section only spans the content column (~700px at 1280px viewport), the block markup is missing \`align: "full"\` on the outer group or has a mismatched inner \`layout\` type — see the block-theme layout cascade rules above. Fix in markup, not custom CSS.
 
 ## Working cadence
 
-One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp_cli\` queries may be combined). Short prose between tools — no long design-plan essays. The CLI only renders complete assistant messages, so a turn that batches files or emits >~200 lines 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.
+One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp_cli\` queries may be combined). Short prose between tools — no long design-plan essays. The CLI only renders complete assistant messages, so a turn that batches files or emits >~200 lines spins silently for minutes and can hit gateway timeouts.
 
 **After \`site_create\`** (or "redesign"/"rebuild"/"start over" triggers), the next turn MUST be small: \`site_info\` or a single ≤50-line \`Write\`. Never scaffold a whole theme in one turn.
 
 **Long files (>~200 lines): skeleton first, then fill across Edits.**
 
 - \`style.css\`: skeleton = \`:root { ... }\` custom properties + 6–10 anchor comments \`/* === <concern> === */\` (e.g. \`reset\`, \`typography\`, \`hero\`, \`features\`, \`cta\`, \`footer\`, \`responsive\`), <2KB total. Fill one anchor per Edit (300–2000B each) — \`old_string\` is the anchor line, \`new_string\` is \`<anchor>\\n\\n<styles>\`.
-- Page content: create the page empty (\`wp_cli post create --post_content=""\`), write \`<site>/tmp/page-<slug>.html\` (not inside the theme) with \`<!-- section:<concern> -->\` anchors (<1KB), fill one anchor per Edit using only core blocks (never wrap in \`core/html\`), 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";'\`. Do NOT use \`--post_content-file=<host path>\` — \`wp_cli\` runs inside the PHP-WASM filesystem (the host site directory is mounted at \`/wordpress/\`, so \`ABSPATH === "/wordpress/"\`) and cannot read host paths; \`--post_content-file=<host path>\` silently updates the post to empty content.
+- Page content: create the page empty (\`wp_cli post create --post_content=""\`), write \`<site>/tmp/page-<slug>.html\` (not inside the theme) with \`<!-- section:<concern> -->\` anchors (<1KB), fill one anchor per Edit with a clean raw HTML body fragment (\`section\`, \`header\`, \`h1\`-\`h6\`, \`p\`, \`ul\`/\`ol\`, \`blockquote\`, \`figure\`, \`img\`, \`table\`, \`a\`, \`button\`) and CSS classes for styling, 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";'\`. Put CSS in the theme stylesheet. Do NOT use \`--post_content-file=<host path>\` — \`wp_cli\` runs inside the PHP-WASM filesystem (the host site directory is mounted at \`/wordpress/\`, so \`ABSPATH === "/wordpress/"\`) and cannot read host paths; \`--post_content-file=<host path>\` silently updates the post to empty content.
 
 ## Available Studio Tools (prefixed with mcp__studio__)
 
@@ -179,8 +178,7 @@ One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp
 - 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.
-- 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.
+- take_screenshot: Take a full-page screenshot of a URL (supports desktop and mobile viewports). Use only when the user explicitly asks for screenshot-based review.
 - 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.
 - site_connected_remote_sites: List the WordPress.com sites already attached to a local site. Call this before site_push to decide how to ask the user which remote site to target.
@@ -191,7 +189,7 @@ One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp
 
 ## 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 and visual ambition are not in conflict with Site Editor compatibility. Custom CSS targeting semantic HTML classes can achieve any visual design. WordPress stores the converted block structure 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).
@@ -244,7 +242,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
+const LOCAL_CONTENT_GUIDELINES = `## Content guidelines
 
 - Only use \`core/html\` blocks for:
 	- Inline SVGs
@@ -252,6 +250,8 @@ const LOCAL_CONTENT_GUIDELINES = `## Block content guidelines
 	- 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.
+- Provide raw HTML body fragments for page, post, and template content. Block conversion happens automatically when WordPress stores it.
+- Use semantic HTML elements for static content: \`section\`, \`header\`, \`main\`, \`h1\`-\`h6\`, \`p\`, \`ul\`, \`ol\`, \`blockquote\`, \`figure\`, \`img\`, \`table\`, \`a\`, and \`button\`.
 - 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/scripts/studio-bfb-smoke.mjs b/apps/cli/scripts/studio-bfb-smoke.mjs
new file mode 100644
index 0000000000..726f3b0c69
--- /dev/null
+++ b/apps/cli/scripts/studio-bfb-smoke.mjs
@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDir = dirname( fileURLToPath( import.meta.url ) );
+const cliPath = resolve( scriptDir, '../dist/cli/main.mjs' );
+const nodeBin = process.execPath;
+const sitePath = process.env.STUDIO_BFB_SMOKE_SITE || resolve( tmpdir(), 'studio-bfb-smoke' );
+const bfbPath = process.env.STUDIO_BFB_MU_PLUGIN_PATH;
+
+if ( ! bfbPath ) {
+	console.error( 'STUDIO_BFB_MU_PLUGIN_PATH is required.' );
+	process.exit( 1 );
+}
+
+if ( ! existsSync( cliPath ) ) {
+	console.error(
+		`Built Studio CLI not found at ${ cliPath }. Run homeboy rig up studio-bfb first.`
+	);
+	process.exit( 1 );
+}
+
+function run( args, options = {} ) {
+	const result = spawnSync( nodeBin, [ cliPath, ...args ], {
+		encoding: 'utf8',
+		env: { ...process.env, STUDIO_BFB_MU_PLUGIN_PATH: bfbPath },
+		...options,
+	} );
+
+	if ( result.status !== 0 ) {
+		if ( result.stdout ) {
+			process.stdout.write( result.stdout );
+		}
+		if ( result.stderr ) {
+			process.stderr.write( result.stderr );
+		}
+		throw new Error( `${ args.join( ' ' ) } exited ${ result.status }` );
+	}
+
+	return result;
+}
+
+function ensureSite() {
+	const status = spawnSync(
+		nodeBin,
+		[ cliPath, 'site', 'status', '--path', sitePath, '--format', 'json' ],
+		{
+			encoding: 'utf8',
+			env: { ...process.env, STUDIO_BFB_MU_PLUGIN_PATH: bfbPath },
+		}
+	);
+
+	if ( status.status === 0 ) {
+		return;
+	}
+
+	run( [
+		'site',
+		'create',
+		'--name',
+		'BFB Mu Plugin Smoke',
+		'--path',
+		sitePath,
+		'--skip-browser',
+		'--skip-log-details',
+	] );
+}
+
+function stopSite() {
+	spawnSync( nodeBin, [ cliPath, 'site', 'stop', '--path', sitePath ], {
+		encoding: 'utf8',
+		env: { ...process.env, STUDIO_BFB_MU_PLUGIN_PATH: bfbPath },
+	} );
+}
+
+const php = `
+update_option( 'studio_bfb_unsupported_fallback_count', 0, false );
+
+$results = array();
+$results['bfb_loaded'] = function_exists( 'bfb_convert' );
+$results['h2bc_loaded'] = function_exists( 'BlockFormatBridge\\Vendor\\html_to_blocks_raw_handler' );
+$results['write_hook'] = (bool) has_filter( 'wp_insert_post_data', 'BlockFormatBridge\\Vendor\\html_to_blocks_convert_on_insert' );
+
+$page_html = '<section class="hero"><h1>Deterministic Blocks</h1><p>Raw semantic HTML should become editable blocks.</p><ul><li>Fast</li><li>Native</li></ul><p><a class="wp-element-button" href="/#start">Start</a></p></section>';
+$page_id = wp_insert_post( array(
+	'post_title'   => 'BFB smoke page ' . time(),
+	'post_type'    => 'page',
+	'post_status'  => 'publish',
+	'post_content' => $page_html,
+) );
+if ( is_wp_error( $page_id ) ) {
+	throw new RuntimeException( $page_id->get_error_message() );
+}
+$page_stored = get_post_field( 'post_content', $page_id );
+
+$template_html = '<main class="site-shell"><section class="hero"><h1>Clean Block Template Smoke</h1><p>No fallback should fire.</p></section></main>';
+$template_id = wp_insert_post( array(
+	'post_title'   => 'bfb-smoke//main-' . time(),
+	'post_name'    => 'bfb-smoke//main-' . time(),
+	'post_type'    => 'wp_template',
+	'post_status'  => 'publish',
+	'post_content' => $template_html,
+) );
+if ( is_wp_error( $template_id ) ) {
+	throw new RuntimeException( $template_id->get_error_message() );
+}
+$template_stored = get_post_field( 'post_content', $template_id );
+
+$results['page_has_blocks'] = false !== strpos( $page_stored, '<!-- wp:' );
+$results['template_has_blocks'] = false !== strpos( $template_stored, '<!-- wp:' );
+$results['page_html_blocks'] = substr_count( $page_stored, 'wp:html' );
+$results['template_html_blocks'] = substr_count( $template_stored, 'wp:html' );
+$results['fallback_count'] = (int) get_option( 'studio_bfb_unsupported_fallback_count', 0 );
+$results['page_id'] = $page_id;
+$results['template_id'] = $template_id;
+
+echo wp_json_encode( $results, JSON_PRETTY_PRINT ) . PHP_EOL;
+
+foreach ( array( 'bfb_loaded', 'h2bc_loaded', 'write_hook', 'page_has_blocks', 'template_has_blocks' ) as $key ) {
+	if ( empty( $results[ $key ] ) ) {
+		throw new RuntimeException( 'Smoke failed: ' . $key );
+	}
+}
+
+if ( 0 !== $results['fallback_count'] ) {
+	throw new RuntimeException( 'Smoke failed: fallback_count=' . $results['fallback_count'] );
+}
+
+if ( 0 !== $results['page_html_blocks'] || 0 !== $results['template_html_blocks'] ) {
+	throw new RuntimeException( 'Smoke failed: core/html fallback block present' );
+}
+`;
+
+try {
+	ensureSite();
+	stopSite();
+	const result = run( [ 'wp', '--path', sitePath, '--php-version', '8.3', 'eval', php ] );
+	process.stdout.write( result.stdout );
+	if ( result.stderr ) {
+		process.stderr.write( result.stderr );
+	}
+	console.log( 'PASS: Studio/BFB raw HTML write path stores native blocks.' );
+} catch ( error ) {
+	console.error( error instanceof Error ? error.message : String( error ) );
+	process.exit( 1 );
+}
diff --git a/tools/common/lib/mu-plugins.ts b/tools/common/lib/mu-plugins.ts
index 9c337d3909..a3563f80ca 100644
--- a/tools/common/lib/mu-plugins.ts
+++ b/tools/common/lib/mu-plugins.ts
@@ -5,7 +5,7 @@
  * available to WordPress instances. Shared between desktop app and CLI.
  */
 
-import { copyFile, mkdir, mkdtemp, readdir, unlink, writeFile } from 'fs/promises';
+import { copyFile, mkdir, mkdtemp, readdir, symlink, unlink, writeFile } from 'fs/promises';
 import { tmpdir } from 'os';
 import path from 'path';
 
@@ -21,6 +21,8 @@ export interface MuPluginOptions {
 	runtime?: MuPluginRuntime;
 }
 
+const BFB_EXPERIMENT_PATH_ENV = 'STUDIO_BFB_MU_PLUGIN_PATH';
+
 /**
  * MU-plugin filenames that should not be written for native PHP sites.
  * These exist to work around behaviors specific to the Playground/PHP WASM
@@ -432,6 +434,38 @@ function getStandardMuPlugins( options: MuPluginOptions ): MuPlugin[] {
 		`,
 	} );
 
+	if ( process.env[ BFB_EXPERIMENT_PATH_ENV ] ) {
+		muPlugins.push( {
+			filename: '1-block-format-bridge-experiment.php',
+			content: `<?php
+			/**
+			 * Block Format Bridge experiment loader.
+			 *
+			 * Enabled only when Studio is launched with ${ BFB_EXPERIMENT_PATH_ENV }.
+			 */
+			$bfb_library = '/internal/studio/mu-plugins/block-format-bridge/library.php';
+			if ( file_exists( $bfb_library ) ) {
+				require_once $bfb_library;
+			}
+
+			add_filter( 'html_to_blocks_supported_post_types', function( $post_types ) {
+				return array_values( array_unique( array_merge( (array) $post_types, array(
+					'post',
+					'page',
+					'wp_template',
+					'wp_template_part',
+					'wp_navigation',
+				) ) ) );
+			} );
+
+			add_action( 'html_to_blocks_unsupported_html_fallback', function() {
+				$count = (int) get_option( 'studio_bfb_unsupported_fallback_count', 0 );
+				update_option( 'studio_bfb_unsupported_fallback_count', $count + 1, false );
+			}, 10, 3 );
+			`,
+		} );
+	}
+
 	// Studio Admin API: Persistent endpoint for admin operations
 	muPlugins.push( {
 		filename: '0-studio-admin-api.php',
@@ -603,6 +637,12 @@ async function createMuPluginsDirectory( options: MuPluginOptions ): Promise< st
 			const pluginPath = path.join( tempDir, plugin.filename );
 			await writeFile( pluginPath, plugin.content );
 		}
+
+		const bfbExperimentPath = process.env[ BFB_EXPERIMENT_PATH_ENV ];
+		if ( bfbExperimentPath ) {
+			await symlink( bfbExperimentPath, path.join( tempDir, 'block-format-bridge' ), 'dir' );
+		}
+
 		return tempDir;
 	} catch ( error ) {
 		throw new Error( `Failed to create mu-plugins directory: ${ error }` );

From 44dc3bffbd7e3dde0ef784e87fe545ecc059794d Mon Sep 17 00:00:00 2001
From: Chris Huber <chubes@chubes.net>
Date: Sat, 2 May 2026 21:52:28 -0400
Subject: [PATCH 2/7] Use Static Site Importer for generated local sites

---
 apps/cli/ai/system-prompt.ts          |  54 +++--------
 apps/cli/scripts/studio-bfb-smoke.mjs | 133 +++++++++++++++++---------
 tools/common/lib/mu-plugins.ts        |  37 ++++---
 3 files changed, 115 insertions(+), 109 deletions(-)

diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index 9765e43a71..9d979b53e4 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -131,10 +131,7 @@ Call \`preview_navigate\` / \`preview_reload\` as a side effect of your editing
 	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.
-- Raw HTML/CSS for content: Check the content guidelines below.
+IMPORTANT: For generated local sites, build a normal static HTML/CSS site first, then import it with Static Site Importer for WordPress block-theme output.
 
 ## Workflow
 
@@ -149,10 +146,9 @@ 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. For static content, post content passed via \`wp post create\` or \`wp post update --post_content=...\` should be a raw HTML body fragment; block conversion happens automatically when WordPress stores it. The stored result still needs to be pre-validated for editability, validated using validate_blocks tool, and kept aligned with the block content guidelines above. 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. **Width check**: any section that was meant to be full-width (heroes, banners, edge-to-edge galleries, full-bleed footers) must visibly span the entire viewport in the desktop screenshot. If a "full-width" section only spans the content column (~700px at 1280px viewport), the block markup is missing \`align: "full"\` on the outer group or has a mismatched inner \`layout\` type — see the block-theme layout cascade rules above. Fix in markup, not custom CSS.
+3. **Write the static site**: Use Write and Edit to create \`<site>/tmp/static-site/index.html\` as a full static HTML document with semantic body structure and CSS/assets.
+4. **Import into WordPress**: Use \`wp_cli\` to run \`static-site-importer import-theme /wordpress/tmp/static-site/index.html --slug=<theme-slug> --name="<Theme Name>" --activate --overwrite\`. The importer converts the static HTML into an editable block theme and front page. The \`wp_cli\` tool already runs WP-CLI, so do not prefix commands with \`wp\`. It takes one literal WP-CLI command per call, not shell commands: never combine commands with \`&&\`, \`;\`, pipes, redirection, shell substitution such as \`$(cat file)\`, backticks, environment variables, or host temp-file paths. Paths passed to WP-CLI must use WordPress's mounted filesystem (\`/wordpress/...\`), not host paths.
+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. **Width check**: any section that was meant to be full-width (heroes, banners, edge-to-edge galleries, full-bleed footers) must visibly span the entire viewport in the desktop screenshot.
 
 ## Working cadence
 
@@ -160,10 +156,7 @@ One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp
 
 **After \`site_create\`** (or "redesign"/"rebuild"/"start over" triggers), the next turn MUST be small: \`site_info\` or a single ≤50-line \`Write\`. Never scaffold a whole theme in one turn.
 
-**Long files (>~200 lines): skeleton first, then fill across Edits.**
-
-- \`style.css\`: skeleton = \`:root { ... }\` custom properties + 6–10 anchor comments \`/* === <concern> === */\` (e.g. \`reset\`, \`typography\`, \`hero\`, \`features\`, \`cta\`, \`footer\`, \`responsive\`), <2KB total. Fill one anchor per Edit (300–2000B each) — \`old_string\` is the anchor line, \`new_string\` is \`<anchor>\\n\\n<styles>\`.
-- Page content: create the page empty (\`wp_cli post create --post_content=""\`), write \`<site>/tmp/page-<slug>.html\` (not inside the theme) with \`<!-- section:<concern> -->\` anchors (<1KB), fill one anchor per Edit with a clean raw HTML body fragment (\`section\`, \`header\`, \`h1\`-\`h6\`, \`p\`, \`ul\`/\`ol\`, \`blockquote\`, \`figure\`, \`img\`, \`table\`, \`a\`, \`button\`) and CSS classes for styling, 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";'\`. Put CSS in the theme stylesheet. Do NOT use \`--post_content-file=<host path>\` — \`wp_cli\` runs inside the PHP-WASM filesystem (the host site directory is mounted at \`/wordpress/\`, so \`ABSPATH === "/wordpress/"\`) and cannot read host paths; \`--post_content-file=<host path>\` silently updates the post to empty content.
+**Long static HTML files (>~200 lines): skeleton first, then fill across Edits.** Create \`index.html\` with the document shell, \`<style>\` block anchors, and body section anchors first; fill one section/anchor per Edit.
 
 ## Available Studio Tools (prefixed with mcp__studio__)
 
@@ -189,13 +182,10 @@ One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp
 
 ## General rules
 
-- Design quality and visual ambition are not in conflict with Site Editor compatibility. Custom CSS targeting semantic HTML classes can achieve any visual design. WordPress stores the converted block structure for editability; the CSS is for aesthetics.
+- Design quality and visual ambition are not in conflict with Site Editor compatibility. Normal static HTML/CSS targeting semantic classes can achieve any visual design; the importer turns that static site into editable WordPress block theme output.
 - 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.
-- Always enqueue the theme's style.css on the frontend from functions.php.
-- For theme and page content custom CSS, put the styles in the main style.css of the theme. No custom stylesheets.
+- Let Static Site Importer generate and activate the block theme. Do not manually create theme files unless the user explicitly asks for custom plugin/theme development.
 - 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;\`).
 
@@ -244,31 +234,11 @@ const REMOTE_DESIGN_GUIDELINES = `## Design capabilities by plan
 
 const LOCAL_CONTENT_GUIDELINES = `## 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.
-- Provide raw HTML body fragments for page, post, and template content. Block conversion happens automatically when WordPress stores it.
-- Use semantic HTML elements for static content: \`section\`, \`header\`, \`main\`, \`h1\`-\`h6\`, \`p\`, \`ul\`, \`ol\`, \`blockquote\`, \`figure\`, \`img\`, \`table\`, \`a\`, and \`button\`.
-- 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.
-
-## Block-theme layout cascade
-
-WordPress constrains children of \`core/post-content\` (and any constrained-layout container) to \`theme.json\`'s \`settings.layout.contentSize\` (~700px by default). Custom CSS like \`.hero { width: 100% }\` does NOT win against core's layout selectors (\`.is-layout-constrained > *:not(.alignwide):not(.alignfull)\`) because they're more specific.
-
-To break out of the content width, use these three patterns:
-
-- **Full-bleed section, constrained inner content** (most common — full-width hero with text in the middle): outer \`core/group {"align":"full","layout":{"type":"constrained"}}\` containing a default-layout child for the inner block.
-- **Full-bleed section, full-bleed inner** (image grids, edge-to-edge galleries): outer AND inner \`core/group {"align":"full","layout":{"type":"default"}}\`. Children render at full viewport width.
-- **Standard constrained content**: omit \`align\` entirely and write blocks normally.
-
-The single most common failure is "I made a hero full-width but its inner content is narrow" — that's a missing \`align: "full"\` on the outer group or a mismatched inner \`layout\` type. Fix in markup, not in CSS.`;
+- Build local generated sites as normal static HTML/CSS in \`<site>/tmp/static-site/index.html\`.
+- Use semantic HTML elements: \`section\`, \`header\`, \`main\`, \`footer\`, \`nav\`, \`h1\`-\`h6\`, \`p\`, \`ul\`, \`ol\`, \`blockquote\`, \`figure\`, \`img\`, \`table\`, \`a\`, and \`button\`.
+- Use CSS classes for styling hooks and keep the visual system in the static HTML/CSS that will be imported.
+- Static Site Importer handles the WordPress block-theme conversion.
+- No emojis anywhere in generated content.`;
 
 const LOCAL_DESIGN_GUIDELINES = `## Design guidelines
 
diff --git a/apps/cli/scripts/studio-bfb-smoke.mjs b/apps/cli/scripts/studio-bfb-smoke.mjs
index 726f3b0c69..8370a639b3 100644
--- a/apps/cli/scripts/studio-bfb-smoke.mjs
+++ b/apps/cli/scripts/studio-bfb-smoke.mjs
@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -8,11 +8,13 @@ import { fileURLToPath } from 'node:url';
 const scriptDir = dirname( fileURLToPath( import.meta.url ) );
 const cliPath = resolve( scriptDir, '../dist/cli/main.mjs' );
 const nodeBin = process.execPath;
-const sitePath = process.env.STUDIO_BFB_SMOKE_SITE || resolve( tmpdir(), 'studio-bfb-smoke' );
-const bfbPath = process.env.STUDIO_BFB_MU_PLUGIN_PATH;
+const sitePath =
+	process.env.STUDIO_STATIC_SITE_IMPORTER_SMOKE_SITE ||
+	resolve( tmpdir(), 'studio-static-site-importer-smoke' );
+const importerPath = process.env.STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH;
 
-if ( ! bfbPath ) {
-	console.error( 'STUDIO_BFB_MU_PLUGIN_PATH is required.' );
+if ( ! importerPath ) {
+	console.error( 'STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH is required.' );
 	process.exit( 1 );
 }
 
@@ -23,10 +25,14 @@ if ( ! existsSync( cliPath ) ) {
 	process.exit( 1 );
 }
 
+function env() {
+	return { ...process.env, STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH: importerPath };
+}
+
 function run( args, options = {} ) {
 	const result = spawnSync( nodeBin, [ cliPath, ...args ], {
 		encoding: 'utf8',
-		env: { ...process.env, STUDIO_BFB_MU_PLUGIN_PATH: bfbPath },
+		env: env(),
 		...options,
 	} );
 
@@ -49,7 +55,7 @@ function ensureSite() {
 		[ cliPath, 'site', 'status', '--path', sitePath, '--format', 'json' ],
 		{
 			encoding: 'utf8',
-			env: { ...process.env, STUDIO_BFB_MU_PLUGIN_PATH: bfbPath },
+			env: env(),
 		}
 	);
 
@@ -61,7 +67,7 @@ function ensureSite() {
 		'site',
 		'create',
 		'--name',
-		'BFB Mu Plugin Smoke',
+		'Static Site Importer Smoke',
 		'--path',
 		sitePath,
 		'--skip-browser',
@@ -72,77 +78,112 @@ function ensureSite() {
 function stopSite() {
 	spawnSync( nodeBin, [ cliPath, 'site', 'stop', '--path', sitePath ], {
 		encoding: 'utf8',
-		env: { ...process.env, STUDIO_BFB_MU_PLUGIN_PATH: bfbPath },
+		env: env(),
 	} );
 }
 
+function writeStaticFixture() {
+	const fixtureDir = resolve( sitePath, 'tmp/static-site-importer-smoke' );
+	mkdirSync( fixtureDir, { recursive: true } );
+	writeFileSync(
+		resolve( fixtureDir, 'index.html' ),
+		`<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Static Importer Smoke</title>
+  <style>
+    :root { --bg: #101018; --text: #f7f7fb; --accent: #42e8c5; }
+    body { margin: 0; background: var(--bg); color: var(--text); font-family: system-ui, sans-serif; }
+    .site-header, .site-footer { padding: 24px; border-color: rgba(255,255,255,.12); }
+    .hero { padding: 72px 24px; }
+    .cta { color: var(--bg); background: var(--accent); padding: 12px 18px; border-radius: 999px; }
+  </style>
+</head>
+<body>
+  <header class="site-header"><a class="brand" href="index.html">Studio Code</a><nav><a href="#start">Start</a></nav></header>
+  <main>
+    <section class="hero"><h1>Imported Static Site</h1><p>Static HTML should become editable block theme output.</p><a class="cta" href="#start">Start</a></section>
+    <section id="start"><h2>Workflow</h2><ol><li>Generate HTML</li><li>Import theme</li><li>Edit blocks</li></ol></section>
+  </main>
+  <footer class="site-footer"><p>Built with Static Site Importer.</p></footer>
+</body>
+</html>
+`,
+		'utf8'
+	);
+}
+
 const php = `
 update_option( 'studio_bfb_unsupported_fallback_count', 0, false );
 
 $results = array();
+$results['importer_loaded'] = class_exists( 'Static_Site_Importer_Theme_Generator' );
 $results['bfb_loaded'] = function_exists( 'bfb_convert' );
 $results['h2bc_loaded'] = function_exists( 'BlockFormatBridge\\Vendor\\html_to_blocks_raw_handler' );
-$results['write_hook'] = (bool) has_filter( 'wp_insert_post_data', 'BlockFormatBridge\\Vendor\\html_to_blocks_convert_on_insert' );
-
-$page_html = '<section class="hero"><h1>Deterministic Blocks</h1><p>Raw semantic HTML should become editable blocks.</p><ul><li>Fast</li><li>Native</li></ul><p><a class="wp-element-button" href="/#start">Start</a></p></section>';
-$page_id = wp_insert_post( array(
-	'post_title'   => 'BFB smoke page ' . time(),
-	'post_type'    => 'page',
-	'post_status'  => 'publish',
-	'post_content' => $page_html,
+
+$html_path = ABSPATH . 'tmp/static-site-importer-smoke/index.html';
+$result = Static_Site_Importer_Theme_Generator::import_theme( $html_path, array(
+	'slug' => 'studio-static-importer-smoke',
+	'name' => 'Studio Static Importer Smoke',
+	'activate' => true,
+	'overwrite' => true,
 ) );
-if ( is_wp_error( $page_id ) ) {
-	throw new RuntimeException( $page_id->get_error_message() );
+if ( is_wp_error( $result ) ) {
+	throw new RuntimeException( $result->get_error_message() );
 }
-$page_stored = get_post_field( 'post_content', $page_id );
-
-$template_html = '<main class="site-shell"><section class="hero"><h1>Clean Block Template Smoke</h1><p>No fallback should fire.</p></section></main>';
-$template_id = wp_insert_post( array(
-	'post_title'   => 'bfb-smoke//main-' . time(),
-	'post_name'    => 'bfb-smoke//main-' . time(),
-	'post_type'    => 'wp_template',
-	'post_status'  => 'publish',
-	'post_content' => $template_html,
-) );
-if ( is_wp_error( $template_id ) ) {
-	throw new RuntimeException( $template_id->get_error_message() );
+
+$theme_dir = $result['theme_dir'];
+$files = array(
+	'parts/header.html',
+	'parts/footer.html',
+	'templates/front-page.html',
+	'templates/page-home.html',
+	'patterns/page-home.php',
+	'style.css',
+	'theme.json',
+);
+foreach ( $files as $file ) {
+	$results['file:' . $file] = file_exists( $theme_dir . '/' . $file );
 }
-$template_stored = get_post_field( 'post_content', $template_id );
 
-$results['page_has_blocks'] = false !== strpos( $page_stored, '<!-- wp:' );
-$results['template_has_blocks'] = false !== strpos( $template_stored, '<!-- wp:' );
-$results['page_html_blocks'] = substr_count( $page_stored, 'wp:html' );
-$results['template_html_blocks'] = substr_count( $template_stored, 'wp:html' );
+$home_page_id = $result['pages']['index.html'] ?? 0;
+$results['front_page_id'] = (int) get_option( 'page_on_front', 0 );
+$results['home_page_id'] = (int) $home_page_id;
+$results['active_theme'] = get_stylesheet();
 $results['fallback_count'] = (int) get_option( 'studio_bfb_unsupported_fallback_count', 0 );
-$results['page_id'] = $page_id;
-$results['template_id'] = $template_id;
+$results['header_html_blocks'] = substr_count( (string) file_get_contents( $theme_dir . '/parts/header.html' ), 'wp:html' );
+$results['footer_html_blocks'] = substr_count( (string) file_get_contents( $theme_dir . '/parts/footer.html' ), 'wp:html' );
+$results['pattern_has_blocks'] = false !== strpos( (string) file_get_contents( $theme_dir . '/patterns/page-home.php' ), '<!-- wp:' );
 
 echo wp_json_encode( $results, JSON_PRETTY_PRINT ) . PHP_EOL;
 
-foreach ( array( 'bfb_loaded', 'h2bc_loaded', 'write_hook', 'page_has_blocks', 'template_has_blocks' ) as $key ) {
+foreach ( array( 'importer_loaded', 'bfb_loaded', 'h2bc_loaded', 'pattern_has_blocks' ) as $key ) {
 	if ( empty( $results[ $key ] ) ) {
 		throw new RuntimeException( 'Smoke failed: ' . $key );
 	}
 }
-
-if ( 0 !== $results['fallback_count'] ) {
-	throw new RuntimeException( 'Smoke failed: fallback_count=' . $results['fallback_count'] );
+foreach ( $files as $file ) {
+	$key = 'file:' . $file;
+	if ( empty( $results[ $key ] ) ) {
+		throw new RuntimeException( 'Smoke failed missing file: ' . $file );
+	}
 }
-
-if ( 0 !== $results['page_html_blocks'] || 0 !== $results['template_html_blocks'] ) {
-	throw new RuntimeException( 'Smoke failed: core/html fallback block present' );
+if ( $results['front_page_id'] !== $results['home_page_id'] ) {
+	throw new RuntimeException( 'Smoke failed: imported home page is not the front page' );
 }
 `;
 
 try {
 	ensureSite();
+	writeStaticFixture();
 	stopSite();
 	const result = run( [ 'wp', '--path', sitePath, '--php-version', '8.3', 'eval', php ] );
 	process.stdout.write( result.stdout );
 	if ( result.stderr ) {
 		process.stderr.write( result.stderr );
 	}
-	console.log( 'PASS: Studio/BFB raw HTML write path stores native blocks.' );
+	console.log( 'PASS: Studio Static Site Importer smoke generated an editable block theme.' );
 } catch ( error ) {
 	console.error( error instanceof Error ? error.message : String( error ) );
 	process.exit( 1 );
diff --git a/tools/common/lib/mu-plugins.ts b/tools/common/lib/mu-plugins.ts
index a3563f80ca..98980c0164 100644
--- a/tools/common/lib/mu-plugins.ts
+++ b/tools/common/lib/mu-plugins.ts
@@ -21,7 +21,7 @@ export interface MuPluginOptions {
 	runtime?: MuPluginRuntime;
 }
 
-const BFB_EXPERIMENT_PATH_ENV = 'STUDIO_BFB_MU_PLUGIN_PATH';
+const STATIC_SITE_IMPORTER_EXPERIMENT_PATH_ENV = 'STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH';
 
 /**
  * MU-plugin filenames that should not be written for native PHP sites.
@@ -434,30 +434,20 @@ function getStandardMuPlugins( options: MuPluginOptions ): MuPlugin[] {
 		`,
 	} );
 
-	if ( process.env[ BFB_EXPERIMENT_PATH_ENV ] ) {
+	if ( process.env[ STATIC_SITE_IMPORTER_EXPERIMENT_PATH_ENV ] ) {
 		muPlugins.push( {
-			filename: '1-block-format-bridge-experiment.php',
+			filename: '1-static-site-importer-experiment.php',
 			content: `<?php
 			/**
-			 * Block Format Bridge experiment loader.
+			 * Static Site Importer experiment loader.
 			 *
-			 * Enabled only when Studio is launched with ${ BFB_EXPERIMENT_PATH_ENV }.
+			 * Enabled only when Studio is launched with ${ STATIC_SITE_IMPORTER_EXPERIMENT_PATH_ENV }.
 			 */
-			$bfb_library = '/internal/studio/mu-plugins/block-format-bridge/library.php';
-			if ( file_exists( $bfb_library ) ) {
-				require_once $bfb_library;
+			$static_site_importer_plugin = __DIR__ . '/static-site-importer/static-site-importer.php';
+			if ( file_exists( $static_site_importer_plugin ) ) {
+				require_once $static_site_importer_plugin;
 			}
 
-			add_filter( 'html_to_blocks_supported_post_types', function( $post_types ) {
-				return array_values( array_unique( array_merge( (array) $post_types, array(
-					'post',
-					'page',
-					'wp_template',
-					'wp_template_part',
-					'wp_navigation',
-				) ) ) );
-			} );
-
 			add_action( 'html_to_blocks_unsupported_html_fallback', function() {
 				$count = (int) get_option( 'studio_bfb_unsupported_fallback_count', 0 );
 				update_option( 'studio_bfb_unsupported_fallback_count', $count + 1, false );
@@ -638,9 +628,14 @@ async function createMuPluginsDirectory( options: MuPluginOptions ): Promise< st
 			await writeFile( pluginPath, plugin.content );
 		}
 
-		const bfbExperimentPath = process.env[ BFB_EXPERIMENT_PATH_ENV ];
-		if ( bfbExperimentPath ) {
-			await symlink( bfbExperimentPath, path.join( tempDir, 'block-format-bridge' ), 'dir' );
+		const staticSiteImporterExperimentPath =
+			process.env[ STATIC_SITE_IMPORTER_EXPERIMENT_PATH_ENV ];
+		if ( staticSiteImporterExperimentPath ) {
+			await symlink(
+				staticSiteImporterExperimentPath,
+				path.join( tempDir, 'static-site-importer' ),
+				'dir'
+			);
 		}
 
 		return tempDir;

From 27942dc267735eefd5c487118b16e9c5fcc82614 Mon Sep 17 00:00:00 2001
From: Chris Huber <chubes@chubes.net>
Date: Mon, 4 May 2026 06:39:47 -0400
Subject: [PATCH 3/7] Bundle Static Site Importer via wp-files download chain

Drops the STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH env-var contract that
required reviewers to clone chubes4/static-site-importer separately and
point Studio at it. The PR is now self-contained: a fresh `npm install`
fetches SSI's main zipball and extracts it into wp-files/, the CLI bundle
ships it, and the mu-plugin loader symlinks from the bundle path.

- scripts/download-wp-server-files.ts: add a `static-site-importer`
  entry that pulls https://github.com/chubes4/static-site-importer/archive/refs/heads/main.zip
  and renames the extracted root into wp-files/static-site-importer/.
  Iteration-mode contract: re-running `npm install` refreshes SSI to
  the current main HEAD. Before the PR un-drafts, swap the URL for a
  pinned tag/sha to lock the substrate.
- apps/cli/lib/dependency-management/paths.ts: expose
  `getStaticSiteImporterPluginPath()` resolving against `getWpFilesPath()`.
- tools/common/lib/mu-plugins.ts: drop the env-var gate. The SSI loader
  mu-plugin and the symlink branch now key on `options.staticSiteImporterPluginPath`,
  passed in from each CLI runtime entry point.
- apps/cli/{php-server-child,playground-server-child}.ts and
  apps/cli/lib/run-wp-cli-command.ts: pass the bundled SSI path through
  to mu-plugin generation.
- apps/cli/scripts/studio-bfb-smoke.mjs: drop the env-var requirement;
  the bundled CLI already knows where SSI lives.
- tools/common/lib/tests/mu-plugins.test.ts: cover loader + symlink
  presence when an SSI path is provided, and absence when it isn't.
- Rename mu-plugin filename from 1-static-site-importer-experiment.php
  to 1-static-site-importer.php, and add the old name to the legacy
  cleanup list so existing installs scrub it.

Also bundles two unrelated prompt/UI tweaks from the same iteration:
- system-prompt.ts: drop two outdated guidance lines now superseded by
  the SSI workflow itself.
- ui.ts: welcome text "block themes" -> "WordPress sites" for accuracy.

## AI assistance
- **AI assistance:** Yes
- **Tool(s):** Claude Code (Sonnet 4.5)
- **Used for:** Drafted the wp-files download entry, mu-plugin contract
  refactor, smoke-script clean-up, and tests under Chris's direction
  and review.
---
 apps/cli/ai/system-prompt.ts                |  3 --
 apps/cli/ai/ui.ts                           |  2 +-
 apps/cli/lib/dependency-management/paths.ts |  8 ++++
 apps/cli/lib/run-wp-cli-command.ts          |  8 +++-
 apps/cli/php-server-child.ts                | 10 ++++-
 apps/cli/playground-server-child.ts         |  2 +
 apps/cli/scripts/studio-bfb-smoke.mjs       | 44 +++++++------------
 scripts/download-wp-server-files.ts         | 40 +++++++++++++++++
 tools/common/lib/mu-plugins.ts              | 44 +++++++++++++------
 tools/common/lib/tests/mu-plugins.test.ts   | 48 +++++++++++++++++++++
 10 files changed, 161 insertions(+), 48 deletions(-)

diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index 9d979b53e4..aadb3af925 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -156,8 +156,6 @@ One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp
 
 **After \`site_create\`** (or "redesign"/"rebuild"/"start over" triggers), the next turn MUST be small: \`site_info\` or a single ≤50-line \`Write\`. Never scaffold a whole theme in one turn.
 
-**Long static HTML files (>~200 lines): skeleton first, then fill across Edits.** Create \`index.html\` with the document shell, \`<style>\` block anchors, and body section anchors first; fill one section/anchor per Edit.
-
 ## Available Studio Tools (prefixed with mcp__studio__)
 
 - site_create: Create a new WordPress site (name only — handles everything automatically)
@@ -182,7 +180,6 @@ One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp
 
 ## General rules
 
-- Design quality and visual ambition are not in conflict with Site Editor compatibility. Normal static HTML/CSS targeting semantic classes can achieve any visual design; the importer turns that static site into editable WordPress block theme output.
 - Do NOT modify WordPress core files. Only work within wp-content/.
 - Before running wp_cli, ensure the site is running (site_start if needed).
 - Let Static Site Importer generate and activate the block theme. Do not manually create theme files unless the user explicitly asks for custom plugin/theme development.
diff --git a/apps/cli/ai/ui.ts b/apps/cli/ai/ui.ts
index 0348307b02..988d425db7 100644
--- a/apps/cli/ai/ui.ts
+++ b/apps/cli/ai/ui.ts
@@ -1549,7 +1549,7 @@ export class AiChatUI implements AiOutputAdapter {
 			'  - ' +
 				sprintf(
 					/* translators: %s: bold "Build" */
-					__( '%s block themes with striking, memorable designs' ),
+					__( '%s WordPress sites with striking, memorable designs' ),
 					b( __( 'Build' ) )
 				),
 			'  - ' +
diff --git a/apps/cli/lib/dependency-management/paths.ts b/apps/cli/lib/dependency-management/paths.ts
index be42d158b2..5018440e89 100644
--- a/apps/cli/lib/dependency-management/paths.ts
+++ b/apps/cli/lib/dependency-management/paths.ts
@@ -55,3 +55,11 @@ export function getPhpMyAdminPath(): string {
 export function getBlueprintsPharPath(): string {
 	return path.join( getWpFilesPath(), 'blueprints', 'blueprints.phar' );
 }
+
+// Static Site Importer ships read-only with the CLI bundle (downloaded at npm
+// install time by `scripts/download-wp-server-files.ts`) and is symlinked into
+// each site's mu-plugins temp directory. No writable cache needed — the
+// bundled directory is treated as the source of truth.
+export function getStaticSiteImporterPluginPath(): string {
+	return path.join( getWpFilesPath(), 'static-site-importer' );
+}
diff --git a/apps/cli/lib/run-wp-cli-command.ts b/apps/cli/lib/run-wp-cli-command.ts
index a5034fc2c3..a2c603005f 100644
--- a/apps/cli/lib/run-wp-cli-command.ts
+++ b/apps/cli/lib/run-wp-cli-command.ts
@@ -25,6 +25,7 @@ import { setupPlatformLevelMuPlugins } from '@wp-playground/wordpress';
 import {
 	getPhpBinaryPath,
 	getSqliteCommandPath,
+	getStaticSiteImporterPluginPath,
 	getWpCliPharPath,
 } from 'cli/lib/dependency-management/paths';
 import { validatePhpVersion } from 'cli/lib/utils';
@@ -123,7 +124,11 @@ async function runNativeWpCliCommand(
 ): Promise< DisposableWpCliResponse > {
 	const nativeArgs = applyWpCliCommandOptions( 'native', args, options );
 	const phpVersion = validateNativePhpVersion( options.phpVersion ?? DEFAULT_PHP_VERSION );
-	await writeStudioMuPluginsForNativePhpRuntime( site.path, site.isWpAutoUpdating );
+	await writeStudioMuPluginsForNativePhpRuntime(
+		site.path,
+		site.isWpAutoUpdating,
+		getStaticSiteImporterPluginPath()
+	);
 	const child = spawn(
 		getPhpBinaryPath( phpVersion ),
 		[ getWpCliPharPath(), `--path=${ site.path }`, ...nativeArgs ],
@@ -219,6 +224,7 @@ export async function runWpCliCommand(
 		// Mount mu-plugins
 		const [ studioMuPluginsHostPath, loaderMuPluginHostPath ] = await getMuPlugins( {
 			isWpAutoUpdating: false,
+			staticSiteImporterPluginPath: getStaticSiteImporterPluginPath(),
 		} );
 		await php.mount(
 			'/internal/studio/mu-plugins',
diff --git a/apps/cli/php-server-child.ts b/apps/cli/php-server-child.ts
index efdafd84bf..18e1e14a31 100644
--- a/apps/cli/php-server-child.ts
+++ b/apps/cli/php-server-child.ts
@@ -27,6 +27,7 @@ import {
 import {
 	getBlueprintsPharPath,
 	getPhpBinaryPath,
+	getStaticSiteImporterPluginPath,
 	getWpCliPharPath,
 } from './lib/dependency-management/paths';
 
@@ -316,7 +317,11 @@ async function startServer( config: ServerConfig, signal: AbortSignal ): Promise
 		stopSignal.throwIfAborted();
 		await ensureWpConfig( config.sitePath, phpVersion, stopSignal, config );
 		stopSignal.throwIfAborted();
-		await writeStudioMuPluginsForNativePhpRuntime( config.sitePath, config.isWpAutoUpdating );
+		await writeStudioMuPluginsForNativePhpRuntime(
+			config.sitePath,
+			config.isWpAutoUpdating,
+			getStaticSiteImporterPluginPath()
+		);
 		stopSignal.throwIfAborted();
 		await installWordPress( config, phpVersion, stopSignal );
 		stopSignal.throwIfAborted();
@@ -594,7 +599,8 @@ async function ipcMessageHandler( packet: unknown ) {
 				);
 				await writeStudioMuPluginsForNativePhpRuntime(
 					blueprintConfig.sitePath,
-					blueprintConfig.isWpAutoUpdating
+					blueprintConfig.isWpAutoUpdating,
+					getStaticSiteImporterPluginPath()
 				);
 				await installWordPress( blueprintConfig, blueprintPhpVersion, abortController.signal );
 				if ( ! blueprintConfig.blueprint ) {
diff --git a/apps/cli/playground-server-child.ts b/apps/cli/playground-server-child.ts
index 0cd3fb40fa..393d98fc1a 100644
--- a/apps/cli/playground-server-child.ts
+++ b/apps/cli/playground-server-child.ts
@@ -35,6 +35,7 @@ import { sanitizeRunCLIArgs } from 'cli/lib/cli-args-sanitizer';
 import {
 	getPhpMyAdminPath,
 	getSqliteCommandPath,
+	getStaticSiteImporterPluginPath,
 	getWpCliPharPath,
 } from 'cli/lib/dependency-management/paths';
 import { rewriteWpCliPostContentToFile } from 'cli/lib/rewrite-wp-cli-post-content';
@@ -222,6 +223,7 @@ async function getBaseRunCLIArgs(
 
 	const [ studioMuPluginsHostPath, loaderMuPluginHostPath ] = await getMuPlugins( {
 		isWpAutoUpdating: config.isWpAutoUpdating,
+		staticSiteImporterPluginPath: getStaticSiteImporterPluginPath(),
 	} );
 
 	if ( ! useExactMountLayout ) {
diff --git a/apps/cli/scripts/studio-bfb-smoke.mjs b/apps/cli/scripts/studio-bfb-smoke.mjs
index 8370a639b3..aa8b8d5bcc 100644
--- a/apps/cli/scripts/studio-bfb-smoke.mjs
+++ b/apps/cli/scripts/studio-bfb-smoke.mjs
@@ -11,12 +11,6 @@ const nodeBin = process.execPath;
 const sitePath =
 	process.env.STUDIO_STATIC_SITE_IMPORTER_SMOKE_SITE ||
 	resolve( tmpdir(), 'studio-static-site-importer-smoke' );
-const importerPath = process.env.STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH;
-
-if ( ! importerPath ) {
-	console.error( 'STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH is required.' );
-	process.exit( 1 );
-}
 
 if ( ! existsSync( cliPath ) ) {
 	console.error(
@@ -25,14 +19,9 @@ if ( ! existsSync( cliPath ) ) {
 	process.exit( 1 );
 }
 
-function env() {
-	return { ...process.env, STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH: importerPath };
-}
-
 function run( args, options = {} ) {
 	const result = spawnSync( nodeBin, [ cliPath, ...args ], {
 		encoding: 'utf8',
-		env: env(),
 		...options,
 	} );
 
@@ -53,32 +42,28 @@ function ensureSite() {
 	const status = spawnSync(
 		nodeBin,
 		[ cliPath, 'site', 'status', '--path', sitePath, '--format', 'json' ],
-		{
-			encoding: 'utf8',
-			env: env(),
-		}
+		{ encoding: 'utf8' }
 	);
 
-	if ( status.status === 0 ) {
-		return;
+	if ( status.status !== 0 ) {
+		run( [
+			'site',
+			'create',
+			'--name',
+			'Static Site Importer Smoke',
+			'--path',
+			sitePath,
+			'--skip-browser',
+			'--skip-log-details',
+		] );
 	}
 
-	run( [
-		'site',
-		'create',
-		'--name',
-		'Static Site Importer Smoke',
-		'--path',
-		sitePath,
-		'--skip-browser',
-		'--skip-log-details',
-	] );
+	run( [ 'site', 'start', '--path', sitePath, '--skip-browser' ] );
 }
 
 function stopSite() {
 	spawnSync( nodeBin, [ cliPath, 'site', 'stop', '--path', sitePath ], {
 		encoding: 'utf8',
-		env: env(),
 	} );
 }
 
@@ -177,7 +162,6 @@ if ( $results['front_page_id'] !== $results['home_page_id'] ) {
 try {
 	ensureSite();
 	writeStaticFixture();
-	stopSite();
 	const result = run( [ 'wp', '--path', sitePath, '--php-version', '8.3', 'eval', php ] );
 	process.stdout.write( result.stdout );
 	if ( result.stderr ) {
@@ -187,4 +171,6 @@ try {
 } catch ( error ) {
 	console.error( error instanceof Error ? error.message : String( error ) );
 	process.exit( 1 );
+} finally {
+	stopSite();
 }
diff --git a/scripts/download-wp-server-files.ts b/scripts/download-wp-server-files.ts
index 093ff353bd..27f3ebc930 100644
--- a/scripts/download-wp-server-files.ts
+++ b/scripts/download-wp-server-files.ts
@@ -108,6 +108,27 @@ const FILES_TO_DOWNLOAD: FileToDownload[] = [
 		},
 		destinationPath: path.join( WP_SERVER_FILES_PATH, 'blueprints' ),
 	},
+	/**
+	 * Static Site Importer is an experimental upstream WordPress plugin that
+	 * converts static HTML into editable block themes. It's bundled into Studio
+	 * as a mu-plugin so generated local sites can run `wp static-site-importer
+	 * import-theme ...` without any per-machine setup.
+	 *
+	 * **Iteration mode:** while the SSI substrate is still rapidly evolving,
+	 * Studio pulls the latest `main` zipball at `npm install` time. Reviewers
+	 * automatically pick up fixes by re-running `npm install`. Before the
+	 * Studio PR un-drafts, swap the URL below for a pinned tag/sha — for
+	 * example `archive/refs/tags/v0.4.0.zip` — to lock the substrate.
+	 *
+	 * The SSI repo commits its `vendor/` directory, so no `composer install`
+	 * runs on the consumer side.
+	 */
+	{
+		name: 'static-site-importer',
+		description: 'Static Site Importer (chubes4/static-site-importer @ main)',
+		getUrl: () => 'https://github.com/chubes4/static-site-importer/archive/refs/heads/main.zip',
+		destinationPath: path.join( WP_SERVER_FILES_PATH, 'static-site-importer' ),
+	},
 ];
 
 async function downloadFile( file: FileToDownload ): Promise< void > {
@@ -152,6 +173,25 @@ async function downloadFile( file: FileToDownload ): Promise< void > {
 			fs.rmSync( targetPath, { recursive: true, force: true } );
 		}
 		fs.moveSync( sourcePath, targetPath );
+	} else if ( name === 'static-site-importer' ) {
+		/**
+		 * GitHub's `archive/refs/heads/main.zip` extracts into a folder named
+		 * `static-site-importer-main`. We extract to a temp dir, then move the
+		 * inner folder into `wp-files/static-site-importer/`.
+		 */
+		console.log( `[${ name }] Extracting files from zip ...` );
+		const tmpExtractPath = path.join( os.tmpdir(), 'static-site-importer-extract' );
+		if ( fs.existsSync( tmpExtractPath ) ) {
+			fs.rmSync( tmpExtractPath, { recursive: true, force: true } );
+		}
+		await extractZip( zipPath, tmpExtractPath );
+
+		const sourcePath = path.join( tmpExtractPath, 'static-site-importer-main' );
+		if ( fs.existsSync( extractedPath ) ) {
+			fs.rmSync( extractedPath, { recursive: true, force: true } );
+		}
+		fs.moveSync( sourcePath, extractedPath );
+		fs.rmSync( tmpExtractPath, { recursive: true, force: true } );
 	} else if ( name === 'phpmyadmin' ) {
 		/**
 		 * phpMyAdmin is extracted into a folder like phpMyAdmin-5.2.3-english.
diff --git a/tools/common/lib/mu-plugins.ts b/tools/common/lib/mu-plugins.ts
index 98980c0164..363ba52a10 100644
--- a/tools/common/lib/mu-plugins.ts
+++ b/tools/common/lib/mu-plugins.ts
@@ -19,10 +19,22 @@ export type MuPluginRuntime = 'playground' | 'native-php';
 export interface MuPluginOptions {
 	isWpAutoUpdating?: boolean;
 	runtime?: MuPluginRuntime;
+	/**
+	 * Absolute host path to the Static Site Importer plugin directory.
+	 *
+	 * Studio bundles the SSI plugin (sourced from
+	 * `chubes4/static-site-importer` `main` at `npm install` time, see
+	 * `scripts/download-wp-server-files.ts`) into `wp-files/static-site-importer/`.
+	 * Callers pass that path here; this module symlinks it into the per-site
+	 * mu-plugins temp directory and writes a small loader that requires
+	 * `static-site-importer/static-site-importer.php`.
+	 *
+	 * Optional only because not every caller has the bundled-files path
+	 * resolved (e.g. unit tests). When omitted, SSI is not loaded.
+	 */
+	staticSiteImporterPluginPath?: string;
 }
 
-const STATIC_SITE_IMPORTER_EXPERIMENT_PATH_ENV = 'STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH';
-
 /**
  * MU-plugin filenames that should not be written for native PHP sites.
  * These exist to work around behaviors specific to the Playground/PHP WASM
@@ -434,14 +446,17 @@ function getStandardMuPlugins( options: MuPluginOptions ): MuPlugin[] {
 		`,
 	} );
 
-	if ( process.env[ STATIC_SITE_IMPORTER_EXPERIMENT_PATH_ENV ] ) {
+	if ( options.staticSiteImporterPluginPath ) {
 		muPlugins.push( {
-			filename: '1-static-site-importer-experiment.php',
+			filename: '1-static-site-importer.php',
 			content: `<?php
 			/**
-			 * Static Site Importer experiment loader.
+			 * Static Site Importer loader.
 			 *
-			 * Enabled only when Studio is launched with ${ STATIC_SITE_IMPORTER_EXPERIMENT_PATH_ENV }.
+			 * Loads the bundled SSI plugin from the symlinked directory
+			 * created by createMuPluginsDirectory() and observes the
+			 * unsupported-HTML fallback signal so the smoke harness can
+			 * gate on a clean conversion.
 			 */
 			$static_site_importer_plugin = __DIR__ . '/static-site-importer/static-site-importer.php';
 			if ( file_exists( $static_site_importer_plugin ) ) {
@@ -628,11 +643,9 @@ async function createMuPluginsDirectory( options: MuPluginOptions ): Promise< st
 			await writeFile( pluginPath, plugin.content );
 		}
 
-		const staticSiteImporterExperimentPath =
-			process.env[ STATIC_SITE_IMPORTER_EXPERIMENT_PATH_ENV ];
-		if ( staticSiteImporterExperimentPath ) {
+		if ( options.staticSiteImporterPluginPath ) {
 			await symlink(
-				staticSiteImporterExperimentPath,
+				options.staticSiteImporterPluginPath,
 				path.join( tempDir, 'static-site-importer' ),
 				'dir'
 			);
@@ -666,7 +679,8 @@ export async function getMuPlugins( options: MuPluginOptions = {} ): Promise< [
 
 export async function writeStudioMuPluginsForNativePhpRuntime(
 	siteFolder: string,
-	isWpAutoUpdating: MuPluginOptions[ 'isWpAutoUpdating' ]
+	isWpAutoUpdating: MuPluginOptions[ 'isWpAutoUpdating' ],
+	staticSiteImporterPluginPath?: MuPluginOptions[ 'staticSiteImporterPluginPath' ]
 ): Promise< void > {
 	const muPluginsDir = path.join( siteFolder, 'wp-content', 'mu-plugins' );
 	await mkdir( muPluginsDir, { recursive: true } );
@@ -676,7 +690,11 @@ export async function writeStudioMuPluginsForNativePhpRuntime(
 	// copy the loader into wp-content/mu-plugins/ — WordPress auto-loads it
 	// at runtime and it pulls the rest in from the temp directory, keeping
 	// the user's mu-plugins/ nearly empty.
-	const [ , loaderHostPath ] = await getMuPlugins( { isWpAutoUpdating, runtime: 'native-php' } );
+	const [ , loaderHostPath ] = await getMuPlugins( {
+		isWpAutoUpdating,
+		runtime: 'native-php',
+		staticSiteImporterPluginPath,
+	} );
 	await copyFile( loaderHostPath, path.join( muPluginsDir, STUDIO_LOADER_MU_PLUGIN_FILENAME ) );
 }
 
@@ -716,11 +734,13 @@ export const LEGACY_MU_PLUGIN_FILENAMES = [
 	'0-tmp-fix-hide-plugins-spinner.php',
 	'0-tmp-fix-qm-plugin-sapi.php',
 	'0-wp-admin-trailing-slash.php',
+	'1-static-site-importer.php',
 	// Retired mu-plugins from older Studio versions
 	'0-32bit-integer-warnings.php',
 	'0-dns-functions.php',
 	'0-sqlite.php',
 	'0-wp-config-constants-polyfill.php',
+	'1-static-site-importer-experiment.php',
 ];
 
 /**
diff --git a/tools/common/lib/tests/mu-plugins.test.ts b/tools/common/lib/tests/mu-plugins.test.ts
index 39b203940c..f85d686e51 100644
--- a/tools/common/lib/tests/mu-plugins.test.ts
+++ b/tools/common/lib/tests/mu-plugins.test.ts
@@ -114,4 +114,52 @@ describe( 'writeStudioMuPluginsForNativePhpRuntime', () => {
 		expect( generatedPlugins ).toContain( '0-enable-auto-updates.php' );
 		expect( generatedPlugins ).not.toContain( '0-disable-auto-updates.php' );
 	} );
+
+	it( 'should write the Static Site Importer loader and symlink when a plugin path is provided', async () => {
+		const ssiPath = await mkdtemp( join( tmpdir(), 'studio-ssi-fixture-' ) );
+		writeFileSync( join( ssiPath, 'static-site-importer.php' ), '<?php // SSI plugin fixture' );
+
+		await writeStudioMuPluginsForNativePhpRuntime( sitePath, true, ssiPath );
+
+		const loaderPath = join(
+			sitePath,
+			'wp-content',
+			'mu-plugins',
+			STUDIO_LOADER_MU_PLUGIN_FILENAME
+		);
+		const loaderContent = await readFile( loaderPath, 'utf8' );
+		const muPluginsDir = loaderContent.match( /\$studio_mu_plugins_dir = '([^']+)';/ )?.[ 1 ];
+
+		expect( muPluginsDir ).toBeTruthy();
+
+		const generatedPlugins = await readdir( muPluginsDir as string );
+		// The SSI loader mu-plugin should be present.
+		expect( generatedPlugins ).toContain( '1-static-site-importer.php' );
+		// The symlinked SSI plugin directory should be present and resolve to a file.
+		expect( generatedPlugins ).toContain( 'static-site-importer' );
+		expect(
+			existsSync(
+				join( muPluginsDir as string, 'static-site-importer', 'static-site-importer.php' )
+			)
+		).toBe( true );
+	} );
+
+	it( 'should not write the SSI loader when no plugin path is provided', async () => {
+		await writeStudioMuPluginsForNativePhpRuntime( sitePath, true );
+
+		const loaderPath = join(
+			sitePath,
+			'wp-content',
+			'mu-plugins',
+			STUDIO_LOADER_MU_PLUGIN_FILENAME
+		);
+		const loaderContent = await readFile( loaderPath, 'utf8' );
+		const muPluginsDir = loaderContent.match( /\$studio_mu_plugins_dir = '([^']+)';/ )?.[ 1 ];
+
+		expect( muPluginsDir ).toBeTruthy();
+
+		const generatedPlugins = await readdir( muPluginsDir as string );
+		expect( generatedPlugins ).not.toContain( '1-static-site-importer.php' );
+		expect( generatedPlugins ).not.toContain( 'static-site-importer' );
+	} );
 } );

From fcb4ca6b174e7c589f6c2b11b1901266c14472c3 Mon Sep 17 00:00:00 2001
From: Chris Huber <chubes@chubes.net>
Date: Mon, 4 May 2026 07:14:30 -0400
Subject: [PATCH 4/7] Drop screenshot-loop negative framing from system prompt

The 'do not run visual screenshot loops unless the user explicitly asks'
guidance reads as anti-instruction for a behavior that is no longer part
of the workflow. Negative framing in prompts trains the model on the
behavior we're trying to avoid; it's better to omit the topic entirely.

Removes the trailing clause from the two 'Finish promptly' workflow
steps and the parenthetical from the take_screenshot tool description.
The neutral tool description (what it does) remains in both the
WordPress.com and local tool listings.

- **AI assistance:** Yes
- **Tool(s):** Claude Code (Sonnet 4.5)
- **Used for:** Mechanical removal under Chris's direction.
---
 apps/cli/ai/system-prompt.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index aadb3af925..eae2d2486b 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -98,7 +98,7 @@ Use \`per_page\` and \`page\` for pagination. Use \`status\` to filter by publis
 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. **Finish promptly**: Summarize what changed and let the user review the result. Do not run visual screenshot loops unless the user explicitly asks.
+4. **Finish promptly**: Summarize what changed and let the user review the result.
 
 ## General rules
 
@@ -148,7 +148,7 @@ Then continue with:
 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 the static site**: Use Write and Edit to create \`<site>/tmp/static-site/index.html\` as a full static HTML document with semantic body structure and CSS/assets.
 4. **Import into WordPress**: Use \`wp_cli\` to run \`static-site-importer import-theme /wordpress/tmp/static-site/index.html --slug=<theme-slug> --name="<Theme Name>" --activate --overwrite\`. The importer converts the static HTML into an editable block theme and front page. The \`wp_cli\` tool already runs WP-CLI, so do not prefix commands with \`wp\`. It takes one literal WP-CLI command per call, not shell commands: never combine commands with \`&&\`, \`;\`, pipes, redirection, shell substitution such as \`$(cat file)\`, backticks, environment variables, or host temp-file paths. Paths passed to WP-CLI must use WordPress's mounted filesystem (\`/wordpress/...\`), not host paths.
-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. **Width check**: any section that was meant to be full-width (heroes, banners, edge-to-edge galleries, full-bleed footers) must visibly span the entire viewport in the desktop screenshot.
+5. **Finish promptly**: Run any cheap static checks that are directly relevant, summarize what changed, and let the user review the result.
 
 ## Working cadence
 
@@ -169,7 +169,7 @@ One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp
 - 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
-- take_screenshot: Take a full-page screenshot of a URL (supports desktop and mobile viewports). Use only when the user explicitly asks for screenshot-based review.
+- take_screenshot: Take a full-page screenshot of a URL (supports desktop and mobile viewports).
 - 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.
 - site_connected_remote_sites: List the WordPress.com sites already attached to a local site. Call this before site_push to decide how to ask the user which remote site to target.

From 7d0eac96b04ee15839f6710261c3885340de5e86 Mon Sep 17 00:00:00 2001
From: Chris Huber <chubes@chubes.net>
Date: Mon, 4 May 2026 07:17:13 -0400
Subject: [PATCH 5/7] Drop homeboy reference from smoke script error message

Studio doesn't depend on homeboy, so the error path shouldn't either.
Replace the homeboy command suggestion with the Studio-native build
sequence (`npm install` at the root, `npm run build` in apps/cli)
so a reviewer running the smoke without a homeboy rig sees instructions
they can actually follow.

The script filename and the studio_bfb_unsupported_fallback_count option
key are unchanged \u2014 "BFB" there refers to Block Format Bridge (the
upstream conversion substrate), not the homeboy rig name.

## AI assistance
- **AI assistance:** Yes
- **Tool(s):** Claude Code (Sonnet 4.5)
- **Used for:** Mechanical message swap under Chris's direction.
---
 apps/cli/scripts/studio-bfb-smoke.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/cli/scripts/studio-bfb-smoke.mjs b/apps/cli/scripts/studio-bfb-smoke.mjs
index aa8b8d5bcc..003ef6b52f 100644
--- a/apps/cli/scripts/studio-bfb-smoke.mjs
+++ b/apps/cli/scripts/studio-bfb-smoke.mjs
@@ -14,7 +14,7 @@ const sitePath =
 
 if ( ! existsSync( cliPath ) ) {
 	console.error(
-		`Built Studio CLI not found at ${ cliPath }. Run homeboy rig up studio-bfb first.`
+		`Built Studio CLI not found at ${ cliPath }. Run \`npm install\` at the repo root and \`npm run build\` in apps/cli first.`
 	);
 	process.exit( 1 );
 }

From 0e70a387aa2319718ce48a6a3ea55937a72ae0b3 Mon Sep 17 00:00:00 2001
From: Chris Huber <chubes@chubes.net>
Date: Mon, 4 May 2026 07:19:57 -0400
Subject: [PATCH 6/7] Drop SSI legacy mu-plugin entries from cleanup list

Adding draft mu-plugin filenames to LEGACY_MU_PLUGIN_FILENAMES is
overengineering for a draft PR \u2014 there is no installed base of the
old experiment-suffixed filename to scrub, and adding the current
filename to the legacy list is conceptually wrong (it's not legacy,
it's the current shipping name).

The list is for cleaning up files older Studio versions wrote on disk;
the SSI mu-plugin has never shipped in a Studio release. If/when this
PR lands and a future rename is needed, that's the right time to add
the previous name to the legacy list.

## AI assistance
- **AI assistance:** Yes
- **Tool(s):** Claude Code (Sonnet 4.5)
- **Used for:** Mechanical removal under Chris's direction.
---
 tools/common/lib/mu-plugins.ts | 2 --
 1 file changed, 2 deletions(-)

diff --git a/tools/common/lib/mu-plugins.ts b/tools/common/lib/mu-plugins.ts
index 363ba52a10..2366fd544f 100644
--- a/tools/common/lib/mu-plugins.ts
+++ b/tools/common/lib/mu-plugins.ts
@@ -734,13 +734,11 @@ export const LEGACY_MU_PLUGIN_FILENAMES = [
 	'0-tmp-fix-hide-plugins-spinner.php',
 	'0-tmp-fix-qm-plugin-sapi.php',
 	'0-wp-admin-trailing-slash.php',
-	'1-static-site-importer.php',
 	// Retired mu-plugins from older Studio versions
 	'0-32bit-integer-warnings.php',
 	'0-dns-functions.php',
 	'0-sqlite.php',
 	'0-wp-config-constants-polyfill.php',
-	'1-static-site-importer-experiment.php',
 ];
 
 /**

From fe16ee96dc2adfae8592cb3e590a04d2eecf3cc3 Mon Sep 17 00:00:00 2001
From: Chris Huber <chubes@chubes.net>
Date: Tue, 5 May 2026 10:17:30 -0400
Subject: [PATCH 7/7] Use requested SSI plugin path in CLI

---
 apps/cli/lib/dependency-management/paths.ts   |  8 +++++--
 .../dependency-management/tests/paths.test.ts | 22 +++++++++++++++++++
 2 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 apps/cli/lib/dependency-management/tests/paths.test.ts

diff --git a/apps/cli/lib/dependency-management/paths.ts b/apps/cli/lib/dependency-management/paths.ts
index 5018440e89..75d547e522 100644
--- a/apps/cli/lib/dependency-management/paths.ts
+++ b/apps/cli/lib/dependency-management/paths.ts
@@ -58,8 +58,12 @@ export function getBlueprintsPharPath(): string {
 
 // Static Site Importer ships read-only with the CLI bundle (downloaded at npm
 // install time by `scripts/download-wp-server-files.ts`) and is symlinked into
-// each site's mu-plugins temp directory. No writable cache needed — the
-// bundled directory is treated as the source of truth.
+// each site's mu-plugins temp directory. Bench harnesses may override that
+// bundled copy to test an active SSI worktree.
 export function getStaticSiteImporterPluginPath(): string {
+	if ( process.env.STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH ) {
+		return process.env.STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH;
+	}
+
 	return path.join( getWpFilesPath(), 'static-site-importer' );
 }
diff --git a/apps/cli/lib/dependency-management/tests/paths.test.ts b/apps/cli/lib/dependency-management/tests/paths.test.ts
new file mode 100644
index 0000000000..7d5d577b59
--- /dev/null
+++ b/apps/cli/lib/dependency-management/tests/paths.test.ts
@@ -0,0 +1,22 @@
+import path from 'path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { getStaticSiteImporterPluginPath } from '../paths';
+
+describe( 'dependency path helpers', () => {
+	afterEach( () => {
+		delete process.env.STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH;
+	} );
+
+	it( 'uses the requested Static Site Importer plugin path when provided', () => {
+		process.env.STUDIO_STATIC_SITE_IMPORTER_PLUGIN_PATH =
+			'/tmp/static-site-importer-worktree';
+
+		expect( getStaticSiteImporterPluginPath() ).toBe( '/tmp/static-site-importer-worktree' );
+	} );
+
+	it( 'falls back to the bundled Static Site Importer plugin path', () => {
+		expect( getStaticSiteImporterPluginPath() ).toContain(
+			path.join( 'wp-files', 'static-site-importer' )
+		);
+	} );
+} );