Simplify scaffold theme defaults

Author: youknowriad

apps/cli/ai/system-prompt.ts

@@ -150,9 +150,10 @@ 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**: For a brand new theme, call \`scaffold_theme\` first — it drops a minimal block-theme baseline (style.css, theme.json with appearanceTools and a sane palette/spacing scale, functions.php with frontend + editor style enqueue, default templates and parts, empty assets/fonts and patterns dirs) and activates it by default. Then use Write and Edit to fill the scaffold (one part/template/file per turn). For the homepage, Edit \`templates/front-page.html\` directly — replace \`<!-- wp:post-content /-->\` with \`<!-- section:<concern> -->\` anchors (hero, features, cta, etc.) and fill one anchor per Edit using only core blocks. WP renders this template at \`/\` automatically, so no DB page and no \`show_on_front\`/\`page_on_front\` change is needed. Reserve \`templates/page.html\` for interior pages. For plugins or for editing an existing theme, use Write and Edit directly under the site's wp-content/themes/ or wp-content/plugins/ directory.
-4. **Configure WordPress**: Use wp_cli to 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 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 theme/plugin files**: For a brand new theme, call \`scaffold_theme\` first — it drops an unopinionated block-theme baseline (style.css with only the theme header, theme.json with appearanceTools only, functions.php with frontend + editor style enqueue, default templates and parts, empty assets/fonts and patterns dirs) and activates it by default. Then use Write and Edit to fill the scaffold (one part/template/file per turn). For plugins or for editing an existing theme, use Write and Edit directly 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. **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
 
@@ -162,8 +163,8 @@ One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp
 
 **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>\`. **When \`scaffold_theme\` was used, do NOT \`Write\` over the scaffolded \`style.css\`** — it already contains the theme header and UX-fix rules. Instead, \`Edit\` the file to append the \`:root { ... }\` block and anchor comments below the existing content, then fill anchors as above.
-- Interior page content (About, Contact, etc.): 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.
+- \`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>\`. **When \`scaffold_theme\` was used, do NOT \`Write\` over the scaffolded \`style.css\`** — it already contains the required theme header. Instead, \`Edit\` the file to append the \`:root { ... }\` block and anchor comments below the existing content, then fill anchors as above.
+- 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.
 
 ## Available Studio Tools (prefixed with mcp__studio__)
 

apps/cli/ai/tests/tools.test.ts

@@ -505,7 +505,6 @@ describe( 'Studio AI MCP tools', () => {
 				'theme.json',
 				'functions.php',
 				'templates/index.html',
-				'templates/front-page.html',
 				'templates/single.html',
 				'templates/page.html',
 				'templates/archive.html',
@@ -537,7 +536,7 @@ describe( 'Studio AI MCP tools', () => {
 			expect( functionsPhp ).toContain( "add_editor_style( 'style.css' )" );
 
 			expect( getTextContent( result ) ).toContain(
-				`Block theme 'Acme Studio' scaffolded at ${ path.join( tempSiteRoot, 'wp-content', 'themes', 'acme-studio' ) }/.`
+				"Block theme 'Acme Studio' scaffolded at wp-content/themes/acme-studio/."
 			);
 			expect( getTextContent( result ) ).toContain( 'wp theme activate acme-studio' );
 		} );

apps/cli/ai/tools/scaffold-theme.ts

@@ -70,28 +70,6 @@ License URI: http://www.gnu.org/licenses/gpl-2.0.html
 Text Domain: ${ slug }
 Tags: full-site-editing, block-patterns, block-styles, wide-blocks, accessibility-ready, style-variations
 */
-
-/* Link styles */
-a {
-	text-decoration-thickness: 1px !important;
-	text-underline-offset: .1em;
-}
-
-/* Focus styles */
-:where(.wp-site-blocks *:focus) {
-	outline-width: 2px;
-	outline-style: solid;
-}
-
-/* Reduce widows and orphans on prose */
-h1, h2, h3, h4, h5, h6, blockquote, caption, figcaption, p {
-	text-wrap: pretty;
-}
-
-/* Prevent unnecessary scrollbars on long preformatted text */
-:where(pre) {
-	overflow-x: auto;
-}
 `;
 }
 
@@ -101,79 +79,7 @@ function renderThemeJson(): string {
 		version: 3,
 		settings: {
 			appearanceTools: true,
-			useRootPaddingAwareAlignments: true,
-			layout: {
-				contentSize: '720px',
-				wideSize: '1200px',
-			},
-			color: {
-				palette: [
-					{ color: '#FFFFFF', name: 'Base', slug: 'base' },
-					{ color: '#111111', name: 'Contrast', slug: 'contrast' },
-					{ color: '#3858E9', name: 'Accent', slug: 'accent' },
-				],
-			},
-			spacing: {
-				spacingSizes: [
-					{ name: 'Tiny', size: '8px', slug: '20' },
-					{ name: 'X-Small', size: '16px', slug: '30' },
-					{ name: 'Small', size: '24px', slug: '40' },
-					{ name: 'Regular', size: 'clamp(32px, 5vw, 48px)', slug: '50' },
-					{ name: 'Large', size: 'clamp(48px, 8vw, 80px)', slug: '60' },
-					{ name: 'X-Large', size: 'clamp(80px, 12vw, 128px)', slug: '70' },
-					{ name: 'Huge', size: 'clamp(128px, 16vw, 192px)', slug: '80' },
-				],
-			},
-			typography: {
-				fluid: true,
-				fontFamilies: [
-					{
-						name: 'System Sans',
-						slug: 'system-sans',
-						fontFamily:
-							"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif",
-					},
-				],
-			},
-		},
-		styles: {
-			color: {
-				background: 'var(--wp--preset--color--base)',
-				text: 'var(--wp--preset--color--contrast)',
-			},
-			typography: {
-				fontFamily: 'var(--wp--preset--font-family--system-sans)',
-				lineHeight: '1.6',
-			},
-			elements: {
-				link: {
-					color: { text: 'var(--wp--preset--color--accent)' },
-				},
-				h1: {
-					typography: {
-						fontSize: 'clamp(2rem, 4vw, 3.5rem)',
-						lineHeight: '1.1',
-					},
-				},
-				h2: {
-					typography: {
-						fontSize: 'clamp(1.5rem, 3vw, 2.5rem)',
-						lineHeight: '1.2',
-					},
-				},
-				h3: {
-					typography: {
-						fontSize: 'clamp(1.25rem, 2vw, 1.75rem)',
-						lineHeight: '1.3',
-					},
-				},
-			},
 		},
-		templateParts: [
-			{ name: 'header', title: 'Header', area: 'header' },
-			{ name: 'footer', title: 'Footer', area: 'footer' },
-		],
-		customTemplates: [],
 	};
 	return JSON.stringify( data, null, '\t' ) + '\n';
 }
@@ -261,17 +167,6 @@ const TEMPLATE_SINGLE = `<!-- wp:template-part {"slug":"header"} /-->
 <!-- wp:template-part {"slug":"footer"} /-->
 `;
 
-const TEMPLATE_FRONT_PAGE = `<!-- wp:template-part {"slug":"header"} /-->
-
-<!-- wp:group {"tagName":"main"} -->
-<main class="wp-block-group">
-	<!-- wp:post-content /-->
-</main>
-<!-- /wp:group -->
-
-<!-- wp:template-part {"slug":"footer"} /-->
-`;
-
 const TEMPLATE_PAGE = `<!-- wp:template-part {"slug":"header"} /-->
 
 <!-- wp:group {"tagName":"main"} -->
@@ -373,8 +268,8 @@ const PART_FOOTER = `<!-- wp:group {"layout":{"type":"constrained"},"style":{"sp
 export const scaffoldThemeTool = defineTool(
 	'scaffold_theme',
 	'Scaffolds a minimal block theme into the given site at wp-content/themes/<slug>/ and activates it by default. ' +
-		'Drops in style.css, theme.json (with appearanceTools, semantic palette and a numeric spacing scale), ' +
-		'functions.php (frontend + editor style enqueue), default templates (index, front-page, single, page, archive, 404), ' +
+		'Drops in style.css (theme header only), theme.json (appearanceTools only), ' +
+		'functions.php (frontend + editor style enqueue), default templates (index, single, page, archive, 404), ' +
 		'header/footer parts, and empty assets/fonts and patterns directories. ' +
 		'Use when the user wants to start a new custom theme — the agent fills in design-specific content afterwards. ' +
 		'Block themes only; does not support classic (PHP template) themes. ' +
@@ -439,7 +334,6 @@ export const scaffoldThemeTool = defineTool(
 				[ 'theme.json', renderThemeJson() ],
 				[ 'functions.php', renderFunctionsPhp( trimmedName, slug ) ],
 				[ path.join( 'templates', 'index.html' ), TEMPLATE_INDEX ],
-				[ path.join( 'templates', 'front-page.html' ), TEMPLATE_FRONT_PAGE ],
 				[ path.join( 'templates', 'single.html' ), TEMPLATE_SINGLE ],
 				[ path.join( 'templates', 'page.html' ), TEMPLATE_PAGE ],
 				[ path.join( 'templates', 'archive.html' ), TEMPLATE_ARCHIVE ],
@@ -456,22 +350,14 @@ export const scaffoldThemeTool = defineTool(
 			const activation = shouldActivate ? await activateTheme( site.id, slug ) : null;
 
 			const summaryLines = [
-				`Block theme '${ trimmedName }' scaffolded at ${ themeDir }/.`,
+				`Block theme '${ trimmedName }' scaffolded at wp-content/themes/${ slug }/.`,
 				'',
-				'Files (paths relative to the theme directory above):',
-				'  style.css                 — WP header + UX-fix CSS. Append :root tokens and section anchors below the existing rules.',
-				'  theme.json                — appearanceTools, useRootPaddingAwareAlignments, palette (base/contrast/accent), spacing scale 20–80, content/wide 720/1200, system-sans default.',
-				'  functions.php             — versioned style.css frontend enqueue + add_editor_style.',
-				'  templates/front-page.html — Plain <main> + <wp:post-content/>. Replace post-content with section anchors for the homepage layout.',
-				'  templates/page.html       — Constrained title group + constrained post-content. Interior pages.',
-				'  templates/single.html     — Constrained title/date/featured-image + constrained post-content + constrained comments form.',
-				'  templates/index.html      — Constrained query loop (blog index fallback).',
-				'  templates/archive.html    — Constrained archive title + term description + query loop.',
-				'  templates/404.html        — Constrained heading + message + search.',
-				'  parts/header.html         — Constrained group: site-title + empty wp:navigation. Add menu items here.',
-				'  parts/footer.html         — Constrained group: centered © + site-title.',
+				'Created files:',
+				...files.map( ( [ relPath ] ) => `  ${ relPath }` ),
 				'',
-				'Empty: assets/fonts/, patterns/',
+				'Empty directories:',
+				'  assets/fonts/',
+				'  patterns/',
 				'',
 			];