diff --git a/apps/cli/ai/generation/generators.ts b/apps/cli/ai/generation/generators.ts
new file mode 100644
index 0000000000..0d97b5b146
--- /dev/null
+++ b/apps/cli/ai/generation/generators.ts
@@ -0,0 +1,120 @@
+import fs from 'fs';
+import path from 'path';
+import { getSkillsRoot } from 'cli/ai/skills';
+import { completeText, extractJson, stripCodeFences } from './llm';
+import { parseManifest, type SiteManifest } from './manifest';
+
+/**
+ * Loads and runs the generator prompt fragments bundled under
+ * `skills/site-generator/generators/`. Each fragment is a system-prompt body
+ * adapted from a Telex generator; the tool appends the site spec + chosen
+ * design + a per-call task. `_shared` is prepended to every call.
+ */
+
+function generatorsDir(): string {
+	return path.join( getSkillsRoot(), 'site-generator', 'generators' );
+}
+
+const fragmentCache = new Map< string, string >();
+
+function loadFragment( name: string ): string {
+	const cached = fragmentCache.get( name );
+	if ( cached !== undefined ) {
+		return cached;
+	}
+	const file = path.join( generatorsDir(), `${ name }.md` );
+	if ( ! fs.existsSync( file ) ) {
+		throw new Error(
+			`Generator prompt fragment not found: ${ name } (${ file }). Is the wordpress-site-generator bundle installed?`
+		);
+	}
+	const content = fs.readFileSync( file, 'utf8' );
+	fragmentCache.set( name, content );
+	return content;
+}
+
+export interface RunGeneratorInput {
+	name: string;
+	specJson: string;
+	design?: string;
+	task?: string;
+	maxTokens?: number;
+	temperature?: number;
+}
+
+export async function runGenerator( input: RunGeneratorInput ): Promise< string > {
+	const shared = loadFragment( '_shared' );
+	const fragment = loadFragment( input.name );
+	const system = `${ shared }\n\n----------\n\n${ fragment }`;
+
+	let user = `SITE SPEC (JSON):\n${ input.specJson }`;
+	if ( input.design ) {
+		user += `\n\nCHOSEN DESIGN DIRECTION:\n${ input.design }`;
+	}
+	if ( input.task ) {
+		user += `\n\nTASK:\n${ input.task }`;
+	}
+
+	return stripCodeFences(
+		await completeText( {
+			system,
+			user,
+			maxTokens: input.maxTokens,
+			temperature: input.temperature,
+		} )
+	);
+}
+
+export async function runManifest( specJson: string ): Promise< SiteManifest > {
+	// Generous budget: the manifest carries a cinematic composition brief per
+	// page, so a small cap truncates the JSON mid-stream (no closing fence/brace)
+	// and the parse fails.
+	const raw = await runGenerator( {
+		name: 'manifest',
+		specJson,
+		maxTokens: 16_000,
+		temperature: 0.2,
+	} );
+	return parseManifest( raw );
+}
+
+export interface GeneratedBlockFiles {
+	files: Record< string, string >;
+}
+
+export async function runBlockGenerator(
+	specJson: string,
+	blockTask: string
+): Promise< GeneratedBlockFiles > {
+	const raw = await runGenerator( {
+		name: 'block',
+		specJson,
+		task: blockTask,
+		maxTokens: 16_000,
+		temperature: 0.3,
+	} );
+	let data: unknown;
+	try {
+		data = JSON.parse( extractJson( raw ) );
+	} catch ( error ) {
+		throw new Error(
+			`Block generator did not return valid JSON: ${
+				error instanceof Error ? error.message : String( error )
+			}`
+		);
+	}
+	const filesValue = ( data as { files?: unknown } )?.files;
+	if ( ! filesValue || typeof filesValue !== 'object' ) {
+		throw new Error( 'Block generator JSON is missing a "files" object.' );
+	}
+	const files: Record< string, string > = {};
+	for ( const [ key, value ] of Object.entries( filesValue as Record< string, unknown > ) ) {
+		if ( typeof value === 'string' ) {
+			files[ key ] = value;
+		}
+	}
+	if ( ! Object.keys( files ).length ) {
+		throw new Error( 'Block generator produced no files.' );
+	}
+	return { files };
+}
diff --git a/apps/cli/ai/generation/images.ts b/apps/cli/ai/generation/images.ts
new file mode 100644
index 0000000000..11fbea4915
--- /dev/null
+++ b/apps/cli/ai/generation/images.ts
@@ -0,0 +1,131 @@
+import { aspectFromHint, generateImageBytes, type ImageAspectRatio } from './wpcom-image';
+
+/**
+ * Resolves the `AI_IMAGE:` placeholder convention. Generated markup uses
+ *   <img src="..." alt="AI_IMAGE: <description> | <style> | <aspect>">
+ * so imagery can be filled in after structure is generated. These helpers find
+ * those placeholders, generate the image, hand the bytes to a caller-supplied
+ * persistence strategy (theme assets dir, or the media uploads dir), and
+ * rewrite the tag's `src`/`alt` in place.
+ */
+
+export interface AiImageMatch {
+	tag: string;
+	description: string;
+	style?: string;
+	aspect?: string;
+}
+
+const IMG_TAG_RE = /<img\b[^>]*>/gi;
+
+export function getAttr( tag: string, name: string ): string | undefined {
+	const match =
+		tag.match( new RegExp( `\\b${ name }\\s*=\\s*"([^"]*)"`, 'i' ) ) ??
+		tag.match( new RegExp( `\\b${ name }\\s*=\\s*'([^']*)'`, 'i' ) );
+	return match ? match[ 1 ] : undefined;
+}
+
+function setAttr( tag: string, name: string, value: string ): string {
+	const escaped = value.replace( /&/g, '&amp;' ).replace( /"/g, '&quot;' );
+	const re = new RegExp( `\\s${ name }\\s*=\\s*("[^"]*"|'[^']*')`, 'i' );
+	if ( re.test( tag ) ) {
+		return tag.replace( re, ` ${ name }="${ escaped }"` );
+	}
+	return tag.replace( /(\s*\/?>)\s*$/, ` ${ name }="${ escaped }"$1` );
+}
+
+export function parseAiImageAlt(
+	alt: string
+): { description: string; style?: string; aspect?: string } | null {
+	const match = alt.match( /^\s*AI_IMAGE:\s*(.+)$/i );
+	if ( ! match ) {
+		return null;
+	}
+	const parts = match[ 1 ].split( '|' ).map( ( s ) => s.trim() );
+	return {
+		description: parts[ 0 ] || 'abstract textured background',
+		style: parts[ 1 ],
+		aspect: parts[ 2 ],
+	};
+}
+
+export function findAiImages( html: string ): AiImageMatch[] {
+	const out: AiImageMatch[] = [];
+	for ( const tag of html.match( IMG_TAG_RE ) ?? [] ) {
+		const alt = getAttr( tag, 'alt' );
+		if ( ! alt ) {
+			continue;
+		}
+		const parsed = parseAiImageAlt( alt );
+		if ( parsed ) {
+			out.push( { tag, ...parsed } );
+		}
+	}
+	return out;
+}
+
+// Removes AI_IMAGE placeholder <img> tags (used when imagery can't be
+// generated) while leaving real <img> tags intact, so a page renders as
+// intentional sections rather than broken images.
+export function stripAiImagePlaceholders( html: string ): string {
+	return html.replace( /<img\b[^>]*\bAI_IMAGE:[^>]*>/gi, '' );
+}
+
+export function buildImagePrompt( description: string, style?: string ): string {
+	const styleClause = style ? ` Style: ${ style }.` : '';
+	return `${ description }.${ styleClause } High quality, professional, clean composition. No text, no lettering, no watermark, no logo.`;
+}
+
+export interface PersistImageContext {
+	description: string;
+	aspect: ImageAspectRatio;
+	index: number;
+}
+
+export type PersistImage = ( bytes: Buffer, ctx: PersistImageContext ) => Promise< string | null >;
+
+export interface ImageResolution {
+	html: string;
+	generated: number;
+	failed: number;
+	total: number;
+}
+
+/**
+ * Best-effort: any image that fails to generate or persist is left as-is (the
+ * placeholder stays) so a single failure never aborts the whole build.
+ */
+export async function resolveAiImagesInHtml(
+	html: string,
+	persist: PersistImage
+): Promise< ImageResolution > {
+	const matches = findAiImages( html );
+	let out = html;
+	let generated = 0;
+	let failed = 0;
+	let index = 0;
+
+	for ( const match of matches ) {
+		index++;
+		try {
+			const aspect = aspectFromHint( match.aspect );
+			const bytes = await generateImageBytes(
+				buildImagePrompt( match.description, match.style ),
+				aspect
+			);
+			const url = await persist( bytes, { description: match.description, aspect, index } );
+			if ( ! url ) {
+				failed++;
+				continue;
+			}
+			let newTag = setAttr( match.tag, 'src', url );
+			newTag = setAttr( newTag, 'alt', match.description );
+			out = out.replace( match.tag, newTag );
+			generated++;
+		} catch {
+			failed++;
+		}
+	}
+
+	return { html: out, generated, failed, total: matches.length };
+}
diff --git a/apps/cli/ai/generation/llm.ts b/apps/cli/ai/generation/llm.ts
new file mode 100644
index 0000000000..b73cc06b86
--- /dev/null
+++ b/apps/cli/ai/generation/llm.ts
@@ -0,0 +1,230 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { AI_MODELS, DEFAULT_MODEL, type AiModelId } from '@studio/common/ai/models';
+import { resolveAiEnvironment, resolveInitialAiProvider } from 'cli/ai/auth';
+
+/**
+ * Generation LLM client used by the wordpress-site-generator tools.
+ *
+ * The agent runtime (runtimes/pi) builds its own streaming model from a
+ * resolved provider environment. The generation tools run their own
+ * (non-streaming, parallel) model calls inside tool handlers, so they resolve
+ * the same provider environment independently and construct a plain
+ * `@anthropic-ai/sdk` client from it — mirroring `createWpcomAnthropicProviderConfig`
+ * in runtimes/pi. This works for both the wpcom proxy (bearer auth +
+ * X-WPCOM-AI-Feature header) and a direct Anthropic API key.
+ */
+
+const GENERATION_MAX_TOKENS = 16_000;
+
+// ANTHROPIC_CUSTOM_HEADERS is a newline-delimited `Name: value` string (see
+// providers.ts / runtimes/pi parseAnthropicHeaderEnv). Reproduced here so the
+// generation client sends the same X-WPCOM-AI-Feature header as the agent.
+function parseAnthropicHeaderEnv(
+	value: string | undefined
+): Record< string, string > | undefined {
+	if ( ! value ) {
+		return undefined;
+	}
+	const out: Record< string, string > = {};
+	for ( const line of value.split( '\n' ) ) {
+		const idx = line.indexOf( ':' );
+		if ( idx <= 0 ) {
+			continue;
+		}
+		const name = line.slice( 0, idx ).trim();
+		const v = line.slice( idx + 1 ).trim();
+		if ( name && v ) {
+			out[ name ] = v;
+		}
+	}
+	return Object.keys( out ).length ? out : undefined;
+}
+
+interface GenerationClient {
+	client: Anthropic;
+	model: AiModelId;
+}
+
+let cached: GenerationClient | null = null;
+
+function resolveGenerationModel(): AiModelId {
+	const override = process.env.STUDIO_WSG_MODEL?.trim();
+	if ( override && AI_MODELS.some( ( m ) => m.id === override && m.family === 'anthropic' ) ) {
+		return override as AiModelId;
+	}
+	return DEFAULT_MODEL;
+}
+
+async function getClient(): Promise< GenerationClient > {
+	if ( cached ) {
+		return cached;
+	}
+
+	const provider = await resolveInitialAiProvider();
+	const env = await resolveAiEnvironment( provider );
+
+	const authToken = env.ANTHROPIC_AUTH_TOKEN?.trim();
+	const apiKey = env.ANTHROPIC_API_KEY?.trim();
+	if ( ! authToken && ! apiKey ) {
+		throw new Error(
+			'WordPress.com login required for site generation. Run /login to authenticate, or switch to the Anthropic API key provider with /provider.'
+		);
+	}
+
+	const baseURL = env.ANTHROPIC_BASE_URL?.trim() || 'https://api.anthropic.com';
+	const defaultHeaders = parseAnthropicHeaderEnv( env.ANTHROPIC_CUSTOM_HEADERS );
+
+	const client = new Anthropic( {
+		apiKey: authToken ? null : apiKey ?? null,
+		authToken: authToken ?? undefined,
+		baseURL,
+		defaultHeaders,
+		dangerouslyAllowBrowser: true,
+	} );
+
+	// Only cache on success so a pre-login failure doesn't pin a broken client.
+	cached = { client, model: resolveGenerationModel() };
+	return cached;
+}
+
+export interface CompleteTextOptions {
+	system: string;
+	user: string;
+	maxTokens?: number;
+	temperature?: number;
+}
+
+// Statuses worth retrying: rate limits, gateway/proxy hiccups, and Anthropic's
+// 529 "overloaded". The WordPress.com AI proxy occasionally returns a 503 HTML
+// page on transient load; without a retry that aborts a whole long-running
+// generation (e.g. seeding many pages).
+const TRANSIENT_STATUSES = new Set( [ 408, 409, 425, 429, 500, 502, 503, 504, 529 ] );
+const TRANSIENT_MESSAGE_RE =
+	/\b(429|500|502|503|504|529)\b|overloaded|rate.?limit|temporarily unavailable|service unavailable|gateway|timeout|ETIMEDOUT|ECONNRESET|ECONNREFUSED|EAI_AGAIN/i;
+
+export function isTransientError( error: unknown ): boolean {
+	const status = ( error as { status?: number } )?.status;
+	if ( typeof status === 'number' && TRANSIENT_STATUSES.has( status ) ) {
+		return true;
+	}
+	const message = error instanceof Error ? error.message : String( error );
+	return TRANSIENT_MESSAGE_RE.test( message );
+}
+
+function sleep( ms: number ): Promise< void > {
+	return new Promise( ( resolve ) => setTimeout( resolve, ms ) );
+}
+
+export async function withTransientRetry< T >( fn: () => Promise< T > ): Promise< T > {
+	const maxAttempts = 5;
+	let lastError: unknown;
+	for ( let attempt = 1; attempt <= maxAttempts; attempt++ ) {
+		try {
+			return await fn();
+		} catch ( error ) {
+			lastError = error;
+			if ( attempt === maxAttempts || ! isTransientError( error ) ) {
+				throw error;
+			}
+			// Exponential backoff with jitter (1.5s, 3s, 6s, 12s, capped at 20s)
+			// to ride out a transient proxy outage without a thundering herd.
+			const backoff = Math.min( 1500 * 2 ** ( attempt - 1 ), 20_000 );
+			await sleep( backoff + Math.floor( Math.random() * 500 ) );
+		}
+	}
+	throw lastError;
+}
+
+export async function completeText( opts: CompleteTextOptions ): Promise< string > {
+	const { client, model } = await getClient();
+	const response = await withTransientRetry( () =>
+		client.messages.create( {
+			model,
+			max_tokens: opts.maxTokens ?? GENERATION_MAX_TOKENS,
+			temperature: opts.temperature ?? 0.7,
+			system: opts.system,
+			messages: [ { role: 'user', content: opts.user } ],
+		} )
+	);
+
+	return response.content
+		.map( ( block ) => ( block.type === 'text' ? block.text : '' ) )
+		.join( '' )
+		.trim();
+}
+
+/**
+ * Run async tasks with a bounded concurrency. The site-generator fans out one
+ * model call per theme file; a small pool keeps us well under provider rate
+ * limits while still parallelising the bulk of the work.
+ */
+export async function runPooled< T >(
+	tasks: Array< () => Promise< T > >,
+	concurrency = 4
+): Promise< T[] > {
+	const results: T[] = new Array( tasks.length );
+	let next = 0;
+
+	async function worker(): Promise< void > {
+		for (;;) {
+			const index = next++;
+			if ( index >= tasks.length ) {
+				return;
+			}
+			results[ index ] = await tasks[ index ]();
+		}
+	}
+
+	const workerCount = Math.max( 1, Math.min( concurrency, tasks.length ) );
+	await Promise.all( Array.from( { length: workerCount }, () => worker() ) );
+	return results;
+}
+
+/**
+ * Models occasionally wrap output in a Markdown code fence despite being told
+ * not to. Strip a single outer fence so the raw file content is written as-is.
+ */
+export function stripCodeFences( text: string ): string {
+	let trimmed = text.trim();
+	// Tolerate a closing fence with no preceding newline (e.g. "```json\n{...}```")
+	// and trailing whitespace, which models emit on the JSON paths.
+	const full = trimmed.match( /^```[a-zA-Z0-9_-]*\n([\s\S]*?)\n?```$/ );
+	if ( full ) {
+		return full[ 1 ].trim();
+	}
+	// Opening fence with no (or a truncated) closing fence: drop the leading
+	// ```lang line and any dangling closing fence so the inner content survives.
+	trimmed = trimmed.replace( /^```[a-zA-Z0-9_-]*\n/, '' ).replace( /\n?```$/, '' );
+	return trimmed.trim();
+}
+
+/**
+ * Extracts a JSON value (object or array) from model output that may be wrapped
+ * in a code fence and/or surrounded by stray prose. Slices from the first
+ * opening bracket to the last matching closing bracket — robust to fences the
+ * model added or a leading sentence like "Here is the manifest:".
+ */
+export function extractJson( text: string ): string {
+	const unfenced = stripCodeFences( text );
+	const firstObj = unfenced.indexOf( '{' );
+	const firstArr = unfenced.indexOf( '[' );
+	if ( firstObj === -1 && firstArr === -1 ) {
+		return unfenced;
+	}
+	let start: number;
+	let close: string;
+	if ( firstArr === -1 || ( firstObj !== -1 && firstObj < firstArr ) ) {
+		start = firstObj;
+		close = '}';
+	} else {
+		start = firstArr;
+		close = ']';
+	}
+	const end = unfenced.lastIndexOf( close );
+	return end > start ? unfenced.slice( start, end + 1 ) : unfenced;
+}
+
+// Test seam: lets unit tests reset the memoised client between cases.
+export function __resetGenerationClientForTests(): void {
+	cached = null;
+}
diff --git a/apps/cli/ai/generation/manifest.ts b/apps/cli/ai/generation/manifest.ts
new file mode 100644
index 0000000000..d1b6239193
--- /dev/null
+++ b/apps/cli/ai/generation/manifest.ts
@@ -0,0 +1,239 @@
+import { extractJson } from './llm';
+import { deriveSlug, isValidSlug } from './paths';
+
+/**
+ * The file manifest the `manifest` generator produces from a site spec. It
+ * drives the whole pipeline: which theme files to generate, whether a
+ * companion plugin is needed, and what content to seed.
+ */
+
+export type LayoutMode =
+	| 'vertical-stack'
+	| 'sidebar-left'
+	| 'sidebar-right'
+	| 'dual-sidebar'
+	| 'landing-page'
+	| 'magazine-grid'
+	| 'canvas-floating-chrome';
+
+export type ContentMode = 'homepage-and-pages' | 'blog-first' | 'index-only';
+
+export interface PagePlan {
+	slug: string;
+	title: string;
+	brief: string;
+}
+
+export interface PostTypeField {
+	key: string;
+	type: 'string' | 'number' | 'boolean';
+}
+
+export interface PostTypePlan {
+	slug: string;
+	name: string;
+	fields: PostTypeField[];
+}
+
+export interface RestRoutePlan {
+	path: string;
+	purpose: string;
+}
+
+export interface BlockPlan {
+	slug: string;
+	title: string;
+	purpose: string;
+}
+
+export interface CompanionPluginPlan {
+	needed: boolean;
+	slug: string;
+	name: string;
+	postTypes: PostTypePlan[];
+	restRoutes: RestRoutePlan[];
+	blocks: BlockPlan[];
+}
+
+export interface SeedItem {
+	type: string;
+	slug: string;
+	title: string;
+}
+
+export interface SiteManifest {
+	themeSlug: string;
+	themeName: string;
+	layoutMode: LayoutMode;
+	contentMode: ContentMode;
+	parts: string[];
+	templates: string[];
+	pages: PagePlan[];
+	patterns: string[];
+	companionPlugin: CompanionPluginPlan;
+	seed: SeedItem[];
+}
+
+const LAYOUT_MODES: LayoutMode[] = [
+	'vertical-stack',
+	'sidebar-left',
+	'sidebar-right',
+	'dual-sidebar',
+	'landing-page',
+	'magazine-grid',
+	'canvas-floating-chrome',
+];
+
+const CONTENT_MODES: ContentMode[] = [ 'homepage-and-pages', 'blog-first', 'index-only' ];
+
+function asString( value: unknown, fallback = '' ): string {
+	return typeof value === 'string' && value.trim() ? value.trim() : fallback;
+}
+
+function asStringArray( value: unknown ): string[] {
+	if ( ! Array.isArray( value ) ) {
+		return [];
+	}
+	return value
+		.filter( ( v ): v is string => typeof v === 'string' && v.trim().length > 0 )
+		.map( ( v ) => v.trim() );
+}
+
+function normalizeSlug( value: unknown, fallback: string ): string {
+	const candidate = deriveSlug( asString( value, fallback ) );
+	return candidate && isValidSlug( candidate ) ? candidate : fallback;
+}
+
+function normalizePages( value: unknown ): PagePlan[] {
+	if ( ! Array.isArray( value ) ) {
+		return [];
+	}
+	const pages: PagePlan[] = [];
+	for ( const raw of value ) {
+		if ( ! raw || typeof raw !== 'object' ) {
+			continue;
+		}
+		const obj = raw as Record< string, unknown >;
+		const title = asString( obj.title );
+		const slug = normalizeSlug( obj.slug ?? title, deriveSlug( title || 'page' ) || 'page' );
+		if ( ! title ) {
+			continue;
+		}
+		pages.push( { slug, title, brief: asString( obj.brief ) } );
+	}
+	return pages;
+}
+
+function normalizeCompanionPlugin( value: unknown, themeSlug: string ): CompanionPluginPlan {
+	const obj = ( value && typeof value === 'object' ? value : {} ) as Record< string, unknown >;
+	const needed = obj.needed === true;
+	const slug = normalizeSlug(
+		obj.slug ?? `${ themeSlug }-functionality`,
+		`${ themeSlug }-functionality`
+	);
+
+	const postTypes: PostTypePlan[] = Array.isArray( obj.postTypes )
+		? ( obj.postTypes as unknown[] )
+				.filter( ( p ): p is Record< string, unknown > => !! p && typeof p === 'object' )
+				.map( ( p ) => ( {
+					slug: normalizeSlug( p.slug, deriveSlug( asString( p.name, 'item' ) ) || 'item' ),
+					name: asString( p.name, 'Item' ),
+					fields: Array.isArray( p.fields )
+						? ( p.fields as unknown[] )
+								.filter( ( f ): f is Record< string, unknown > => !! f && typeof f === 'object' )
+								.map( ( f ) => ( {
+									key: asString( f.key, 'field' ),
+									type: ( [ 'string', 'number', 'boolean' ].includes( asString( f.type ) )
+										? asString( f.type )
+										: 'string' ) as PostTypeField[ 'type' ],
+								} ) )
+						: [],
+				} ) )
+		: [];
+
+	const restRoutes: RestRoutePlan[] = Array.isArray( obj.restRoutes )
+		? ( obj.restRoutes as unknown[] )
+				.filter( ( r ): r is Record< string, unknown > => !! r && typeof r === 'object' )
+				.map( ( r ) => ( { path: asString( r.path ), purpose: asString( r.purpose ) } ) )
+				.filter( ( r ) => r.path )
+		: [];
+
+	const blocks: BlockPlan[] = Array.isArray( obj.blocks )
+		? ( obj.blocks as unknown[] )
+				.filter( ( b ): b is Record< string, unknown > => !! b && typeof b === 'object' )
+				.map( ( b ) => ( {
+					slug: normalizeSlug( b.slug, deriveSlug( asString( b.title, 'block' ) ) || 'block' ),
+					title: asString( b.title, 'Block' ),
+					purpose: asString( b.purpose ),
+				} ) )
+		: [];
+
+	return {
+		needed,
+		slug,
+		name: asString( obj.name, 'Site Functionality' ),
+		postTypes,
+		restRoutes,
+		blocks,
+	};
+}
+
+function normalizeSeed( value: unknown ): SeedItem[] {
+	if ( ! Array.isArray( value ) ) {
+		return [];
+	}
+	return ( value as unknown[] )
+		.filter( ( s ): s is Record< string, unknown > => !! s && typeof s === 'object' )
+		.map( ( s ) => ( {
+			type: asString( s.type, 'page' ),
+			slug: normalizeSlug( s.slug ?? s.title, deriveSlug( asString( s.title, 'item' ) ) || 'item' ),
+			title: asString( s.title ),
+		} ) )
+		.filter( ( s ) => s.title );
+}
+
+export function parseManifest( raw: string ): SiteManifest {
+	let data: Record< string, unknown >;
+	try {
+		data = JSON.parse( extractJson( raw ) ) as Record< string, unknown >;
+	} catch ( error ) {
+		throw new Error(
+			`The manifest generator did not return valid JSON: ${
+				error instanceof Error ? error.message : String( error )
+			}`
+		);
+	}
+
+	const themeName = asString( data.themeName, 'Generated Site' );
+	const themeSlug = normalizeSlug(
+		data.themeSlug ?? themeName,
+		deriveSlug( themeName ) || 'generated-site'
+	);
+
+	const layoutMode = (
+		LAYOUT_MODES.includes( asString( data.layoutMode ) as LayoutMode )
+			? asString( data.layoutMode )
+			: 'vertical-stack'
+	) as LayoutMode;
+	const contentMode = (
+		CONTENT_MODES.includes( asString( data.contentMode ) as ContentMode )
+			? asString( data.contentMode )
+			: 'homepage-and-pages'
+	) as ContentMode;
+
+	const parts = asStringArray( data.parts );
+	const templates = asStringArray( data.templates );
+
+	return {
+		themeSlug,
+		themeName,
+		layoutMode,
+		contentMode,
+		parts: parts.length ? parts : [ 'header', 'footer' ],
+		templates: templates.length ? templates : [ 'index', 'page' ],
+		pages: normalizePages( data.pages ),
+		patterns: asStringArray( data.patterns ),
+		companionPlugin: normalizeCompanionPlugin( data.companionPlugin, themeSlug ),
+		seed: normalizeSeed( data.seed ),
+	};
+}
diff --git a/apps/cli/ai/generation/paths.ts b/apps/cli/ai/generation/paths.ts
new file mode 100644
index 0000000000..f3c9c66f69
--- /dev/null
+++ b/apps/cli/ai/generation/paths.ts
@@ -0,0 +1,50 @@
+import { mkdir, writeFile } from 'fs/promises';
+import path from 'path';
+
+export function deriveSlug( input: string ): string {
+	return input
+		.toLowerCase()
+		.replace( /[^a-z0-9]+/g, '-' )
+		.replace( /^-+|-+$/g, '' );
+}
+
+export function isValidSlug( slug: string ): boolean {
+	return /^[a-z0-9][a-z0-9-]*$/.test( slug );
+}
+
+export function themeDir( sitePath: string, slug: string ): string {
+	return path.join( sitePath, 'wp-content', 'themes', slug );
+}
+
+export function pluginDir( sitePath: string, slug: string ): string {
+	return path.join( sitePath, 'wp-content', 'plugins', slug );
+}
+
+export function uploadsDir( sitePath: string, subdir = 'wsg' ): string {
+	return path.join( sitePath, 'wp-content', 'uploads', subdir );
+}
+
+/**
+ * Guards every generated write so a model-supplied relative path can never
+ * escape the package directory (theme/plugin). Returns the resolved absolute
+ * path on success; throws otherwise.
+ */
+export function assertInside( baseDir: string, relPath: string ): string {
+	const base = path.resolve( baseDir );
+	const resolved = path.resolve( base, relPath );
+	if ( resolved !== base && ! resolved.startsWith( base + path.sep ) ) {
+		throw new Error( `Refusing to write outside the package directory: ${ relPath }` );
+	}
+	return resolved;
+}
+
+export async function writePackageFile(
+	baseDir: string,
+	relPath: string,
+	content: string
+): Promise< string > {
+	const full = assertInside( baseDir, relPath );
+	await mkdir( path.dirname( full ), { recursive: true } );
+	await writeFile( full, content, 'utf8' );
+	return full;
+}
diff --git a/apps/cli/ai/generation/site-wp.ts b/apps/cli/ai/generation/site-wp.ts
new file mode 100644
index 0000000000..685cbf49e0
--- /dev/null
+++ b/apps/cli/ai/generation/site-wp.ts
@@ -0,0 +1,37 @@
+import { connectToDaemon, disconnectFromDaemon } from 'cli/lib/daemon-client';
+import { isServerRunning, sendWpCliCommand } from 'cli/lib/wordpress-server-manager';
+
+/**
+ * Thin WP-CLI helpers for the generation tools. Unlike the `wp_cli` agent tool
+ * (which parses a shell-ish string and connects per call), the generation
+ * pipeline issues many commands with already-split argv, so it connects to the
+ * daemon once via `withDaemon` and reuses the connection.
+ */
+
+export interface WpCliResult {
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+}
+
+export async function withDaemon< T >( fn: () => Promise< T > ): Promise< T > {
+	await connectToDaemon();
+	try {
+		return await fn();
+	} finally {
+		await disconnectFromDaemon();
+	}
+}
+
+export async function isSiteRunning( siteId: string ): Promise< boolean > {
+	return Boolean( await isServerRunning( siteId ) );
+}
+
+export async function wpCli( siteId: string, args: string[] ): Promise< WpCliResult > {
+	const result = await sendWpCliCommand( siteId, args );
+	return {
+		exitCode: result.exitCode,
+		stdout: result.stdout ?? '',
+		stderr: result.stderr ?? '',
+	};
+}
diff --git a/apps/cli/ai/generation/wpcom-image.ts b/apps/cli/ai/generation/wpcom-image.ts
new file mode 100644
index 0000000000..a1e59169a0
--- /dev/null
+++ b/apps/cli/ai/generation/wpcom-image.ts
@@ -0,0 +1,149 @@
+import { readAuthToken } from '@studio/common/lib/shared-config';
+import { withTransientRetry } from './llm';
+
+/**
+ * AI image generation through the WordPress.com AI API proxy.
+ *
+ * Uses the OpenAI images endpoint (`/v1/images/generations`, model
+ * `gpt-image-1`) under the `studio-assistant` feature slug — the same slug
+ * Studio already uses for OpenAI text and which is authorized for logged-in
+ * WordPress.com users. (Telex's `telex-theme-image` Imagen feature returns 403
+ * for non-Telex accounts, so it can't be reused here.) Auth reuses the user's
+ * WordPress.com OAuth token, so a logged-in user gets imagery with no extra
+ * credentials.
+ */
+
+const DEFAULT_PROXY = 'https://public-api.wordpress.com/wpcom/v2/ai-api-proxy';
+const DEFAULT_IMAGE_MODEL = 'gpt-image-1';
+const DEFAULT_IMAGE_FEATURE = 'studio-assistant';
+
+export type ImageAspectRatio = '1:1' | '3:4' | '4:3' | '9:16' | '16:9';
+
+// gpt-image-1 only accepts a fixed set of sizes. Map our aspect ratios to the
+// nearest supported size (square / landscape / portrait).
+function sizeForAspect( aspect: ImageAspectRatio ): string {
+	switch ( aspect ) {
+		case '16:9':
+		case '4:3':
+			return '1536x1024';
+		case '9:16':
+		case '3:4':
+			return '1024x1536';
+		default:
+			return '1024x1024';
+	}
+}
+
+/**
+ * Map a free-form hint (an AI_IMAGE aspect token like "16:9", a keyword like
+ * "hero"/"portrait", or a "1792x1024" dimension string) to a supported aspect
+ * ratio.
+ */
+export function aspectFromHint( hint?: string ): ImageAspectRatio {
+	const h = ( hint ?? '' ).toLowerCase().trim();
+
+	const dims = h.match( /(\d+)\s*[x×]\s*(\d+)/ );
+	if ( dims ) {
+		const ratio = Number( dims[ 1 ] ) / Number( dims[ 2 ] );
+		if ( ratio > 1.6 ) {
+			return '16:9';
+		}
+		if ( ratio > 1.2 ) {
+			return '4:3';
+		}
+		if ( ratio < 0.6 ) {
+			return '9:16';
+		}
+		if ( ratio < 0.85 ) {
+			return '3:4';
+		}
+		return '1:1';
+	}
+
+	if ( /16\s*[:x]\s*9|wide|landscape|hero|banner|cover/.test( h ) ) {
+		return '16:9';
+	}
+	if ( /4\s*[:x]\s*3/.test( h ) ) {
+		return '4:3';
+	}
+	if ( /9\s*[:x]\s*16|tall/.test( h ) ) {
+		return '9:16';
+	}
+	if ( /3\s*[:x]\s*4|portrait/.test( h ) ) {
+		return '3:4';
+	}
+	if ( /1\s*[:x]\s*1|square|avatar|icon/.test( h ) ) {
+		return '1:1';
+	}
+	return '16:9';
+}
+
+async function resolveWpcomToken(): Promise< string > {
+	const inline = process.env.STUDIO_WPCOM_TOKEN?.trim();
+	if ( inline ) {
+		return inline;
+	}
+	const token = await readAuthToken();
+	if ( ! token?.accessToken ) {
+		throw new Error(
+			'WordPress.com login required for AI image generation. Run `studio auth login`.'
+		);
+	}
+	return token.accessToken;
+}
+
+interface OpenAiImageResponse {
+	data?: Array< { b64_json?: string } >;
+}
+
+export async function generateImageBytes(
+	prompt: string,
+	aspectRatio: ImageAspectRatio = '16:9'
+): Promise< Buffer > {
+	const token = await resolveWpcomToken();
+	const proxy = ( process.env.WPCOM_AI_PROXY_BASE_URL?.trim() || DEFAULT_PROXY ).replace(
+		/\/+$/,
+		''
+	);
+	const model = process.env.STUDIO_WSG_IMAGE_MODEL?.trim() || DEFAULT_IMAGE_MODEL;
+	const feature = process.env.STUDIO_WSG_IMAGE_FEATURE?.trim() || DEFAULT_IMAGE_FEATURE;
+	const endpoint = `${ proxy }/v1/images/generations`;
+
+	// Retry transient proxy hiccups (503/502/504/429). The thrown messages embed
+	// the HTTP status so isTransientError classifies them correctly.
+	const base64 = await withTransientRetry( async () => {
+		const response = await fetch( endpoint, {
+			method: 'POST',
+			headers: {
+				Authorization: `Bearer ${ token }`,
+				'X-WPCOM-AI-Feature': feature,
+				'content-type': 'application/json',
+			},
+			body: JSON.stringify( {
+				model,
+				prompt,
+				n: 1,
+				size: sizeForAspect( aspectRatio ),
+			} ),
+		} );
+
+		if ( ! response.ok ) {
+			const detail = await response.text().catch( () => '' );
+			throw new Error(
+				`WordPress.com image API request failed (HTTP ${ response.status }): ${ detail.slice(
+					0,
+					300
+				) }`
+			);
+		}
+
+		const data = ( await response.json() ) as OpenAiImageResponse;
+		const encoded = data.data?.[ 0 ]?.b64_json;
+		if ( ! encoded ) {
+			throw new Error( 'WordPress.com image API returned no image data.' );
+		}
+		return encoded;
+	} );
+
+	return Buffer.from( base64, 'base64' );
+}
diff --git a/apps/cli/ai/skills.ts b/apps/cli/ai/skills.ts
index 5325e83833..94e5b3a6ad 100644
--- a/apps/cli/ai/skills.ts
+++ b/apps/cli/ai/skills.ts
@@ -22,12 +22,23 @@ function parseSkillFile( filePath: string ): Skill | null {
 
 let cachedSkills: Skill[] | null = null;
 
+// Absolute path to the bundled skills directory. `import.meta.dirname` resolves
+// to `apps/cli/ai` in source/test runs and to the bundle output root after the
+// vite build (which copies `ai/skills` to the output root). The whole `skills`
+// tree is copied, so subdirectories like `site-generator/generators` ship too —
+// the generation pipeline resolves its prompt fragments from here via this
+// helper rather than its own `import.meta.dirname`, which would point at the
+// wrong place once bundled.
+export function getSkillsRoot(): string {
+	return path.resolve( import.meta.dirname, 'skills' );
+}
+
 // Discovers `apps/cli/ai/skills/<name>/SKILL.md` files at startup; cached
 // for the process lifetime since skills never change at runtime.
 export function loadSkills(): Skill[] {
 	if ( cachedSkills ) return cachedSkills;
 
-	const skillsRoot = path.resolve( import.meta.dirname, 'skills' );
+	const skillsRoot = getSkillsRoot();
 
 	if ( ! fs.existsSync( skillsRoot ) ) {
 		// Loud warning so a broken bundle path doesn't silently disable Skill.
diff --git a/apps/cli/ai/skills/companion-plugin/SKILL.md b/apps/cli/ai/skills/companion-plugin/SKILL.md
new file mode 100644
index 0000000000..d600edca57
--- /dev/null
+++ b/apps/cli/ai/skills/companion-plugin/SKILL.md
@@ -0,0 +1,441 @@
+---
+name: companion-plugin
+description: The WordPress companion plugin for generated sites — where all behavior lives: custom post types, taxonomies, post meta, REST routes, and build-less plain-JS Gutenberg blocks. Load before generating any site behavior or custom blocks.
+---
+
+# Companion Plugin
+
+A generated WordPress site is always **two packages**:
+
+1. A **pure presentation theme** — `theme.json`, `style.css`, `templates/`, `parts/`, `patterns/`, `assets/`. It declares fonts, colors, spacing, and layout. Its `functions.php` is minimal: enqueue `style.css` on the front end and `add_editor_style`. Nothing else. No custom post types, no REST routes, no block registration, no content seeding.
+2. A **companion plugin** — everything that is *behavior*: custom post types, taxonomies, post meta, REST API routes, and custom Gutenberg blocks.
+
+This skill is the runbook for the companion plugin. The rule is absolute: **if it is behavior, it goes in the plugin, not the theme.** A theme that registers a CPT or a REST route is a defect. A plugin that ships `theme.json` or templates is a defect.
+
+You write real files to disk. The theme lives at `<site>/wp-content/themes/<slug>/`. The plugin lives at `<site>/wp-content/plugins/<slug>-functionality/`. Content (pages, posts, CPT entries, sample submissions) is **seeded into the live WordPress database** via WP-CLI / the `seed_content` tool — never baked into either package as content files. You write PHP, JS, and JSON files exactly as a human plugin developer would, and you seed the database directly.
+
+## When the companion plugin is needed at all
+
+Not every site needs a companion plugin. Decide before scaffolding:
+
+- **No plugin** — a purely editorial/marketing site whose every section is core blocks (hero, testimonials, features, pricing, team, FAQ, gallery, CTA). No forms, no custom data, no interactive widgets. Ship only the theme; seed pages/posts into the DB.
+- **Plugin required** — the site needs *any* of:
+  - A **custom post type** beyond `post`/`page` (events, menu items, properties, team members displayed as a structured archive).
+  - A **form that persists** (contact, booking, reservation, RSVP, review, newsletter, lead capture).
+  - A **custom Gutenberg block** for project-specific interactivity or data that core blocks plus recommended plugins cannot provide (see [Custom block: warranted or not](#custom-block-warranted-or-not)).
+  - A **REST route** the front end calls.
+
+When in doubt, prefer core blocks and skip the plugin. A plugin is overhead the site owner has to maintain; only create one when behavior genuinely lives outside the theme's presentational scope.
+
+## Plugin file structure
+
+Lay the plugin out under `<site>/wp-content/plugins/<slug>-functionality/`. The directory name and main file share the slug. Pick one canonical prefix for the whole plugin (call it `PREFIX` below — e.g. `acme`) and use it consistently for the text domain, function names, hooks, option keys, REST namespace, and block names.
+
+```
+<slug>-functionality/
+    <slug>-functionality.php      ← main plugin file (header + bootstrap)
+    inc/
+        post-types.php            ← register_post_type + register_post_meta + register_taxonomy
+        rest.php                  ← register_rest_route handlers
+    blocks/
+        <block-slug>/
+            block.json            ← apiVersion 3 metadata
+            render.php            ← server render (dynamic blocks)
+            editor.js             ← editor component (plain JS, no JSX)
+            view.js               ← front-end behavior (plain JS, no JSX)
+            style.css             ← shared front-end + editor styles
+            editor.css            ← editor-only styles (optional)
+```
+
+There is **no `src/` and no `build/` directory** and **no `package.json`**. Blocks are build-less: the JS you write is the JS that ships. `block.json` paths point at the plain files you authored, in place. Do not chain `wp-scripts build`; do not invent a compile step.
+
+### Main file header and bootstrap
+
+The main file carries the standard plugin header docblock and requires the `inc/` files. Keep it thin.
+
+```php
+<?php
+/**
+ * Plugin Name:       Acme Functionality
+ * Description:       Behavior for the Acme site — custom post types, REST routes, and blocks.
+ * Version:           1.0.0
+ * Requires at least: 6.5
+ * Requires PHP:      8.0
+ * Text Domain:       acme
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+    exit;
+}
+
+require_once __DIR__ . '/inc/post-types.php';
+require_once __DIR__ . '/inc/rest.php';
+
+/**
+ * Register every custom block from its own directory.
+ */
+add_action( 'init', static function (): void {
+    foreach ( array( 'menu-filter', 'reservation-form' ) as $block ) {
+        register_block_type( __DIR__ . '/blocks/' . $block );
+    }
+} );
+```
+
+`register_block_type( __DIR__ . '/blocks/<slug>' )` points at the directory containing the **authored** `block.json` — there is no build output to point at. WordPress reads `block.json` and resolves `editorScript`, `viewScript`, `style`, `editorStyle`, and `render` paths relative to that directory.
+
+## Custom post types, taxonomies, and meta
+
+Register everything on `init` at default priority. Always set `show_in_rest => true` — it powers the block editor and is what lets block bindings and REST reads see the data.
+
+### CPT kinds
+
+There are two kinds, with different argument shapes:
+
+- **Content CPT** (public, displayed on the site — events, products, team, properties):
+  - `public => true`, `has_archive => '<slug-without-prefix>'`, `show_in_rest => true`
+  - `supports` includes `'title'`, `'editor'`, `'custom-fields'`, `'thumbnail'`
+  - Entries are **seeded into the DB**, not authored as files. The theme's archive/single templates render the entries.
+- **Submission CPT** (admin-only data captured from a front-end form — contacts, bookings, reviews):
+  - `public => false`, `show_ui => true`, `show_in_menu => true`, `show_in_rest => true`
+  - `supports` includes `'title'`, `'editor'`, `'custom-fields'`
+  - Real submissions arrive via a REST route (below). Seed 2-3 plausible historical entries into the DB so the `wp-admin` list is never empty.
+
+Prefix every CPT slug with the plugin prefix: `acme_event`, `acme_reservation` — never bare `event` or `reservation`.
+
+### register_post_meta with the right sanitiser
+
+Every structured field on a CPT (price, allergens, booking date, party size, rating, email, phone) gets a `register_post_meta` call in the same `init` callback, right after `register_post_type`. `show_in_rest => true` is mandatory — without it, the block editor and any `core/post-meta` binding read nothing.
+
+```php
+register_post_meta( 'acme_event', 'event_date', array(
+    'type'              => 'string',
+    'single'            => true,
+    'show_in_rest'      => true,
+    'auth_callback'     => static function (): bool { return current_user_can( 'edit_posts' ); },
+    'sanitize_callback' => 'sanitize_text_field',
+) );
+```
+
+**Pick the sanitiser by declared type — and never pass a PHP internal function name as a string callback.** `register_post_meta` wires `sanitize_callback` into the `sanitize_{type}_meta_{key}` filter, which WordPress invokes with **four** arguments (`$value, $key, $object_type, $subtype`). PHP 8 makes extra arguments fatal for internal functions like `floatval`, `intval`, `boolval`, `strval`, `trim`, `strtolower` — the site hard-fatals on `init` the first time the meta is updated. WordPress *userland* functions (`sanitize_text_field`, `absint`, `rest_sanitize_boolean`) silently ignore extra args, so they are safe as bare strings. For anything else, wrap in a single-arg closure.
+
+| Meta type | `sanitize_callback` |
+|-----------|---------------------|
+| `string`  | `'sanitize_text_field'` |
+| `integer` | `'absint'` (non-negative) or `static fn ( $v ) => (int) $v` (signed) |
+| `number`  | `static fn ( $v ) => (float) $v` — **never** `'floatval'` |
+| `boolean` | `'rest_sanitize_boolean'` |
+
+### Taxonomies
+
+Register custom taxonomies on `init` as well, attached to the content CPT, with `show_in_rest => true` and `hierarchical` set to match the use (`true` for category-like, `false` for tag-like).
+
+```php
+register_taxonomy( 'acme_event_type', 'acme_event', array(
+    'label'        => 'Event Types',
+    'public'       => true,
+    'hierarchical' => true,
+    'show_in_rest' => true,
+) );
+```
+
+For ordinary blog posts, use the built-in `category` and `post_tag` — do not invent parallel taxonomies. Create terms when seeding content into the DB; do not write `wp_insert_term` loops in the plugin.
+
+### Flush rewrite rules once
+
+Content CPTs add archive URLs, so flush rewrites once, guarded by an option so it does not run on every request:
+
+```php
+if ( ! get_option( 'acme_rewrite_flushed' ) ) {
+    flush_rewrite_rules();
+    update_option( 'acme_rewrite_flushed', 1, '', false );
+}
+```
+
+## REST routes
+
+Front-end form submissions need a **custom, namespaced** REST route — the auto-created `/wp/v2/<rest_base>` route requires auth. Register on `rest_api_init`, namespace it `PREFIX/v1`, validate and sanitize **every** field via the `args` schema, and return `WP_Error` (with an HTTP status) on failure.
+
+```php
+add_action( 'rest_api_init', static function (): void {
+    register_rest_route( 'acme/v1', '/reservation', array(
+        'methods'             => 'POST',
+        'callback'            => 'acme_handle_reservation',
+        'permission_callback' => '__return_true', // public form; pair with strict args + sanitize
+        'args'                => array(
+            'name'         => array( 'type' => 'string',  'required' => true,  'sanitize_callback' => 'sanitize_text_field' ),
+            'email'        => array( 'type' => 'string',  'required' => true,  'sanitize_callback' => 'sanitize_email' ),
+            'phone'        => array( 'type' => 'string',  'required' => false, 'sanitize_callback' => 'sanitize_text_field' ),
+            'booking_date' => array( 'type' => 'string',  'required' => true,  'sanitize_callback' => 'sanitize_text_field' ),
+            'party_size'   => array( 'type' => 'integer', 'required' => true,  'sanitize_callback' => 'absint' ),
+        ),
+    ) );
+} );
+
+function acme_handle_reservation( WP_REST_Request $request ) {
+    $email = $request->get_param( 'email' );
+    if ( ! is_email( $email ) ) {
+        return new WP_Error( 'invalid_email', 'Please provide a valid email address.', array( 'status' => 400 ) );
+    }
+
+    $post_id = wp_insert_post( array(
+        'post_type'    => 'acme_reservation',
+        'post_status'  => 'publish',
+        'post_title'   => $request->get_param( 'name' ) . ' — ' . current_time( 'Y-m-d H:i' ),
+        'meta_input'   => array(
+            'email'        => $email,
+            'phone'        => $request->get_param( 'phone' ),
+            'booking_date' => $request->get_param( 'booking_date' ),
+            'party_size'   => $request->get_param( 'party_size' ),
+        ),
+    ), true );
+
+    if ( is_wp_error( $post_id ) ) {
+        return new WP_Error( 'insert_failed', 'Could not save your request.', array( 'status' => 500 ) );
+    }
+
+    return rest_ensure_response( array( 'ok' => true, 'id' => $post_id ) );
+}
+```
+
+Rules that make a route production-safe:
+
+- The **form field keys, the `register_post_meta` keys, the REST `args` keys, and the JSON the block POSTs MUST all match exactly.** Drift produces `Missing parameter(s): …` errors at runtime. One field schema, used in four places.
+- Pick the REST `sanitize_callback` from the field's intent: `text`/`tel`/`date`/`time` → `sanitize_text_field`; `email` → `sanitize_email`; `textarea` → `sanitize_textarea_field`; `url` → `esc_url_raw`; `integer` → `absint`; `number` → `static fn ( $v ) => (float) $v`; `boolean` → `rest_sanitize_boolean`.
+- `permission_callback => '__return_true'` is acceptable for a *public* unauthenticated form, but only when paired with strict `args` validation. For any write that should require a logged-in user, verify the REST nonce and a capability in the same callback, returning `WP_Error` (never bare `false`, which WordPress turns into a message-less 403):
+
+```php
+'permission_callback' => static function ( WP_REST_Request $request ): bool|WP_Error {
+    if ( ! wp_verify_nonce( $request->get_header( 'X-WP-Nonce' ), 'wp_rest' ) ) {
+        return new WP_Error( 'rest_forbidden', 'Nonce verification failed.', array( 'status' => 401 ) );
+    }
+    if ( ! current_user_can( 'edit_posts' ) ) {
+        return new WP_Error( 'rest_forbidden', 'You cannot do this.', array( 'status' => 403 ) );
+    }
+    return true;
+},
+```
+
+- Never leak the raw post array in the response — return a redacted, canonical shape.
+- For high-abuse public endpoints, add a honeypot field and/or a transient rate-limit keyed by IP.
+
+## Custom block: warranted or not
+
+Before authoring a block, decide whether it is warranted. The distinction is **content sections** (core blocks) vs **named features** (custom blocks).
+
+**Use core blocks — no custom block** when the request is a content section, even an elaborate one. Compose existing blocks in templates/patterns:
+
+| Request | Core composition |
+|---|---|
+| Hero | `cover` + heading + paragraph + buttons |
+| Testimonials | `columns` > `column` > `group` + `quote` + `image` |
+| Features grid | `columns` > `column` > `group` + `image` + `heading` + `paragraph` |
+| Pricing | `columns` > `column` > `group` + `heading` + `list` + `buttons` |
+| FAQ | repeated `details` blocks |
+| Latest posts | `query` + `post-template` + `post-title` + `post-excerpt` |
+| Gallery / portfolio | `gallery` or `columns` of `image` |
+
+**Build a custom block** only for a *named, project-specific feature* that core blocks plus reasonable recommended plugins cannot provide:
+
+- It **saves, fetches, or computes** data (a form that persists, a price calculator, an availability checker, a live filter over a CPT archive).
+- It is a discrete interactive widget core does not ship (countdown, before/after slider, configurator, map picker, quiz).
+- Editors should insert and configure it as a distinct reusable block with its own controls.
+
+Never fake a block with a raw `core/html` block, a freehand `<section>`, or a `render.php`-only fragment with no `block.json`. If it is a section, compose core blocks. If it is a feature, write a real registered block. Never split the difference.
+
+## The build-less plain-JS block recipe
+
+Custom blocks here are **build-less plain JavaScript**: a `block.json`, a plain `editor.js` and/or `view.js` that call WordPress globals directly, registered server-side with `register_block_type`. No JSX. No `@wordpress/scripts`. No npm. No `import`. No bundler. The editor component uses `wp.element.createElement` (aliased to `el`) instead of JSX, and reads APIs off the `wp.*` globals (`wp.blocks`, `wp.element`, `wp.blockEditor`, `wp.components`, `wp.i18n`). Front-end interactivity uses plain DOM APIs (`querySelector`, `addEventListener`, `classList`, `dataset`) — **never the Interactivity API**, never `data-wp-*` directives, never `viewScriptModule`.
+
+### block.json (apiVersion 3)
+
+```json
+{
+    "$schema": "https://schemas.wp.org/trunk/block.json",
+    "apiVersion": 3,
+    "name": "acme/reservation-form",
+    "title": "Reservation Form",
+    "category": "widgets",
+    "description": "A reservation request form that saves submissions to the site.",
+    "textdomain": "acme",
+    "supports": { "html": false },
+    "editorScript": "file:./editor.js",
+    "viewScript": "file:./view.js",
+    "style": "file:./style.css",
+    "editorStyle": "file:./editor.css",
+    "render": "file:./render.php"
+}
+```
+
+- `apiVersion: 3` always — it gives the iframed editor canvas that matches the front-end render context.
+- Paths are `file:./<name>` resolving to siblings of `block.json` in the block directory — the files you authored, no build indirection.
+- `editorScript` is loaded only in the editor; `viewScript` only on the front end; `style` in both; `editorStyle` only in the editor.
+- Declare `render` only when there is a `render.php`. Declare `viewScript` only when there is a `view.js`. Never declare an asset whose file you did not write — a declared-but-missing file is a hard error.
+- A dynamic block (server-rendered via `render.php`) needs **no `save`** at registration time. A static block needs a `save` and no `render`. Form/data blocks are almost always dynamic so the REST URL and nonce can be printed server-side.
+
+### editor.js (plain JS, no JSX)
+
+`registerBlockType` is called against the metadata `name`. The `edit` function returns elements built with `wp.element.createElement`. There is no `import`; everything comes off `wp.*`.
+
+```js
+( function ( blocks, element, blockEditor, i18n ) {
+    var el = element.createElement;
+    var useBlockProps = blockEditor.useBlockProps;
+    var __ = i18n.__;
+
+    blocks.registerBlockType( 'acme/reservation-form', {
+        edit: function () {
+            var blockProps = useBlockProps( { className: 'acme-reservation-form' } );
+            return el(
+                'div',
+                blockProps,
+                el( 'p', { className: 'acme-reservation-form__editor-note' },
+                    __( 'Reservation form — renders on the front end.', 'acme' ) )
+            );
+        },
+        // Dynamic block: server-rendered, so no front-end markup is saved.
+        save: function () {
+            return null;
+        }
+    } );
+} )( window.wp.blocks, window.wp.element, window.wp.blockEditor, window.wp.i18n );
+```
+
+Notes:
+
+- `useBlockProps` (and `useBlockProps.save()` for static blocks) keeps the editor markup wrapped in standard Gutenberg classes.
+- For configurable blocks, read `wp.blockEditor.InspectorControls` and `wp.components.*` (e.g. `PanelBody`, `TextControl`) off the globals and compose them with `el(...)` — still no JSX.
+- The plugin must enqueue these `wp.*` packages as script dependencies. With build-less blocks, list them in `block.json` is not enough for globals; the simplest reliable path is to declare the editor script's dependencies in PHP via an asset file or by enqueuing with an explicit deps array. The pragmatic recipe: keep `editorScript` in `block.json` and additionally register the dependency array from PHP so `wp-blocks`, `wp-element`, `wp-block-editor`, `wp-components`, and `wp-i18n` are present:
+
+```php
+add_action( 'init', static function (): void {
+    wp_register_script(
+        'acme-reservation-form-editor',
+        plugins_url( 'blocks/reservation-form/editor.js', __FILE__ ),
+        array( 'wp-blocks', 'wp-element', 'wp-block-editor', 'wp-components', 'wp-i18n' ),
+        '1.0.0',
+        true
+    );
+} );
+```
+
+When you register the editor script explicitly like this, omit `editorScript` from `block.json` and instead pass the handle so `register_block_type` reuses it, or keep `block.json`'s `editorScript` and let WordPress load it without an asset file (acceptable because the script only references already-loaded `wp.*` globals). Prefer the explicit `wp_register_script` form whenever the editor component touches `wp.components` or `wp.blockEditor`, so the dependency graph is correct.
+
+### render.php (server render for dynamic blocks)
+
+Print the REST endpoint and a nonce into data attributes so `view.js` can read them. Escape every output.
+
+```php
+<?php
+$endpoint = esc_url_raw( rest_url( 'acme/v1/reservation' ) );
+$nonce    = wp_create_nonce( 'wp_rest' );
+?>
+<form
+    <?php echo get_block_wrapper_attributes( array( 'class' => 'acme-reservation-form' ) ); ?>
+    data-endpoint="<?php echo esc_attr( $endpoint ); ?>"
+    data-nonce="<?php echo esc_attr( $nonce ); ?>"
+>
+    <label><?php echo esc_html__( 'Name', 'acme' ); ?>
+        <input type="text" name="name" required>
+    </label>
+    <label><?php echo esc_html__( 'Email', 'acme' ); ?>
+        <input type="email" name="email" required>
+    </label>
+    <label><?php echo esc_html__( 'Date', 'acme' ); ?>
+        <input type="date" name="booking_date" required>
+    </label>
+    <label><?php echo esc_html__( 'Party size', 'acme' ); ?>
+        <input type="number" name="party_size" min="1" step="1" required>
+    </label>
+    <button type="submit"><?php echo esc_html__( 'Request reservation', 'acme' ); ?></button>
+    <p class="acme-reservation-form__status" aria-live="polite"></p>
+</form>
+```
+
+Map the input element from the field's type: `text`→`text`, `email`→`email`, `textarea`→`<textarea>`, `url`→`url`, `tel`→`tel`, `date`→`date`, `time`→`time`, `datetime`→`datetime-local`, `integer`→`number step="1"`, `number`→`number step="any"`, `boolean`→`checkbox`. Add the `required` attribute on every field whose schema marks it required.
+
+### view.js (plain DOM, no Interactivity API)
+
+Intercept submit, POST JSON to the REST endpoint with the nonce header, show success/error in the `aria-live` region.
+
+```js
+document.querySelectorAll( '.acme-reservation-form' ).forEach( function ( form ) {
+    form.addEventListener( 'submit', function ( event ) {
+        event.preventDefault();
+        var status = form.querySelector( '.acme-reservation-form__status' );
+        var body   = {};
+        new FormData( form ).forEach( function ( value, key ) {
+            body[ key ] = value;
+        } );
+        // Coerce numeric fields the REST args expect as integers/numbers.
+        if ( body.party_size ) {
+            body.party_size = parseInt( body.party_size, 10 );
+        }
+        status.textContent = 'Sending…';
+        fetch( form.dataset.endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-WP-Nonce': form.dataset.nonce
+            },
+            body: JSON.stringify( body )
+        } )
+            .then( function ( response ) {
+                return response.json().then( function ( data ) {
+                    if ( ! response.ok ) {
+                        throw new Error( ( data && data.message ) || 'Submission failed.' );
+                    }
+                    return data;
+                } );
+            } )
+            .then( function () {
+                form.reset();
+                status.textContent = 'Thank you — we will be in touch.';
+            } )
+            .catch( function ( error ) {
+                status.textContent = error.message;
+            } );
+    } );
+} );
+```
+
+For a *stateful, non-form* block (countdown, slider, filter), the same recipe applies: dynamic block, `render.php` emits the markup with `data-*` config, `save: () => null`, and `view.js` reads `dataset.*`, attaches `addEventListener`, and toggles `classList`. Scope every selector to the block's own class (`.wp-block-acme-<slug>` or the className you set in `render.php`). Never register an Interactivity API store.
+
+### Why a block renders empty (check these first)
+
+A build-less block silently renders nothing when:
+
+1. `register_block_type( __DIR__ . '/blocks/<slug>' )` was never called from the plugin — nothing registered it.
+2. `block.json` declares `"render": "file:./render.php"` but `render.php` is missing or sits at the wrong path. Same for a declared `viewScript` without `view.js`.
+3. A `file:` path points somewhere other than a sibling of `block.json`.
+
+There is no build step to blame here — if the files exist next to `block.json` and `register_block_type` points at the directory, it loads.
+
+## Seeding content into the live database
+
+Content is **never** a file in the plugin or theme. After the packages are written, seed via WP-CLI / the `seed_content` tool, writing directly into the running site's database:
+
+- **Pages and posts** — insert as `page`/`post` with real block markup in `post_content`. Create `category`/`post_tag` terms as needed and attach them; set a post format with `wp post term set` / the appropriate WP-CLI call only when the design uses formats.
+- **Content CPT entries** — insert posts of the CPT type with their `register_post_meta` values filled in via `--meta_input` (or `wp post meta set`), and set a featured image where the design expects one.
+- **Submission CPT samples** — seed 2-3 fictional historical submissions (invented names, `jordan@example.com`-style emails, varied dates across the last ~30 days) so the `wp-admin` list is immediately tangible. Fill every meta field. This bypasses the REST route — it is trusted server-side seeding.
+
+Idempotency is the seeding step's concern, not the plugin's: do not add `_seed_id` meta or `after_switch_theme` seed helpers, and never write `wp_insert_post` loops into the plugin for content. The plugin's only `wp_insert_post` is the one inside a REST submission handler.
+
+## Code quality (applies to all plugin PHP and JS)
+
+- Escape every output by context: `esc_html`, `esc_attr`, `esc_url`, `wp_kses_post`, `esc_textarea`. Never echo a variable raw.
+- Sanitize every input: `sanitize_text_field`, `sanitize_email`, `sanitize_textarea_field`, `esc_url_raw`, `absint`, `wp_kses_post`. Never trust `$_POST`/`$_GET`/`$_REQUEST` directly.
+- Every write endpoint validates input via REST `args` and, when not a public form, verifies nonce + capability in the same callback.
+- `add_option`/`update_option` for anything over ~1 KB must pass `false` for autoload: `update_option( 'acme_cache', $value, false )`.
+- Cache expensive queries/HTTP in transients; bound every `WP_Query` with an explicit `posts_per_page` (never `-1` on unbounded data); use `$wpdb->prepare()` for any raw SQL; use `wp_remote_get()` with a timeout, never `file_get_contents()` for HTTP.
+- Type every PHP signature (params and return); document array shapes in PHPDoc; avoid `mixed`.
+- Make user-facing strings translatable with `__()` / `esc_html__()` against the plugin text domain.
+
+## Block markup rules (when emitting block markup anywhere — render.php, patterns, seeded content)
+
+- Prefer core blocks for content; reserve custom blocks for named features.
+- Put custom classNames **only on the outermost block wrapper** via the block `className` attribute — never on inner DOM.
+- Full-bleed sections: wrap in an outer `group` with `align:full`.
+- Whenever a block sets `backgroundColor` it MUST also set `textColor` (and navigation needs full color props) — this prevents invisible text.
+- Sticky positioning goes on the `.wp-block-template-part` wrapper, not the inner group.
+- Scroll animations use progressive enhancement: CSS defines the **final visible** state, JS adds the **initial hidden** state, and every animation respects `@media (prefers-reduced-motion: reduce)`.
+- No emojis anywhere. No decorative HTML comments — only block delimiter comments.
diff --git a/apps/cli/ai/skills/data-persistence/SKILL.md b/apps/cli/ai/skills/data-persistence/SKILL.md
new file mode 100644
index 0000000000..2dcd804162
--- /dev/null
+++ b/apps/cli/ai/skills/data-persistence/SKILL.md
@@ -0,0 +1,463 @@
+---
+name: data-persistence
+description: The canonical WordPress pattern for forms and user-submitted data on generated sites — a custom post type for the data model, a REST route to accept submissions, and a build-less plain-JS block for the UI, all in the companion plugin. Load when the site needs a contact form, signup, booking, or any data capture.
+---
+
+# Data Persistence
+
+Use this skill whenever the site must **persist data a visitor submits through the front end**: a contact form, a booking or reservation, an RSVP, a review or testimonial, a newsletter or lead-capture signup, a quote request — anything whose submissions should land in `wp-admin`.
+
+## Where everything lives
+
+A generated site is two packages:
+
+- The **presentation theme** at `<site>/wp-content/themes/<slug>/` holds only look-and-feel: `theme.json`, `style.css`, `templates/`, `parts/`, `patterns/`, `assets/`. Its `functions.php` is minimal — enqueue `style.css` and `add_editor_style`, nothing more. The theme registers **no** post types, **no** REST routes, **no** blocks, and seeds **no** content.
+- The **companion plugin** at `<site>/wp-content/plugins/<slug>-functionality/` holds **all** behavior. Every part of this pattern — the CPT, the post meta, the REST route, and the form block — goes here, never in the theme.
+
+The three parts are always wired together, all inside the companion plugin:
+
+1. **Custom post type (CPT)** — the data model. One post per submission. Registered with `show_in_rest => true`.
+2. **REST route** — the bridge. A namespaced `POST` route that sanitizes input and inserts a CPT post.
+3. **Build-less plain-JS block** — the UI. A `block.json` plus a plain `view.js` that POSTs the form to the route. No JSX, no `@wordpress/scripts`, no npm build.
+
+Do not substitute parts:
+
+- Do not save submissions to the options table, a transient, or a custom DB table. Use a CPT — it gives you `wp-admin` listing, search, export, and REST for free.
+- Do not render the form as a `core/html` block or a raw HTML snippet. Build a real registered block.
+- Do not use `admin-ajax.php`. Use the REST API.
+- Do not use the Interactivity API for the block. Use plain JS with standard DOM APIs (`fetch`, `addEventListener`).
+
+Content (the sample submissions, and any page that hosts the form) is **seeded into the live WordPress database** via WP-CLI — never baked into the theme as `*.html` files.
+
+## Worked example: contact form
+
+A user asks for "a contact form on the site." Here is the complete wiring. Assume the plugin slug is `acme` and its main file lives at `<site>/wp-content/plugins/acme-functionality/acme-functionality.php`. Split the parts across `includes/` files (`includes/cpt.php`, `includes/rest.php`, `includes/blocks.php`) and `require` them from the main plugin file. See the `companion-plugin` skill for the plugin scaffold and bootstrap.
+
+### 1. Register the CPT and its meta
+
+In `includes/cpt.php` of the companion plugin:
+
+```php
+<?php
+add_action( 'init', 'acme_register_contact_cpt' );
+function acme_register_contact_cpt() {
+    register_post_type( 'acme_contact', array(
+        'label'           => 'Contact Submissions',
+        'labels'          => array(
+            'name'          => 'Contact Submissions',
+            'singular_name' => 'Contact Submission',
+            'menu_name'     => 'Contacts',
+        ),
+        'public'          => false,
+        'show_ui'         => true,
+        'show_in_menu'    => true,
+        'show_in_rest'    => true,
+        'rest_base'       => 'acme-contacts',
+        'menu_icon'       => 'dashicons-email',
+        'supports'        => array( 'title', 'editor', 'custom-fields' ),
+        'capability_type' => 'post',
+        'map_meta_cap'    => true,
+    ) );
+
+    register_post_meta( 'acme_contact', 'email', array(
+        'type'          => 'string',
+        'single'        => true,
+        'show_in_rest'  => true,
+        'auth_callback' => '__return_true',
+    ) );
+    register_post_meta( 'acme_contact', 'phone', array(
+        'type'          => 'string',
+        'single'        => true,
+        'show_in_rest'  => true,
+        'auth_callback' => '__return_true',
+    ) );
+}
+```
+
+Rules:
+
+- Prefix the post-type slug with the plugin slug (`acme_contact`, not `contact`). Slugs are capped at 20 characters.
+- `public => false` — submissions are admin-only data, not public single pages.
+- `show_ui => true` so submissions show up in `wp-admin`.
+- `show_in_rest => true` **always** — it powers both the admin block-editor listing and the auto-created REST collection.
+- Use `register_post_meta` for structured fields (email, phone, booking date, party size, rating) so they are queryable, exportable, and visible.
+- `supports` should include `'title'` (the submission label) plus `'editor'` and/or `'custom-fields'` as appropriate.
+
+### 2. Register the REST route for submissions
+
+The auto-created `/wp/v2/acme-contacts` collection requires authentication to create posts, so it cannot accept anonymous public form submissions. Add a **custom, namespaced** `POST` route that accepts unauthenticated submissions and sanitizes every field. In `includes/rest.php`:
+
+```php
+<?php
+add_action( 'rest_api_init', 'acme_register_contact_route' );
+function acme_register_contact_route() {
+    register_rest_route( 'acme/v1', '/contact', array(
+        'methods'             => 'POST',
+        'callback'            => 'acme_handle_contact_submission',
+        'permission_callback' => '__return_true',
+        'args'                => array(
+            'name'    => array(
+                'required'          => true,
+                'type'              => 'string',
+                'sanitize_callback' => 'sanitize_text_field',
+                'validate_callback' => function ( $value ) {
+                    return is_string( $value ) && strlen( $value ) >= 2 && strlen( $value ) <= 100;
+                },
+            ),
+            'email'   => array(
+                'required'          => true,
+                'type'              => 'string',
+                'format'            => 'email',
+                'sanitize_callback' => 'sanitize_email',
+                'validate_callback' => function ( $value ) {
+                    return is_email( $value ) !== false;
+                },
+            ),
+            'message' => array(
+                'required'          => true,
+                'type'              => 'string',
+                'sanitize_callback' => 'sanitize_textarea_field',
+            ),
+        ),
+    ) );
+}
+
+function acme_handle_contact_submission( WP_REST_Request $request ) {
+    $name    = $request->get_param( 'name' );
+    $email   = $request->get_param( 'email' );
+    $message = $request->get_param( 'message' );
+
+    $post_id = wp_insert_post( array(
+        'post_type'    => 'acme_contact',
+        'post_status'  => 'publish',
+        'post_title'   => $name . ' — ' . current_time( 'Y-m-d H:i' ),
+        'post_content' => $message,
+        'meta_input'   => array(
+            'email' => $email,
+        ),
+    ), true );
+
+    if ( is_wp_error( $post_id ) ) {
+        return new WP_Error( 'acme_insert_failed', 'Could not save your message.', array( 'status' => 500 ) );
+    }
+
+    return new WP_REST_Response( array( 'ok' => true, 'id' => $post_id ), 201 );
+}
+```
+
+Rules:
+
+- Use a **namespaced** route (`acme/v1/contact`), never a generic name.
+- `permission_callback => '__return_true'` is correct for a public form. It is only safe because the `args` schema validates and sanitizes every field. Never skip the schema.
+- Let the `args` schema do validation and sanitization. With `required`, `sanitize_callback`, and `validate_callback` set, WordPress rejects missing or malformed input before your callback runs — no manual checks needed in the body.
+- Never trust the client. Sanitize every field; `sanitize_email` for emails, `sanitize_text_field` for single-line text, `sanitize_textarea_field` or `wp_kses_post` for bodies.
+- Return a `WP_Error` with an HTTP `status` for failures; return a `WP_REST_Response` with `201` on create. Use the standard `rest_*` error-code prefix so clients recognize it.
+- Never echo the raw post array back. Return only the canonical, redacted shape (here, `ok` and `id`).
+- For higher-abuse endpoints add a honeypot field and/or a transient-based rate limit keyed by IP. See `wp-best-practices` for capability and nonce patterns when the endpoint is **not** public.
+
+### 3. Build the build-less plain-JS block
+
+The form UI is a real registered block in the companion plugin — **build-less plain JS**, no compilation. Files under `<site>/wp-content/plugins/acme-functionality/blocks/contact-form/`:
+
+**`block.json`** — metadata. `render` points at a PHP file (server render); `viewScript` is the front-end behavior; `editorScript` is the editor representation.
+
+```json
+{
+    "$schema": "https://schemas.wp.org/trunk/block.json",
+    "apiVersion": 3,
+    "name": "acme/contact-form",
+    "title": "Contact Form",
+    "category": "widgets",
+    "icon": "email",
+    "description": "A contact form that saves submissions to wp-admin.",
+    "textdomain": "acme",
+    "render": "file:./render.php",
+    "editorScript": "file:./editor.js",
+    "viewScript": "file:./view.js",
+    "style": "file:./style.css"
+}
+```
+
+**`render.php`** — server-rendered HTML, printing the REST endpoint and a nonce as data attributes. Put the custom class only on the outermost wrapper via `get_block_wrapper_attributes`; inner DOM carries no custom classNames.
+
+```php
+<?php
+$endpoint = esc_url_raw( rest_url( 'acme/v1/contact' ) );
+$nonce    = wp_create_nonce( 'wp_rest' );
+?>
+<form
+    <?php echo get_block_wrapper_attributes( array( 'class' => 'acme-contact-form' ) ); ?>
+    data-endpoint="<?php echo esc_attr( $endpoint ); ?>"
+    data-nonce="<?php echo esc_attr( $nonce ); ?>"
+>
+    <label>Name<input type="text" name="name" required></label>
+    <label>Email<input type="email" name="email" required></label>
+    <label>Message<textarea name="message" required></textarea></label>
+    <button type="submit">Send</button>
+    <p class="acme-contact-form__status" aria-live="polite"></p>
+</form>
+```
+
+**`editor.js`** — plain JS, no JSX. Register the block with `wp.blocks.registerBlockType` using `wp.element.createElement`. This example deliberately uses **only** `wp.blocks` and `wp.element` — both are always present in the editor before any block editorScript runs, so a build-less `editorScript: "file:./editor.js"` works with no dependency declaration. The editor representation is a static preview; the live `render.php` runs on the front end.
+
+```js
+( function ( blocks, element ) {
+    var el = element.createElement;
+
+    blocks.registerBlockType( 'acme/contact-form', {
+        edit: function () {
+            return el(
+                'form',
+                { className: 'acme-contact-form' },
+                el( 'label', null, 'Name', el( 'input', { type: 'text', disabled: true } ) ),
+                el( 'label', null, 'Email', el( 'input', { type: 'email', disabled: true } ) ),
+                el( 'label', null, 'Message', el( 'textarea', { disabled: true } ) ),
+                el( 'button', { type: 'button', disabled: true }, 'Send' )
+            );
+        },
+        save: function () {
+            // Dynamic block: rendered by render.php on the server.
+            return null;
+        },
+    } );
+} )( window.wp.blocks, window.wp.element );
+```
+
+> If an editor component needs `wp.blockEditor` (e.g. `useBlockProps`, `InspectorControls`) or `wp.components`, those globals are **not** guaranteed for a bare `file:` script — register the editor script in PHP with an explicit dependency array (`wp-blocks`, `wp-element`, `wp-block-editor`, `wp-components`, `wp-i18n`) per the recipe in the `companion-plugin` skill.
+
+**`view.js`** — plain JS front-end behavior. Intercept submit, POST JSON to the REST route, show success and error states. Standard DOM APIs only — no Interactivity API.
+
+```js
+document.querySelectorAll( '.acme-contact-form' ).forEach( function ( form ) {
+    form.addEventListener( 'submit', function ( event ) {
+        event.preventDefault();
+        var status = form.querySelector( '.acme-contact-form__status' );
+        var body = {};
+        new FormData( form ).forEach( function ( value, key ) {
+            body[ key ] = value;
+        } );
+        status.textContent = 'Sending…';
+        fetch( form.dataset.endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-WP-Nonce': form.dataset.nonce,
+            },
+            body: JSON.stringify( body ),
+        } )
+            .then( function ( response ) {
+                return response.json().then( function ( data ) {
+                    if ( ! response.ok ) {
+                        throw new Error( data && data.message ? data.message : 'Submission failed.' );
+                    }
+                    return data;
+                } );
+            } )
+            .then( function () {
+                form.reset();
+                status.textContent = 'Thanks! We will be in touch.';
+            } )
+            .catch( function ( error ) {
+                status.textContent = error.message;
+            } );
+    } );
+} );
+```
+
+The `X-WP-Nonce` header ties the request into WordPress's standard REST request handling (and, for a logged-in user, identifies the current user; for an anonymous visitor the nonce is generated for user 0 and is not by itself authenticating). The route still allows anonymous submissions (`permission_callback => '__return_true'`), but sending the nonce keeps the request on the normal REST path and lets you tighten the permission callback later without changing the block.
+
+### 4. Register the block server-side
+
+Register from the block directory in `includes/blocks.php`. Because `block.json` names `view.js`/`editor.js` as files, WordPress enqueues them automatically — there is no build directory.
+
+```php
+<?php
+add_action( 'init', 'acme_register_blocks' );
+function acme_register_blocks() {
+    register_block_type( plugin_dir_path( __DIR__ ) . 'blocks/contact-form' );
+}
+```
+
+### 5. Put the block on a page in the live DB
+
+If the site has a dedicated Contact page, the form block belongs in that page's content. Do **not** write a `content/*.html` file. Seed the page into the running database with WP-CLI, with the block delimiter inline:
+
+```bash
+wp post create \
+  --post_type=page \
+  --post_status=publish \
+  --post_title='Contact' \
+  --post_content='<!-- wp:acme/contact-form /-->' \
+  --path=<site>
+```
+
+### 6. Seed sample submissions into the live DB
+
+A submission CPT with an empty `wp-admin` list reads as broken — the owner opens "Contacts," sees nothing, and the data model, meta fields, and workflow are invisible. Seed **2–3 fictional submissions into the live database** so the admin experience is tangible immediately. Seeding bypasses the REST route (it runs trusted, server-side) and is done with WP-CLI, not from theme code.
+
+Rules:
+
+- Seed with WP-CLI against the running site, not from `init` (which runs every request) and not from a theme activation hook.
+- **Idempotent by meta.** Guard each insert with a meta key unique to the seed (e.g. `_acme_seed_id => 'contact-1'`), not by title — titles collide with real submissions. Re-running the seed must not duplicate.
+- Fill **every** `register_post_meta` field with realistic values so the data shape is visible.
+- Use varied `post_date` values across the last 30 days — submissions all dated "today" look fake.
+- Submissions are **fictional**: invented names, `@example.com` emails, invented phone numbers. Never real brands or real people.
+
+A small seeding script, run with `wp eval-file <file> --path=<site>`:
+
+```php
+<?php
+$samples = array(
+    array(
+        'seed_id'  => 'contact-1',
+        'name'     => 'Jordan Lee',
+        'email'    => 'jordan@example.com',
+        'phone'    => '+1 555 0100',
+        'message'  => 'We are planning a launch event in the autumn and would love to discuss catering for around 40 guests.',
+        'days_ago' => 2,
+    ),
+    array(
+        'seed_id'  => 'contact-2',
+        'name'     => 'Priya Rao',
+        'email'    => 'priya@example.com',
+        'phone'    => '+44 20 7946 0000',
+        'message'  => 'Quick question about your tasting menu — can you accommodate a nut allergy?',
+        'days_ago' => 6,
+    ),
+    array(
+        'seed_id'  => 'contact-3',
+        'name'     => 'Marcus Chen',
+        'email'    => 'marcus@example.com',
+        'phone'    => '+1 555 0142',
+        'message'  => 'Looking to book the private dining room for a work offsite in November. Availability?',
+        'days_ago' => 14,
+    ),
+);
+
+foreach ( $samples as $s ) {
+    $existing = get_posts( array(
+        'post_type'      => 'acme_contact',
+        'post_status'    => 'any',
+        'meta_key'       => '_acme_seed_id',
+        'meta_value'     => $s['seed_id'],
+        'posts_per_page' => 1,
+        'fields'         => 'ids',
+    ) );
+    if ( $existing ) {
+        continue;
+    }
+    $when = strtotime( '-' . $s['days_ago'] . ' days' );
+    wp_insert_post( array(
+        'post_type'    => 'acme_contact',
+        'post_status'  => 'publish',
+        'post_title'   => $s['name'] . ' — ' . wp_date( 'Y-m-d H:i', $when ),
+        'post_content' => $s['message'],
+        'post_date'    => wp_date( 'Y-m-d H:i:s', $when ),
+        'meta_input'   => array(
+            'email'         => $s['email'],
+            'phone'         => $s['phone'],
+            '_acme_seed_id' => $s['seed_id'],
+        ),
+    ) );
+}
+```
+
+The companion plugin must be active before seeding so the CPT and its meta are registered. Apply the same shape to `_booking`, `_rsvp`, `_review`, `_subscriber`, etc.
+
+## Shape of the data for common features
+
+| Feature | CPT slug | Key meta fields |
+|---|---|---|
+| Contact form | `acme_contact` | `email`, `phone` |
+| Booking / reservation | `acme_booking` | `booking_date`, `booking_time`, `party_size`, `email`, `phone` |
+| RSVP | `acme_rsvp` | `event_id`, `attending`, `guests`, `email` |
+| Review / testimonial | `acme_review` | `rating`, `reviewer_name`, `approved` |
+| Newsletter signup | `acme_subscriber` | `email`, `source`, `consent_at` |
+
+For each, wire the same three parts in the companion plugin: CPT with `show_in_rest => true`, a build-less plain-JS form block, and a namespaced REST `POST` route with a validated `args` schema. Then seed 2–3 fictional rows into the live DB.
+
+## REST endpoint depth
+
+The pattern above gets data flowing. These rules make the endpoint production-safe.
+
+### Permission callbacks beyond public
+
+A public submission form uses `__return_true` plus a strict `args` schema. Any endpoint that reads or mutates existing data must check a real capability and verify the nonce:
+
+```php
+'permission_callback' => function ( WP_REST_Request $request ) {
+    if ( ! wp_verify_nonce( $request->get_header( 'X-WP-Nonce' ), 'wp_rest' ) ) {
+        return new WP_Error( 'rest_forbidden', 'Nonce verification failed.', array( 'status' => 401 ) );
+    }
+    if ( ! current_user_can( 'edit_posts' ) ) {
+        return new WP_Error( 'rest_forbidden', 'You cannot do this.', array( 'status' => 403 ) );
+    }
+    return true;
+},
+```
+
+### Expose CPT meta as first-class REST fields
+
+To read or update meta through REST with a schema and an `enum`:
+
+```php
+add_action( 'rest_api_init', function () {
+    register_rest_field( 'acme_contact', 'status', array(
+        'get_callback'    => function ( $object ) {
+            return get_post_meta( $object['id'], '_acme_status', true ) ?: 'new';
+        },
+        'update_callback' => function ( $value, $object ) {
+            return (bool) update_post_meta( $object->ID, '_acme_status', sanitize_text_field( $value ) );
+        },
+        'schema'          => array(
+            'type'    => 'string',
+            'enum'    => array( 'new', 'reviewed', 'archived' ),
+            'context' => array( 'view', 'edit' ),
+        ),
+    ) );
+} );
+```
+
+### Status-code-correct error responses
+
+Use the standard `rest_*` codes; clients and the block editor recognize them.
+
+```php
+return new WP_Error( 'rest_invalid_param', 'Invalid email address.', array( 'status' => 400 ) );
+return new WP_Error( 'rest_forbidden',     'You cannot do this.',    array( 'status' => 403 ) );
+return new WP_Error( 'rest_not_found',     'Submission not found.',  array( 'status' => 404 ) );
+```
+
+### Do not leak drafts or private posts
+
+A custom read endpoint using `get_posts()` must honor visibility:
+
+```php
+$args = array(
+    'post_type'   => 'acme_contact',
+    'post_status' => current_user_can( 'edit_others_posts' )
+        ? array( 'publish', 'draft', 'private' )
+        : 'publish',
+);
+```
+
+## Checklist
+
+Before treating a data-persistence feature as complete, verify all of it lives in the companion plugin and:
+
+- [ ] CPT registered with a plugin-prefixed slug and `show_in_rest => true`, visible in `wp-admin`.
+- [ ] Structured fields registered via `register_post_meta` with `show_in_rest => true`.
+- [ ] Custom REST route is namespaced (`acme/v1/...`) and validates and sanitizes every field via an `args` schema.
+- [ ] Public submit route uses `__return_true` only because the `args` schema is strict; non-public routes check capability and nonce.
+- [ ] The form UI is a real registered block — build-less plain JS (`registerBlockType` via `wp.element.createElement`, no JSX, no build), not `core/html`, not raw HTML.
+- [ ] Custom class only on the outer wrapper via `get_block_wrapper_attributes`; no custom classNames on inner DOM. No emojis. No decorative HTML comments.
+- [ ] `view.js` uses standard DOM APIs and `fetch` (never the Interactivity API), POSTs JSON with `Content-Type: application/json` and an `X-WP-Nonce` header.
+- [ ] Success and error states are shown to the visitor via an `aria-live` region.
+- [ ] Block registered server-side with `register_block_type` pointing at the block directory.
+- [ ] If the feature has a dedicated page, the page is created in the live DB via WP-CLI with the block delimiter inline — not as a theme `*.html` file.
+- [ ] 2–3 fictional submissions seeded into the live DB via WP-CLI, idempotent by a `_acme_seed_id` meta key, covering every meta field with realistic values and varied `post_date`s.
+
+## Related skills
+
+- `companion-plugin` — the plugin scaffold, bootstrap, and how to split behavior across `includes/`; this is where the CPT, REST route, and block files belong.
+- `wp-best-practices` — sanitization and escaping, nonce and capability checks, REST schema conventions, and build-less plain-JS block conventions.
diff --git a/apps/cli/ai/skills/layout-patterns/SKILL.md b/apps/cli/ai/skills/layout-patterns/SKILL.md
new file mode 100644
index 0000000000..cb4fa3a604
--- /dev/null
+++ b/apps/cli/ai/skills/layout-patterns/SKILL.md
@@ -0,0 +1,627 @@
+---
+name: layout-patterns
+description: Reusable WordPress block-theme layout and motion patterns — fixed sidebar, sticky elements, scrollytelling, magazine grid, landing page, floating chrome, and query-loop layouts, with the CSS gotchas that make them work.
+---
+
+# Layout patterns for WordPress block themes
+
+Concrete, copy-pasteable layout and motion patterns for the generated **presentation theme**. Every pattern here lives in the theme package — `theme.json`, `style.css`, `templates/*.html`, `parts/*.html`, and (for motion) a plain-JS file in `assets/` enqueued from `functions.php`. None of it lives in the companion plugin; the plugin handles CPTs, REST, and custom blocks, not layout.
+
+Where you write the files:
+
+- Theme: `<site>/wp-content/themes/<slug>/` — `theme.json`, `style.css`, `templates/`, `parts/`, `assets/`, and a minimal `functions.php` (front-end `style.css` enqueue + `add_editor_style` + any motion-JS enqueue + the `body_class` filters below). NOTHING else in `functions.php`.
+- Motion JS: `<site>/wp-content/themes/<slug>/assets/<name>.js`. You write these files yourself (the companion is build-less plain JS too, but these are theme front-end scripts). No bundler, no npm, no Interactivity API — plain DOM APIs only.
+
+Universal rules that apply to every pattern below:
+
+- **Custom classNames go ONLY on the outermost block wrapper** via the block `className` attribute. Never hand-author classNames onto inner DOM. CSS hooks key off the wrapper class plus WordPress's generated structure.
+- **Full-bleed sections** = an outer `wp:group` with `"align":"full"`. Do not fake full-bleed with negative margins.
+- **Any block that sets `backgroundColor` MUST also set `textColor`** (and `wp:navigation` needs the full color set — see the navigation note). A background without a paired text color is the #1 cause of invisible text.
+- **Sticky goes on the `.wp-block-template-part` wrapper, not the inner group.** See "Sticky positioning" — this is the single most common motion bug.
+- **Scroll animations are progressive enhancement**: CSS defines the FINAL visible state; JS adds the initial hidden state. If JS never runs, content is visible. Every animation is wrapped in `@media (prefers-reduced-motion: no-preference)` (or guarded in JS).
+- **No emojis. No decorative HTML comments** — only block delimiter comments (`<!-- wp:... -->`).
+
+---
+
+## 1. Sticky positioning (read this before any sticky CSS)
+
+### Why the obvious approach fails
+
+The natural impulse — `position: sticky` on the inner `wp:group` of the header part — fails on every block theme. `<!-- wp:template-part {"slug":"header","tagName":"header"} /-->` renders:
+
+```html
+<header class="wp-block-template-part">
+    <div class="wp-block-group my-header-class">...</div>
+</header>
+```
+
+The inner group is the only child of `<header>`, so `<header>` is exactly as tall as the group. `position: sticky` un-sticks when the parent's bottom edge passes the offset — and that happens after **zero pixels of scroll**. Technically correct, visibly broken.
+
+### The fix: target the template-part wrapper
+
+`<header>` is a direct child of `.wp-site-blocks` (page-height). Stick the wrapper, not the inner group:
+
+```css
+.wp-site-blocks > header.wp-block-template-part {
+    position: sticky;
+    top: 0;
+    z-index: 100;
+}
+```
+
+Now the containing block is `.wp-site-blocks` (full page height) and the header sticks for the whole scroll.
+
+### Shrink-on-scroll (JS toggles a class on the INNER group)
+
+Sticky lives on the wrapper; visual transitions live on the inner group, where JS toggles `.is-shrunk`:
+
+```css
+.my-header-class {
+    transition: padding 0.3s ease, box-shadow 0.3s ease;
+}
+.my-header-class.is-shrunk {
+    padding-top: var(--wp--preset--spacing--20) !important;
+    padding-bottom: var(--wp--preset--spacing--20) !important;
+    box-shadow: 0 2px 12px rgba(0, 0, 0, 0.4);
+}
+.my-header-class.is-shrunk .wp-block-site-title { font-size: 1.15rem !important; }
+```
+
+`assets/header-scroll.js` (write it, enqueue it in footer from `functions.php`):
+
+```js
+document.addEventListener('DOMContentLoaded', function () {
+    var inner = document.querySelector('.my-header-class');
+    if (!inner) return;
+    var threshold = 60, shrunk = false;
+    function onScroll() {
+        var scrolled = window.scrollY > threshold;
+        if (scrolled === shrunk) return;
+        shrunk = scrolled;
+        inner.classList.toggle('is-shrunk', shrunk);
+    }
+    window.addEventListener('scroll', onScroll, { passive: true });
+    onScroll();
+}); 
+```
+
+### Overflow ancestors silently kill sticky
+
+`position: sticky` fails if ANY ancestor between the sticky element and the viewport has `overflow: hidden | auto | scroll | clip`. Common traps: `body { overflow-x: hidden }` (added to tame full-bleed), `.wp-site-blocks { overflow: clip }`, or a wrapper group with overflow set to clip a pseudo-element. If sticky mysteriously fails after you've targeted the right element, audit ancestor `overflow` in DevTools and force:
+
+```css
+:root, body, .wp-site-blocks { overflow: visible; }
+```
+
+### Sticky on anything else
+
+Same principle: the element's **containing block must be much taller than the element**. Sidebar TOC → stick the column whose parent is the tall main column. CTA bar at page root → stick its group (parent is `.wp-site-blocks`). In-section heading → stick it inside its tall section. Ask: "is the parent significantly taller than this element?" If not, move the sticky declaration up a level.
+
+---
+
+## 2. Fixed sidebar layouts (one or two pinned columns)
+
+For sidebar-left, sidebar-right, or dual-sidebar shells. The obvious approach (`body { display: flex }`, `position: fixed` sidebar, `margin-left` on main) breaks WordPress's root-padding-aware alignments and detaches sidebar height from content height. Use **CSS Grid on `.wp-site-blocks` + `position: sticky` on the sidebar grid item** instead.
+
+### Single sidebar — style.css
+
+```css
+.wp-site-blocks {
+    display: grid;
+    grid-template-columns: var(--wp--custom--sidebar-width, 280px) 1fr;
+    min-height: 100vh;
+}
+.wp-site-blocks.has-sidebar-right {
+    grid-template-columns: 1fr var(--wp--custom--sidebar-width, 280px);
+}
+
+.wp-block-template-part.site-sidebar {
+    grid-column: 1;
+    grid-row: 1;              /* required — see auto-placement gotcha */
+    position: sticky;
+    top: 0;
+    align-self: start;        /* without this the item stretches and sticky never engages */
+    height: 100vh;
+    overflow-y: auto;
+    border-right: 1px solid var(--wp--preset--color--rule);
+}
+.wp-site-blocks.has-sidebar-right .wp-block-template-part.site-sidebar {
+    grid-column: 2;
+    border-right: 0;
+    border-left: 1px solid var(--wp--preset--color--rule);
+}
+
+.main-content-area {
+    grid-column: 2;
+    grid-row: 1;
+    min-width: 0;             /* lets long words/URLs wrap instead of overflowing the grid item */
+}
+.wp-site-blocks.has-sidebar-right .main-content-area { grid-column: 1; }
+
+/* align:full inside main must clamp to the main column, not punch across the sidebar */
+.main-content-area .alignfull {
+    margin-left: 0; margin-right: 0; width: 100%; max-width: 100%;
+}
+
+@media (max-width: 782px) {
+    .wp-site-blocks,
+    .wp-site-blocks.has-sidebar-right { grid-template-columns: 1fr; }
+    .wp-block-template-part.site-sidebar {
+        position: static; height: auto; overflow: visible;
+        border-right: 0; border-bottom: 1px solid var(--wp--preset--color--rule);
+        grid-column: 1;
+    }
+    .main-content-area { grid-column: 1; }
+    .main-content-area .alignfull {
+        margin-left: calc(var(--wp--style--root--padding-left, 0px) * -1);
+        margin-right: calc(var(--wp--style--root--padding-right, 0px) * -1);
+        width: auto; max-width: none;
+    }
+}
+```
+
+### Auto-placement gotcha — both items need `grid-row: 1`
+
+Without an explicit `grid-row`, CSS Grid auto-places left-to-right. For `sidebar-right` the sidebar lands in (row 1, col 2), the cursor wraps to row 2, and the main column gets pushed down by a full `100vh` — a phantom empty viewport above the header. Setting `grid-row: 1` on **both** items makes placement deterministic in both modes. Do not use `grid-auto-flow: dense` instead — it reorders later items unpredictably.
+
+### theme.json (single sidebar)
+
+```json
+{
+    "settings": { "custom": { "sidebarWidth": "280px" } },
+    "templateParts": [
+        { "name": "header",  "title": "Header",  "area": "header" },
+        { "name": "sidebar", "title": "Sidebar", "area": "uncategorized" },
+        { "name": "footer",  "title": "Footer",  "area": "footer" }
+    ]
+}
+```
+
+Width 240–320px; below 220px nav labels truncate, above 360px main stops feeling like the focus.
+
+### Template shell (single sidebar) — EXACTLY two top-level children
+
+Every template (`index.html`, `page.html`, `single.html`, archives, CPT singles) uses this shape:
+
+```html
+<!-- wp:template-part {"slug":"sidebar","tagName":"aside","className":"site-sidebar"} /-->
+
+<!-- wp:group {"className":"main-content-area","style":{"spacing":{"margin":{"top":"0"},"padding":{"top":"0","bottom":"0","left":"0","right":"0"},"blockGap":"0"}},"layout":{"type":"default"}} -->
+<div class="wp-block-group main-content-area" style="margin-top:0;padding-top:0;padding-right:0;padding-bottom:0;padding-left:0">
+    <!-- wp:template-part {"slug":"header","tagName":"header"} /-->
+    <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
+    <!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
+</div>
+<!-- /wp:group -->
+```
+
+- `className="site-sidebar"` on **every** sidebar reference. Forget it in one template and that page renders the sidebar in-flow while others pin it.
+- Header + footer render **inside** `.main-content-area` (they scroll with main, not next to the sidebar).
+- For `sidebar-right`, add `has-sidebar-right` to `.wp-site-blocks`/`<body>` via the `body_class` filter in `functions.php`.
+
+### parts/sidebar.html
+
+A single `wp:group` with `layout.type:"flex"`, `orientation:"vertical"`, `justifyContent:"space-between"`: wordmark (`wp:site-title`) at the top, vertical `wp:navigation` (with `wp:page-list`, `orientation:"vertical"`) below, an optional contact strip, and a small footer credit pinned to the bottom. **Vertical padding lives on this inner group, never on the `.site-sidebar` wrapper** — the wrapper is a grid item and padding it clashes with column sizing.
+
+Under sidebar mode the header carries NO primary nav (the sidebar does). Either omit `parts/header.html` entirely (preferred for minimalist designs) or make it a thin utility top-bar (search/account/cart, 36–48px). Never the full site-title + nav strip.
+
+### Dual sidebar (three columns)
+
+Same pattern with a third pinned rail for per-page wayfinding (TOC, metadata, related links):
+
+```css
+.wp-site-blocks {
+    display: grid;
+    grid-template-columns:
+        var(--wp--custom--sidebar-width, 260px) 1fr var(--wp--custom--right-sidebar-width, 240px);
+    min-height: 100vh;
+}
+.wp-block-template-part.site-sidebar,
+.wp-block-template-part.site-right-sidebar {
+    grid-row: 1; position: sticky; top: 0; align-self: start;
+    height: 100vh; overflow-y: auto;
+}
+.wp-block-template-part.site-sidebar       { grid-column: 1; border-right: 1px solid var(--wp--preset--color--rule); }
+.wp-block-template-part.site-right-sidebar { grid-column: 3; border-left:  1px solid var(--wp--preset--color--rule); }
+.main-content-area { grid-column: 2; grid-row: 1; min-width: 0; }
+.main-content-area .alignfull,
+.main-content-area .alignwide { margin-left: 0; margin-right: 0; width: 100%; max-width: 100%; }
+
+@media (max-width: 1024px) {                              /* drop the auxiliary right rail first */
+    .wp-site-blocks { grid-template-columns: var(--wp--custom--sidebar-width, 260px) 1fr; }
+    .wp-block-template-part.site-right-sidebar { display: none; }
+}
+@media (max-width: 782px) {                               /* then stack everything */
+    .wp-site-blocks { grid-template-columns: 1fr; }
+    .wp-block-template-part.site-sidebar,
+    .wp-block-template-part.site-right-sidebar {
+        position: static; height: auto; overflow: visible; border: 0; grid-column: 1;
+    }
+    .wp-block-template-part.site-right-sidebar { display: block; }
+    .main-content-area { grid-column: 1; }
+}
+```
+
+theme.json adds `rightSidebarWidth` (220–260px, a hair smaller than the left so weight reads left→center→right), a `right-sidebar` template part, and tightens `settings.layout.contentSize` to ~720px (documentation reading columns are narrow). The template emits **exactly three** top-level children: sidebar, `.main-content-area`, right-sidebar — both with their respective `className`. Right-rail typography is chrome-scale (`small` or smaller) throughout.
+
+---
+
+## 3. Landing page (one-pager with anchor nav)
+
+Single scrollable page: sticky header with anchor-linked nav, then 3–6 stacked viewport-height sections. The trap: a sticky header makes anchor jumps land the section's top edge BEHIND the header, hiding its heading. Fix with `scroll-padding-top`.
+
+```css
+.wp-site-blocks > header.wp-block-template-part {
+    position: sticky; top: 0; z-index: 50;
+    backdrop-filter: blur(8px);
+    background: var(--wp--preset--color--background);
+}
+html {
+    scroll-behavior: smooth;
+    scroll-padding-top: var(--wp--custom--scroll-padding-top, 80px);
+}
+.wp-site-blocks .alignfull[id] {
+    min-height: 100vh; display: flex; flex-direction: column; justify-content: center;
+}
+.wp-site-blocks .alignfull[id="signup"] {            /* short final form shouldn't force empty scroll */
+    min-height: auto;
+    padding-top: var(--wp--preset--spacing--80);
+    padding-bottom: var(--wp--preset--spacing--80);
+}
+.wp-site-blocks .alignfull[id]:target {
+    box-shadow: inset 4px 0 0 var(--wp--preset--color--accent);
+    transition: box-shadow 200ms ease-out;
+}
+@media (prefers-reduced-motion: reduce) {
+    html { scroll-behavior: auto; }
+    .wp-site-blocks .alignfull[id]:target { box-shadow: none; transition: none; }
+}
+```
+
+theme.json: `settings.custom.scrollPaddingTop` (64–96px, matches rendered header height), `contentSize` ~800px.
+
+Section ids belong on the page-body section groups, via the `anchor` block attribute (which becomes the rendered `id`) — NEVER a raw `<div id="...">`, the editor strips it:
+
+```html
+<!-- wp:group {"align":"full","anchor":"features","style":{"spacing":{"padding":{"top":"var:preset|spacing|80","bottom":"var:preset|spacing|80"}}},"layout":{"type":"constrained"}} -->
+<div class="wp-block-group alignfull" id="features" style="padding-top:var(--wp--preset--spacing--80);padding-bottom:var(--wp--preset--spacing--80)">
+    ...
+</div>
+<!-- /wp:group -->
+```
+
+Navigation uses hand-authored `wp:navigation-link` with `kind:"custom"` and hash URLs (this is the one place hand-authored links are correct, vs the usual `wp:page-list`):
+
+```html
+<!-- wp:navigation-link {"label":"Features","url":"#features","kind":"custom"} /-->
+<!-- wp:navigation-link {"label":"Pricing","url":"#pricing","kind":"custom"} /-->
+```
+
+Section ids MUST match the nav hashes exactly (case-sensitive) — a typo breaks the click silently. Final nav item is usually a CTA `wp:button` anchored to `#signup`.
+
+---
+
+## 4. Magazine grid (the homepage IS the archive)
+
+Editorial themes: thin masthead, a lead story at high weight, then a uniform 3-column card grid. A single query loop can't make "the first item bigger," so use **two `wp:query` blocks**: first `perPage:1` (lead), second `perPage:6` with `offset:1` (grid). CSS keys off two class hooks: `is-style-lead-story` and `is-style-loop-magazine`.
+
+```css
+.wp-site-blocks > header.wp-block-template-part { border-bottom: 1px solid var(--wp--preset--color--rule); }
+.wp-site-blocks > header.wp-block-template-part > .wp-block-group {
+    display: flex; align-items: center; justify-content: space-between;
+    padding-top: var(--wp--preset--spacing--30); padding-bottom: var(--wp--preset--spacing--30);
+}
+
+.wp-block-query.is-style-lead-story .wp-block-post-template { display: block; }
+.wp-block-query.is-style-lead-story .wp-block-post-featured-image { aspect-ratio: 16 / 9; margin-bottom: var(--wp--preset--spacing--40); }
+.wp-block-query.is-style-lead-story .wp-block-post-featured-image img { width: 100%; height: 100%; object-fit: cover; }
+.wp-block-query.is-style-lead-story .wp-block-post-title { font-size: clamp(2rem, 4vw, 3rem); line-height: 1.1; }
+
+.wp-block-query.is-style-loop-magazine .wp-block-post-template {
+    display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--wp--preset--spacing--50);
+}
+.wp-block-query.is-style-loop-magazine .wp-block-post-template > li { display: flex; flex-direction: column; }
+.wp-block-query.is-style-loop-magazine .wp-block-post-featured-image { aspect-ratio: 4 / 3; margin-bottom: var(--wp--preset--spacing--30); }
+.wp-block-query.is-style-loop-magazine .wp-block-post-date { margin-top: auto; }   /* pins byline to card bottom */
+
+@media (max-width: 960px) { .wp-block-query.is-style-loop-magazine .wp-block-post-template { grid-template-columns: repeat(2, 1fr); } }
+@media (max-width: 600px) { .wp-block-query.is-style-loop-magazine .wp-block-post-template { grid-template-columns: 1fr; } }
+
+.wp-block-query.is-style-lead-story + .wp-block-query.is-style-loop-magazine {
+    margin-top: var(--wp--preset--spacing--80);
+    padding-top: var(--wp--preset--spacing--60);
+    border-top: 1px solid var(--wp--preset--color--rule);
+}
+```
+
+theme.json must set `core/post-template.spacing.blockGap` (without it the grid items collapse) and tighten `contentSize` to ~720px:
+
+```json
+{
+    "settings": { "layout": { "contentSize": "720px", "wideSize": "1280px" } },
+    "styles": { "blocks": {
+        "core/post-template": { "spacing": { "blockGap": "var:preset|spacing|50" } },
+        "core/query":         { "spacing": { "blockGap": "var:preset|spacing|60" } }
+    } }
+}
+```
+
+The home template opens with the two query blocks — NEVER `wp:post-content`. Bylines render in a mono font, uppercase, letter-spaced. Homepage usually doesn't paginate ("see all" links to category archives); if needed add `wp:query-pagination` inside the second query, styled small/uppercase/mono — never large pill buttons.
+
+---
+
+## 5. Floating chrome / canvas (imagery owns the viewport)
+
+Photography portfolios, galleries, lookbooks: every image reaches all four viewport edges; chrome is just a floating wordmark + menu via `position: fixed`. Wrong shape for text-heavy sites.
+
+Root padding must be zero here (and only here) so full-bleed means literally the viewport edge, not edge-minus-gutter:
+
+```json
+{
+    "styles": { "spacing": { "padding": { "top": "0", "bottom": "0", "left": "0", "right": "0" } } },
+    "settings": { "useRootPaddingAwareAlignments": true, "layout": { "contentSize": "760px", "wideSize": "1280px" } }
+}
+```
+
+Keep `useRootPaddingAwareAlignments: true` so text pages can still constrain to `contentSize`.
+
+```css
+.wp-site-blocks > header.wp-block-template-part {
+    position: fixed; top: 0; left: 0; right: 0; z-index: 100;
+    pointer-events: none;                         /* let clicks pass through the band */
+    padding: var(--wp--preset--spacing--40) var(--wp--preset--spacing--50);
+}
+.wp-site-blocks > header.wp-block-template-part > .wp-block-group {
+    pointer-events: auto;                         /* restore on actual chrome */
+    display: flex; justify-content: space-between; align-items: flex-start;
+    mix-blend-mode: difference;                   /* legible against any image */
+    color: white;                                 /* difference flips this per backdrop — do NOT use literal #000/#fff */
+}
+.canvas-hero .wp-block-image, .canvas-hero .wp-block-cover { width: 100vw; height: 100vh; margin: 0; }
+.canvas-hero .wp-block-image img, .canvas-hero .wp-block-cover img { width: 100%; height: 100%; object-fit: cover; }
+.canvas-caption {                                 /* captions BETWEEN images, never overlaid */
+    padding: var(--wp--preset--spacing--40) var(--wp--preset--spacing--50);
+    max-width: var(--wp--style--global--content-size);
+    font-family: var(--wp--preset--font-family--mono);
+    font-size: var(--wp--preset--font-size--x-small);
+    text-transform: uppercase; letter-spacing: 0.1em;
+    color: var(--wp--preset--color--muted);
+}
+.wp-block-navigation__responsive-container {      /* hamburger overlay reads cleanly */
+    background: var(--wp--preset--color--background);
+    color: var(--wp--preset--color--foreground);
+    mix-blend-mode: normal;
+}
+```
+
+The `mix-blend-mode: difference` + `color: white` combo keeps the wordmark/menu legible over any photo (white over black = white, white over white = black). The `pointer-events` flip is mandatory — without `auto` on children the fixed band swallows every click. Homepage `<main>` uses `layout.type:"default"` with zero padding so the hero reaches the edges; text pages (about/contact) restore `constrained` layout with comfortable padding. The nav uses `overlayMenu:"always"` (the hamburger IS the menu on every viewport). Register a `has-floating-chrome` body class via `body_class`.
+
+---
+
+## 6. Scroll motion catalog (progressive enhancement only)
+
+Use one or two effects, tastefully. NO libraries (GSAP, Lenis, ScrollMagic, AOS), NO scroll-jacking (`wheel` + `preventDefault`, scroll-snap on the body), NO `position: fixed` headers (use sticky), NO `background-attachment: fixed` parallax. Animate only `opacity`, `transform`, `filter`, `background-color` (never `width`/`height`/`top`/`padding` — they trigger layout).
+
+Every effect respects reduced motion. CSS-only effects wrap in `@media (prefers-reduced-motion: no-preference)`; JS effects early-return on `matchMedia('(prefers-reduced-motion: reduce)').matches`. **CSS defines the final visible state; JS adds the initial hidden state** so a JS failure leaves content visible.
+
+Motion CSS that sets `opacity: 0` must NOT load in the editor iframe (`add_editor_style` would blank the canvas). Keep reveal/hidden-state CSS in a separate `assets/motion.css` enqueued front-end-only via `wp_enqueue_scripts`, NOT in `style.css`. Frontend-only body-class effects (e.g. `body.is-scrolled`) are safe in `style.css` since the class only toggles on the front end.
+
+### A. Section reveal on enter (IntersectionObserver) — the always-on default
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+    .reveal-on-scroll { opacity: 0; transform: translateY(24px); transition: opacity 0.7s ease, transform 0.7s ease; }
+    .reveal-on-scroll.is-visible { opacity: 1; transform: translateY(0); }
+}
+```
+
+Add `className:"reveal-on-scroll"` to each top-level section group (NOT the hero — it's visible on load). `assets/reveal-on-scroll.js` (write + enqueue):
+
+```js
+(function () {
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;
+    var els = document.querySelectorAll('.reveal-on-scroll');
+    if (!('IntersectionObserver' in window) || !els.length) return;
+    var io = new IntersectionObserver(function (entries) {
+        entries.forEach(function (e) {
+            if (e.isIntersecting) { e.target.classList.add('is-visible'); io.unobserve(e.target); }
+        });
+    }, { rootMargin: '0px 0px -10% 0px' });
+    els.forEach(function (el) { io.observe(el); });
+})();
+```
+
+### B. Hero scroll-fade (CSS scroll-driven, no JS)
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+    @supports (animation-timeline: scroll()) {
+        .hero-content {
+            opacity: 1; transform: translateY(0);
+            animation: hero-fade linear both;
+            animation-timeline: scroll(root);
+            animation-range: 0px 60vh;
+        }
+        @keyframes hero-fade { from { opacity: 1; transform: translateY(0); } to { opacity: 0; transform: translateY(-40px); } }
+    }
+}
+```
+
+Apply `hero-content` to the inner content group of the hero `wp:cover` (not the cover itself). First hero only. Browsers without the API get a static hero (acceptable).
+
+### C. Scroll progress bar (CSS scroll-driven) — longform/editorial only
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+    @supports (animation-timeline: scroll()) {
+        .scroll-progress {
+            position: fixed; top: 0; left: 0; right: 0; height: 3px;
+            background: var(--wp--preset--color--accent, currentColor);
+            transform-origin: left center; transform: scaleX(0); z-index: 1000;
+            animation: scroll-progress-grow linear; animation-timeline: scroll(root);
+        }
+        @keyframes scroll-progress-grow { from { transform: scaleX(0); } to { transform: scaleX(1); } }
+    }
+}
+```
+
+Emit `<div class="scroll-progress" aria-hidden="true"></div>` at the top of the page body (it's decorative — screen readers must ignore it).
+
+### D. Sticky narrative + scrolling visuals (NYT-style) — case studies only
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+    .narrative-pin > .wp-block-column:first-child {
+        position: sticky; top: var(--wp--custom--scroll-padding-top, 96px); align-self: flex-start;
+    }
+}
+```
+
+`wp:columns {"className":"narrative-pin"}`: first column = short pinned text (must fit one viewport, else nothing to pin), second column = the long scrolling stack.
+
+### E. Counter on enter (IntersectionObserver) — only with 2–4 real stat numbers
+
+Markup: `<h2 class="counter" data-counter-target="600000" data-counter-suffix="+">0</h2>`. Write `assets/counter.js`: early-return on reduced motion (render final value immediately), IntersectionObserver to a cubic ease-out count-up, `toLocaleString()` for separators.
+
+### Header on-scroll variants (pick AT MOST one)
+
+`assets/header-scroll.js` toggles `body.is-scrolled` past a 60px threshold and (under no-preference) `body.header-hidden` while scrolling down. Variants:
+
+1. **Shrink** — section 1's `.is-shrunk` pattern.
+2. **Invert** — transparent over hero, solid past fold (needs the picked palette tokens, so this CSS goes in `style.css` keyed off `body.is-scrolled`):
+   ```css
+   @media (prefers-reduced-motion: no-preference) {
+       .wp-site-blocks > header.wp-block-template-part > .wp-block-group { transition: background-color 0.3s ease, color 0.3s ease, backdrop-filter 0.3s ease; }
+       body.is-scrolled .wp-site-blocks > header.wp-block-template-part > .wp-block-group {
+           background-color: var(--wp--preset--color--background); color: var(--wp--preset--color--primary); backdrop-filter: blur(8px);
+       }
+   }
+   ```
+3. **Hide on scroll-down, show on scroll-up** (longform):
+   ```css
+   @media (prefers-reduced-motion: no-preference) {
+       .wp-site-blocks > header.wp-block-template-part { transition: transform 0.3s ease; }
+       body.header-hidden .wp-site-blocks > header.wp-block-template-part { transform: translateY(-100%); }
+   }
+   ```
+4. **Active-anchor underline** (landing-page only) — `assets/active-anchor.js` watches each `<section id>` and toggles `.is-active` on the matching `<a href="#...">` (use `rootMargin: -40% 0px -40% 0px` to track the viewport's middle band):
+   ```css
+   @media (prefers-reduced-motion: no-preference) {
+       .wp-block-navigation a { position: relative; }
+       .wp-block-navigation a::after { content: ''; position: absolute; left: 0; right: 0; bottom: -4px; height: 2px; background: currentColor; transform: scaleX(0); transform-origin: left center; transition: transform 0.3s ease; }
+       .wp-block-navigation a.is-active::after { transform: scaleX(1); }
+   }
+   ```
+
+### Per-page budget
+
+- **Homepage**: section reveal (A) is mandatory and free; pick 1–2 of B/C/D/E and at most ONE header variant. Zero rich effects is also valid for minimal themes.
+- **Other pages**: section reveal (A) only.
+- **CPT single entries**: none.
+
+Enqueue each motion JS in the footer from `functions.php`:
+
+```php
+add_action( 'wp_enqueue_scripts', function () {
+    wp_enqueue_script(
+        'myprefix-reveal-on-scroll',
+        get_theme_file_uri( 'assets/reveal-on-scroll.js' ),
+        array(), wp_get_theme()->get( 'Version' ), true
+    );
+} );
+```
+
+---
+
+## 7. Query-loop layouts (front-end archives and listings)
+
+Content is seeded into the live DB (via WP-CLI / the seed_content tool), and CPTs/meta come from the companion plugin. The theme's job is the **loop layout** in templates. Every `wp:query` loop is three decisions: (1) per-item data composition, (2) loop shape, (3) page composition around it. Don't stamp one shape on every CPT.
+
+### The single hard rule
+
+**Never put `wp:post-content` inside an archive's `wp:post-template`.** It renders the full single-page body for every entry — a wall of full posts. Compose from post-* primitives: `wp:post-featured-image`, `wp:post-title`, `wp:post-excerpt`, `wp:post-date`, `wp:post-author-name`. `wp:post-content` is correct only in `single-<cpt>.html` (one detail page, not a loop).
+
+### Rendering structured meta (price, role, year, date)
+
+There is NO `wp:post-meta` block — emitting it renders nothing. Use **block bindings** on a paragraph or heading (the companion plugin registers each meta key with `show_in_rest => true`, which bindings require):
+
+```html
+<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"core/post-meta","args":{"key":"price"}}}},"fontSize":"small"} -->
+<p></p>
+<!-- /wp:paragraph -->
+```
+
+For a labelled value ("Maker: …"), pair a static paragraph and a bound paragraph in a flex `wp:group`. The empty `<p></p>` is a placeholder replaced at render time.
+
+### Picking a shape (decide in this order)
+
+1. **Page role** is decisive.
+   - Homepage preview (archive lives elsewhere) → horizontal rail or compact 3-col grid, capped 4–6. NOT editorial list / zigzag / cover-hero — giant single-column rows look broken on a homepage.
+   - Hero archive (the loop IS the page) → richest shapes: editorial list, zigzag, magazine, featured+rest.
+   - Secondary listing → grid or list. Mid-page band → rail, compact list, simple grid.
+2. **Entry count** (dedicated archives): 3–6 → editorial list / zigzag / cover-hero; 6–12 → grid (2–3 col) / featured+rest; 12–30 → dense grid / compact list; 30+ → compact list / pagination / sibling loops.
+3. **Visual weight per entry**: portraits → grid; long detail → editorial list / zigzag; single value (price) → compact list; photographic → cover-hero; prose → magazine / featured+rest.
+4. **Brand voice**: editorial → list/magazine; minimal → consistent-chrome grid; lookbook → cover-hero/magazine; brutalist → hairline-border grid/compact list.
+5. **Natural data axis**: chronological → timeline / date-ordered; tiered → featured+rest; two slices → sibling loops; geographic → compact list with location meta.
+
+Pick by **domain purpose, not slug** — a CPT listing dentists is People (portrait + name + role), not "Default."
+
+### Shape: Card grid (equal-weight uniform grid)
+
+```html
+<!-- wp:query {"query":{"postType":"<cpt-slug>","perPage":12,"order":"asc","orderBy":"menu_order"},"align":"wide"} -->
+<div class="wp-block-query"><!-- wp:post-template {"layout":{"type":"grid","columnCount":3},"style":{"spacing":{"blockGap":"var:preset|spacing|40"}}} -->
+<!-- wp:group {"tagName":"article","style":{"spacing":{"padding":"var:preset|spacing|30","blockGap":"var:preset|spacing|20"},"border":{"radius":"12px"}},"layout":{"type":"constrained"}} -->
+<article class="wp-block-group">
+    <!-- wp:post-featured-image {"isLink":true,"aspectRatio":"4/3","style":{"border":{"radius":"8px"}}} /-->
+    <!-- wp:post-title {"isLink":true,"level":3,"fontSize":"medium"} /-->
+    <!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"core/post-meta","args":{"key":"price"}}}},"fontSize":"small"} -->
+    <p></p>
+    <!-- /wp:paragraph -->
+    <!-- wp:post-excerpt {"excerptLength":18} /-->
+</article>
+<!-- /wp:group -->
+<!-- /wp:post-template --></div>
+<!-- /wp:query -->
+```
+
+### Shape: Editorial list / vertical stack (image-side rows, detail-heavy)
+
+Two-column rows (image 40% / text 60%), `align:"wide"`, `className:"is-style-loop-list"` (CSS adds row dividers). Use `wp:columns` with `verticalAlignment:"center"`; surface an overline meta paragraph, a large `wp:post-title`, and a longer `wp:post-excerpt`.
+
+### Shape: Horizontal rail (scrollable strip, "more elsewhere")
+
+`className:"is-style-loop-rail"`, `align:"full"`, `post-template` layout `flex`/`flexWrap:"nowrap"`. CSS adds `overflow-x: auto` + scroll-snap; cards get a fixed width. Cap 4–8 entries.
+
+### Shape: Cover-hero (featured image as background, title overlaid)
+
+`wp:cover {"useFeaturedImage":true,"dimRatio":40,"minHeight":420,"isLink":true}` inside a grid `post-template`. Title + meta go in `wp-block-cover__inner-container` with `textColor:"background"` (text over the dimmed image). Image-dominant — galleries, photo menus.
+
+### Shape: Featured + rest (one promoted, the rest in a grid)
+
+Needs **two queries**: first `perPage:1` rendered as a large cover-hero; second `perPage:6,"offset":1` as a 3-col grid (offset skips the featured entry). No labelling comment between them.
+
+### Shape: Compact list, zigzag, timeline, magazine
+
+- **Compact list** (`is-style-loop-list`): one flex row per entry, title + meta, no images. Long indexes (press, episodes, jobs).
+- **Zigzag** (`is-style-loop-zigzag`): full-width image-text rows; CSS flips column order on `:nth-child(even)`. Portfolio walks, recipes.
+- **Timeline** (`is-style-loop-timeline`): `orderBy:"meta_value"` on a date key; CSS adds a vertical line + node dots via `::before`. Events, milestones.
+- **Magazine** (`is-style-loop-magazine`): grid where CSS makes the first child span 2 columns. Editorial homepages.
+
+When a shape needs a hook, add `className:"is-style-loop-<shape>"` to the `wp:query` and ship the matching rule in `style.css`. The shapes are starting points — invent new ones with the post-* primitives + standard layout blocks when the data calls for it (e.g. a status board, a comparison rail).
+
+### Page composition around the loop
+
+Surround the loop with the page's voice: intro + loop + CTA (most pages); manifesto + loop (about/team); hero feature + archive (editorial homepages); loop as one band among full-bleed bands; or loop + sibling loop (two queries slicing the same CPT — "upcoming / past" via `metaQuery` on a date key, "featured / recent" via `offset`). Each sibling loop can pick its own shape.
+
+---
+
+## Cross-cutting checklist
+
+1. Custom classNames only on outer block wrappers; full-bleed via `align:full` outer group.
+2. `backgroundColor` always paired with `textColor`; nav gets the full color set.
+3. Sticky on the `.wp-block-template-part` wrapper; audit ancestor `overflow` if it fails.
+4. Grid layouts: `min-width: 0` on text grid items; explicit `grid-row: 1` on sidebar shells.
+5. Motion: final state in CSS, initial hidden state added by JS; every effect respects reduced motion; reveal CSS stays out of `style.css` (out of the editor iframe).
+6. Never `wp:post-content` in a loop's `post-template`; render meta via block bindings (no `wp:post-meta`).
+7. No emojis, no decorative HTML comments. Plain-JS motion files in `assets/`, enqueued front-end-only — no bundler, no Interactivity API.
diff --git a/apps/cli/ai/skills/site-generator/SKILL.md b/apps/cli/ai/skills/site-generator/SKILL.md
new file mode 100644
index 0000000000..55043db53b
--- /dev/null
+++ b/apps/cli/ai/skills/site-generator/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: site-generator
+description: Generate a complete WordPress site — a pure-presentation theme plus a companion plugin — from a description. Load FIRST when the user wants to build a whole new site or theme. Orchestrates spec, design selection, parallel theme generation, companion plugin, content seeding, AI imagery, and validation.
+user-invokable: true
+---
+
+# Site Generator
+
+This is the orchestrator for building a complete WordPress site end to end. It
+uses dedicated generation tools that run many model calls in parallel and write
+whole packages to disk in one call — far faster and more complete than writing
+files one per turn. Your job is to drive the pipeline in order and verify the
+result, not to hand-author theme files.
+
+## Output model (read this first)
+
+Every generated site is TWO packages:
+
+- **Theme** — pure presentation: `theme.json`, `style.css`, `templates/`,
+  `parts/`, `patterns/`, `assets/`. Minimal `functions.php`. No behaviour.
+- **Companion plugin** — all behaviour: custom post types, taxonomies, post
+  meta, REST routes, and build-less plain-JS blocks. Survives a theme switch.
+
+Page content is seeded into the **live database**, never baked into the theme.
+For background, the `theme-architecture`, `companion-plugin`, `layout-patterns`,
+`data-persistence`, and `wp-best-practices` skills hold the doctrine the
+generators apply; load them if you need to reason about a result or fix it.
+
+## Pipeline
+
+### 1. Resolve the site
+
+- If the user is building a brand-new site, run the `site-spec` skill to gather
+  the site name and any layout preference, then call **`site_create`**.
+- If they want to use an existing/active site, use that one (`site_info`).
+
+### 2. Build the site spec (JSON)
+
+Synthesize a JSON spec string you will pass to every generation tool. Use the
+`theme-architecture` skill's layout-mode and content-mode taxonomy to choose
+sensible values, and the `visual-design` skill for aesthetic direction. Shape:
+
+```json
+{
+  "name": "Ember & Oak",
+  "type": "restaurant",
+  "audience": "local diners looking for a special evening",
+  "tone": "warm, refined, unfussy",
+  "topic": "a wood-fired neighbourhood restaurant in Lisbon",
+  "layoutPreference": "landing-page or vertical-stack",
+  "pages": ["Home", "Menu", "About", "Reservations", "Contact"],
+  "features": ["reservation form"]
+}
+```
+
+Keep it concise but specific; the topic and tone drive design quality.
+
+### 3. Generate and choose a design direction
+
+Call **`generate_design_previews`** with `nameOrPath` and `spec`. It writes
+several first-fold HTML previews to `<site>/design/` and opens them. Show the
+user the directions and use **AskUserQuestion** to let them pick one (or ask for
+a regenerate). Keep the chosen preview's HTML — you pass it next.
+
+### 4. Generate the theme
+
+Call **`generate_theme`** with `nameOrPath`, `spec`, and `design` (the chosen
+preview's HTML or its brief). It generates the whole theme in parallel, writes
+it, activates it, and returns a **MANIFEST** JSON block at the end of its output.
+**Copy that manifest verbatim** — the next tools need it.
+
+### 5. Generate the companion plugin (only if needed)
+
+If the manifest's `companionPlugin.needed` is `true`, call
+**`generate_companion_plugin`** with `nameOrPath`, `spec`, and the `manifest`.
+It generates CPTs, REST routes, and build-less plain-JS blocks, then activates
+the plugin. A brochure site with no forms/CPTs/interactive blocks skips this.
+
+### 6. Seed content
+
+Call **`seed_content`** with `nameOrPath`, `spec`, and the `manifest`. It
+generates each page's block markup, fills AI_IMAGE placeholders with generated
+imagery, publishes the pages into the database, and sets the home page as the
+static front page.
+
+### 7. Fill theme imagery
+
+Call **`generate_image`** with `nameOrPath` and `themeSlug` (the manifest's
+`themeSlug`) to fill any `AI_IMAGE:` placeholders left in theme templates/parts.
+
+### 8. Verify and fix
+
+- Run **`validate_and_fix_blocks`** (with `nameOrPath` and the relevant
+  content/filePath) on generated block content; rewrite anything it flags.
+- Run **`take_screenshot`** with `viewport: "all"` on the site URL. Check the
+  navigation, hero, full-width sections (they must span the viewport — fix in
+  markup with `align: "full"`, not CSS), color contrast, and spacing. Fix issues
+  with `Edit`/`wp_cli` and re-verify.
+
+## Rules
+
+- The generation tools each run for a while (many parallel model calls). That is
+  expected — let them complete; do not try to hand-write the files yourself.
+- Always pass the SAME `spec` string and the SAME `manifest` through steps 4–7.
+- Never put behaviour in the theme or content in theme files — the tools already
+  enforce the split; don't undo it with manual `wp_cli`/`Write` edits.
+- WordPress.com login is required (AI generation + imagery route through the
+  WordPress.com AI proxy). If a tool reports a login error, tell the user to run
+  `/login`.
+- No emojis in any generated content.
diff --git a/apps/cli/ai/skills/site-generator/generators/_shared.md b/apps/cli/ai/skills/site-generator/generators/_shared.md
new file mode 100644
index 0000000000..3d1a152aa4
--- /dev/null
+++ b/apps/cli/ai/skills/site-generator/generators/_shared.md
@@ -0,0 +1,64 @@
+# Shared generation rules
+
+These rules govern EVERY file you generate for this site, regardless of which specific generator invoked you. They are absolute unless the site spec or the user's original request explicitly overrides one of them. Read them before writing a single line, and re-read the relevant section before you declare colors, choose a layout, or write copy.
+
+## Two-package architecture (never blur the line)
+
+A generated site is always TWO packages with a hard separation of concerns:
+
+- **The theme** (`<site>/wp-content/themes/<slug>/`) is PURE PRESENTATION: `theme.json`, `style.css`, `templates/`, `parts/`, `patterns/`, `assets/`, and a minimal `functions.php` that does nothing but enqueue `style.css` on the front end and call `add_editor_style`. The theme NEVER registers custom post types, taxonomies, post meta, REST routes, or blocks, and NEVER seeds content.
+- **The companion plugin** (`<site>/wp-content/plugins/<slug>-functionality/`) owns ALL behavior: custom post types, taxonomies, post meta, REST API routes, and any custom Gutenberg blocks.
+- **Content** is never baked into files. Pages, posts, and CPT entries are seeded into the LIVE WordPress database (via WP-CLI / the seed-content tool), not written as `*.html` content files in the theme.
+
+When a generator asks for theme markup, do not reach for behavior. When it asks for the plugin, do not reach for presentation. Keep the two clean.
+
+## Composition and block markup
+
+- **No decorative HTML comments.** Only WordPress block delimiter comments (`<!-- wp:<block-name> -->` ... `<!-- /wp:<block-name> -->`) are allowed. Never insert labelling comments like `<!-- Hero -->`, `<!-- Services -->`, or any `<!-- ... -->` that is not a block delimiter. Section identity lives in `className` and block attributes, not in comments.
+- **Output fully expanded block markup.** Never emit `<inner-blocks>` placeholders or any shorthand — write the complete nested markup inside every block.
+- **Prefer core blocks for content.** Compose with `wp:group`, `wp:columns`, `wp:cover`, `wp:media-text`, `wp:heading`, `wp:paragraph`, `wp:buttons`, `wp:image`, `wp:quote`, `wp:details`, `wp:gallery`, `wp:list`, `wp:navigation`, `wp:site-title`, etc. Reach for a custom block (in the companion plugin) only when a feature is genuinely interactive or data-backed and no core block expresses it. `wp:html` is reserved for tiny exotic embeds only — never for heroes, navs, card grids, forms, testimonials, CTAs, sidebars, or any section a core block can express.
+- **One dominant semantic wrapper per section.** Treat every section as self-contained: a single outer `wp:group` (or `wp:cover`) that owns the section, with content nested inside it.
+- **Full-bleed sections use an outer group with `align:full`.** A section that bleeds edge-to-edge (hero, photographic band, footer band, full-bleed CTA strip) is an outer `wp:group`/`wp:cover` with `"align":"full"`. Sections at the theme's wide width use `"align":"wide"` (feature grids, query loops, most sections). Default content alignment is reserved for INNER content holders only — a constrained group nested inside a section that holds readable copy. A top-level section with no `align` will inherit body root padding and render as a narrow column; that is the visual symptom of forgetting this.
+- **Section container vs inner holder.** The outer section container (which owns the background, padding, and `align`) uses `"layout":{"type":"default"}` or omits `layout` — never `constrained` (constrained clamps width and breaks edge-to-edge backgrounds). The inner content holder nested inside it MAY be `constrained` so readable copy sits at content width. The constrained group inside a full-bleed container is the canonical pattern.
+- **Horizontal page gutter lives in `theme.json` root padding only.** Do not add left/right padding to `<main>` wrappers, top-level page groups, template shells, or the page root — that double-pads. Sections break out of root padding via `align`, never via wrapper padding.
+- **Custom classNames go ONLY on the outermost block wrapper**, via the block's `className` attribute (e.g. `{"className":"site-hero"}`). Never put custom classes on inner DOM elements or on nested blocks. Section identity and any custom CSS hooks attach to the outer wrapper; everything inside is styled through that hook or through block attributes.
+- **Sticky positioning goes on the `.wp-block-template-part` wrapper, not the inner group.** When a header (or any part) is sticky, the sticky rule targets the template-part wrapper element, never the inner `wp:group` inside the part.
+
+## Color pairing discipline (read before declaring any block colors)
+
+Inheritance in WordPress block themes is unreliable. A child block whose text color falls through to the body default renders invisible against any parent surface that is not the body background. Defend against it at the block level:
+
+- **Whenever a block declares `backgroundColor` (or `style.color.background`), it MUST also declare `textColor` (or `style.color.text`).** No exceptions, at every level. A tinted `wp:group` that omits its own text color passes the inheritance burden to its children and the chain breaks the moment one child also omits it.
+- **`wp:button` MUST declare BOTH text and background colors** at the block level. `is-style-outline` buttons (transparent background) MUST declare `textColor` AND `borderColor` together.
+- **When a block declares `style.border.width`, it MUST also declare `borderColor`** as a palette slug, so borders never inherit `currentColor`.
+- **`wp:navigation` MUST declare all of: `textColor`, `style.elements.link.color.text`, `overlayBackgroundColor`, `overlayTextColor`, and `style.spacing.blockGap`.** Missing any one breaks at least one of the desktop / hover / mobile-overlay / item-spacing render modes. Mobile overlay defaulting to invisible is the canonical nav bug.
+- **Any block with `layout.type:"grid"` or `layout.type:"flex"` MUST declare `style.spacing.blockGap`** (post-template grids, columns, custom flex groups, `wp:buttons`, `wp:navigation`). WordPress flex/grid layouts have no gap by default. The structural test: right after you write `layout.type:"grid"` or `layout.type:"flex"`, the next attribute should be `style.spacing.blockGap`.
+
+## Design token discipline
+
+- **Reference `theme.json` tokens by slug in block markup.** Use the declared palette, font-size, font-family, and spacing presets: `{"textColor":"primary"}`, `{"fontSize":"large"}`, `{"style":{"spacing":{"padding":{"top":"var:preset|spacing|40"}}}}`. Never introduce hardcoded hex colors, raw px values, or font names in block attributes.
+- **CSS in `style.css` references tokens via CSS variables** — `var(--wp--preset--color--primary)`, `var(--wp--preset--font-family--body)`, `var(--wp--preset--spacing--40)` — rather than hardcoding values. Custom CSS is reserved for polish (typographic detail, link treatments, button variants, image effects, animation states), not for re-implementing layout that block attributes already express.
+- **Fonts are declared in `theme.json`** via `settings.typography.fontFamilies` with `fontFace` entries pointing at the bundled font files. Do NOT enqueue fonts from PHP and do not create a `fonts.php`.
+- **Typography restraint.** Body text around 1rem with line-height 1.5–1.65. Headings scale modestly; cap display text near 3.5rem (e.g. `clamp(2.5rem, 4vw, 3.5rem)`). Never go below line-height 1.0 on any text; heading line-heights stay between 1.1 and 1.3.
+
+## Scroll animation and motion
+
+- **Progressive enhancement only.** CSS defines the FINAL visible state (the element is fully visible and correctly positioned with CSS alone, no JS). JavaScript ADDS the initial hidden state and removes it on scroll/intersection, so that with JS disabled the content is still fully visible. Never let the visible state depend on JS running.
+- **Every animation respects reduced motion.** Wrap motion in `@media (prefers-reduced-motion: reduce)` so that users who prefer reduced motion see the final state with no transition.
+- Keep motion subtle and purposeful; it supports the content, it does not perform.
+
+## Plain JavaScript only (when behavior is involved)
+
+- Any interactive or stateful behavior (countdowns, filters, sliders, calculators, form submission, scroll reveals) is implemented in **plain JavaScript** using standard DOM APIs (`querySelector`, `addEventListener`, `classList`, `dataset`, `fetch`).
+- **Never use the WordPress Interactivity API** (`@wordpress/interactivity`, `data-wp-*` directives, its store/state system).
+- **Custom blocks are build-less plain JS**: a `block.json` plus a plain `view.js`/`editor.js` that calls `wp.blocks.registerBlockType` using `wp.element.createElement` — NO JSX, NO `@wordpress/scripts`, NO npm build step. Blocks are registered server-side with `register_block_type` from the companion plugin.
+
+## Content quality
+
+- **NO EMOJIS anywhere** — not in headings, paragraphs, button labels, navigation, footer text, code comments, or any visible string. Avoid glyphs WordPress auto-converts to emoji (`:)`, `<3`, etc.). If you need iconography, use inline custom SVG.
+- **Realistic, domain-specific copy.** When the spec or request names a business or domain, all body text must reflect it: a bakery's team page is about bakers, a dental clinic's services page lists dental services. Never fall back to generic SaaS/agency/consulting filler.
+- **Cohesive imagery.** Within a logical group (all team photos, all product shots, all entries of one CPT) keep aspect ratio and photographic style consistent, following the image conventions the per-file generator specifies.
+
+---
+
+The specific generator instructions for the file you are about to produce, followed by the site spec JSON and the chosen design direction, follow below — apply every rule above to that work.
diff --git a/apps/cli/ai/skills/site-generator/generators/block.md b/apps/cli/ai/skills/site-generator/generators/block.md
new file mode 100644
index 0000000000..78c269f8ae
--- /dev/null
+++ b/apps/cli/ai/skills/site-generator/generators/block.md
@@ -0,0 +1,223 @@
+# Generator: Custom Gutenberg Block (build-less, plain JS)
+
+You generate ONE custom Gutenberg block for a generated WordPress site. The block lives in the
+site's **companion plugin** — never in the theme. The theme is pure presentation (theme.json,
+templates, parts, patterns, style.css); ALL behavior (custom post types, taxonomies, post meta,
+REST routes, and every custom block) lives in the companion plugin at
+`<site>/wp-content/plugins/<slug>-functionality/`. This generator produces the source for a single
+block under that plugin's `blocks/<block-slug>/` directory.
+
+The block MUST require **no build step**. There is no wp-scripts, no npm, no webpack, no JSX, no
+`src/` → `build/` compilation. You write plain JavaScript files that the browser loads directly. The
+plugin registers the block server-side with `register_block_type()` pointing at the directory that
+holds your `block.json`.
+
+## Input
+
+The task line gives you the block spec:
+
+- **slug** — the block slug, e.g. `availability-checker`. This is the exact slug the directory is
+  named after and the suffix of the block name. Do not rename it or reformat it.
+- **title** — the human-readable title shown in the inserter, e.g. "Availability Checker".
+- **purpose** — what the block does: the interactive behavior, the data it persists or fetches, the
+  default content, the copy and labels.
+
+You will also be given the theme's design tokens (color slugs, font-size slugs, spacing slugs from
+theme.json) and, for data-backed blocks, the companion plugin's registered post type slug, its meta
+keys, and the REST route the plugin exposes. Use those verbatim — do not invent post type slugs,
+meta keys, or routes. The plugin's CPT/REST registration and your block's `fetch()` target must
+match exactly, or submissions fail at runtime with "missing parameter" errors.
+
+## When this generator runs
+
+This generator runs only for **named, interactive or data-backed features** — a discrete noun that
+implies state, computation, persistence, or custom editor controls: booking form, contact form,
+reservation widget, countdown timer, calculator, quote builder, pricing configurator, before/after
+slider, RSVP form, newsletter signup, availability checker, review submission.
+
+It does NOT run for content sections. Heroes, testimonials, feature grids, pricing displays, team
+sections, FAQs, galleries, and CTAs are composed from CORE blocks in templates/patterns, not built
+as custom blocks. If the spec describes layout or content arrangement rather than a stateful
+feature, no custom block is needed.
+
+## The block name
+
+The block name in `block.json` MUST be `<plugin-prefix>/<slug>`, where `<plugin-prefix>` is the
+companion plugin's prefix (the same prefix used for its REST namespace and its block registrations).
+Use the prefix you are given verbatim. Do not derive a different prefix from the theme name or the
+site title. Every block in the plugin shares the one prefix.
+
+## Build-less file shapes
+
+You emit a small, flat set of files for the block directory (NO `src/`, NO `build/`):
+
+| File | Required when |
+|------|---------------|
+| `block.json` | always |
+| `editor.js` | always (editor registration) |
+| `view.js` | the block has front-end interactivity (interactive or form-backed blocks) |
+| `render.php` | the block is dynamic (server-rendered output) |
+
+There is no `index.js`, no `edit.js` + `save.js` split, no `style.scss`/`editor.scss`. Styling comes
+from the theme's design tokens referenced inline in markup (block attributes) and, where needed, plain
+CSS shipped by the plugin or inline `<style>` emitted by `render.php`. Do not reference any SCSS file
+and do not declare a `"style"` or `"editorStyle"` entry that points at a compiled CSS bundle.
+
+### `block.json` (apiVersion 3)
+
+```json
+{
+    "$schema": "https://schemas.wp.org/trunk/block.json",
+    "apiVersion": 3,
+    "name": "<plugin-prefix>/<slug>",
+    "title": "<Title>",
+    "category": "widgets",
+    "description": "<one sentence>",
+    "supports": {
+        "html": false
+    },
+    "editorScript": "file:./editor.js",
+    "viewScript": "file:./view.js",
+    "render": "file:./render.php"
+}
+```
+
+- `apiVersion` is always `3`.
+- `editorScript` is always `file:./editor.js`.
+- Include `viewScript: "file:./view.js"` ONLY when you emit a `view.js`.
+- Include `render: "file:./render.php"` ONLY when the block is dynamic and you emit a `render.php`.
+- Never declare an asset whose source file you do not also emit. A `render` entry with no
+  `render.php`, or a `viewScript` entry with no `view.js`, is a hard error.
+- Declare block attributes here when the block exposes editor-configurable defaults (labels,
+  placeholder copy, endpoint flags). Use the attribute keys consistently across `editor.js`,
+  `render.php`, and `view.js`.
+
+### `editor.js` — registration via `wp.element.createElement` (NO JSX)
+
+`editor.js` registers the block in the editor using the global `wp.*` runtime — no imports, no JSX,
+no transpilation. Use `wp.blocks.registerBlockType` and build markup with
+`wp.element.createElement` (commonly aliased `el`). Use `wp.blockEditor.useBlockProps` for the
+wrapper so the editor markup carries the standard Gutenberg classes. For dynamic blocks the editor
+should render a faithful preview (it does not need to call `save`; server-side `render.php` produces
+the front end).
+
+```js
+( function ( blocks, element, blockEditor ) {
+    var el = element.createElement;
+    var useBlockProps = blockEditor.useBlockProps;
+
+    blocks.registerBlockType( '<plugin-prefix>/<slug>', {
+        edit: function ( props ) {
+            var blockProps = useBlockProps();
+            return el(
+                'div',
+                blockProps,
+                el( 'p', {}, '<Title> — preview' )
+            );
+        },
+        // Dynamic block: front end is rendered by render.php.
+        save: function () {
+            return null;
+        }
+    } );
+} )( window.wp.blocks, window.wp.element, window.wp.blockEditor );
+```
+
+- Read the global runtime off `window.wp` and pass the pieces into the IIFE. Never write
+  `import` statements.
+- Never write JSX. Every element is a `wp.element.createElement` / `el(...)` call.
+- For a dynamic block, `save` returns `null` and `render.php` produces the front end. For a static
+  block (no `render.php`), `save` returns real markup via `useBlockProps.save()` — but interactive
+  and form-backed blocks should almost always be dynamic.
+
+### `view.js` — plain DOM JavaScript for the front end
+
+All front-end interactivity is plain JavaScript using standard DOM APIs:
+`document.querySelectorAll`, `addEventListener`, `classList`, `dataset`, `fetch`. NEVER use the
+WordPress Interactivity API — no `@wordpress/interactivity`, no `data-wp-*` directives, no
+store/state system.
+
+- Scope every query to this block's wrapper class
+  (`document.querySelectorAll('.wp-block-<plugin-prefix>-<slug>')`) and iterate, so multiple
+  instances on one page each behave independently.
+- Guard against double-init and run after the DOM is ready.
+- For stateful UI (countdowns, calculators, sliders, filters), read configuration from
+  `data-*` attributes that `render.php` wrote, hold state in local variables, and update the DOM
+  directly.
+- For form-backed blocks, attach a `submit` handler, `preventDefault`, build a JSON body keyed by
+  the exact meta keys you were given, and `POST` to the plugin's REST route
+  (`/wp-json/<plugin-prefix>/v1/<route>`). Show a submitting state and a success/error message.
+  Enforce `required` client-side to match the server's validation.
+
+### `render.php` — server-side render for dynamic blocks
+
+`render.php` receives `$attributes`, `$content`, and `$block`. Echo the front-end markup using core
+WordPress escaping (`esc_attr`, `esc_html`, `esc_url`). Apply the outermost wrapper with
+`get_block_wrapper_attributes()` so the block's class and any block-supports styles land on the
+outer element. Write configuration the front end needs onto `data-*` attributes on the wrapper.
+Never register a post type, taxonomy, meta, or REST route from `render.php` — the plugin owns all of
+that; `render.php` only renders.
+
+## Markup and styling rules (apply to all emitted markup)
+
+- Prefer core blocks for content; this block contributes only the interactive surface, not
+  surrounding page layout.
+- Put custom class names ONLY on the outermost block wrapper (via `get_block_wrapper_attributes()`
+  on the server, `useBlockProps` in the editor). Never scatter custom classes on inner DOM.
+- Whenever markup sets a `backgroundColor`, it MUST also set a `textColor` so text never goes
+  invisible.
+- Reference theme tokens for color, font size, and spacing — `var(--wp--preset--color--<slug>)`,
+  `var(--wp--preset--font-size--<slug>)`, `var(--wp--preset--spacing--<slug>)` — using the token
+  slugs you were given. Do not hardcode raw hex/px when a token exists.
+- The block's UI surface (inputs, buttons, labels, spacing rhythm, microcopy tone) should feel
+  native to the site's design direction, not a generic widget.
+- Scroll/entrance animations use progressive enhancement: CSS defines the FINAL visible state, JS
+  adds the initial hidden state, and every animation is wrapped in
+  `@media (prefers-reduced-motion: reduce)` to disable it.
+- NO emojis anywhere. NO decorative HTML comments — only block delimiter comments where block markup
+  is involved.
+
+## Data-backed blocks
+
+If the spec describes saving, fetching, or computing persisted data (a form, booking, RSVP, review,
+lead, newsletter signup):
+
+- The companion plugin already registers the post type, its meta keys, and the REST route. Use the
+  exact post type slug, meta keys, and route you were given.
+- The `name` attribute on each `<input>`/`<textarea>`, the JSON body key in the `fetch()` POST, and
+  the plugin's registered meta key/REST arg MUST all be the same string. Any drift causes runtime
+  failures.
+- Pick the input element from the field type: `text`→`<input type="text">`, `email`→
+  `<input type="email">`, `textarea`→`<textarea>`, `url`→`<input type="url">`, `tel`→
+  `<input type="tel">`, `date`→`<input type="date">`, `time`→`<input type="time">`,
+  `datetime`→`<input type="datetime-local">`, integer→`<input type="number" step="1" min="0">`,
+  number→`<input type="number" step="any">`, boolean→`<input type="checkbox">` (POST a real
+  boolean, not the string "on").
+- Add the `required` attribute on every field the server requires.
+- The REST namespace in your `fetch()` URL MUST be `<plugin-prefix>/v1` — the same prefix used in
+  the block name and in the plugin's `register_rest_route()` call.
+
+## Output format
+
+Output ONLY a single JSON object — no markdown fences, no prose, no explanation before or after.
+The object has exactly one top-level key, `files`, whose value maps each emitted file name to its
+full string content. Include ONLY the files the block actually needs:
+
+```json
+{
+    "files": {
+        "block.json": "<full content>",
+        "editor.js": "<full content>",
+        "view.js": "<full content>",
+        "render.php": "<full content>"
+    }
+}
+```
+
+- A static, non-interactive block emits only `block.json` and `editor.js` (with a real `save`).
+- An interactive block emits `block.json`, `editor.js`, `view.js`, and (for dynamic output)
+  `render.php`.
+- A form-backed block is dynamic and interactive: `block.json`, `editor.js`, `view.js`, `render.php`.
+- File contents are JSON strings: escape embedded quotes and newlines correctly so the object parses.
+
+Output ONLY the JSON object. No fences, no prose.
diff --git a/apps/cli/ai/skills/site-generator/generators/companion-plugin.md b/apps/cli/ai/skills/site-generator/generators/companion-plugin.md
new file mode 100644
index 0000000000..7a58414214
--- /dev/null
+++ b/apps/cli/ai/skills/site-generator/generators/companion-plugin.md
@@ -0,0 +1,188 @@
+# Companion plugin main file generator
+
+You generate the single main PHP file of the site's companion plugin. This file owns ALL behavior for the site: it registers custom post types, taxonomies, and post meta; it registers REST API routes that receive front-end form submissions; and it registers every custom Gutenberg block. It is the only PHP file in the plugin that the tool asks you to write — the per-block files (`block.json`, `view.js`, `editor.js`, `render.php`) are generated separately and live under `blocks/<block-slug>/` next to this file.
+
+This is a PLUGIN, not a theme. The theme that ships alongside it is pure presentation and registers none of this. Keep the line clean: behavior lives here, never in the theme; presentation lives in the theme, never here. Do not enqueue front-end CSS, do not register block templates or template parts, do not touch `theme.json`, do not seed content. Content (pages, posts, CPT entries, sample submissions) is seeded into the live WordPress database by a separate step — this file must contain NO content-seeding code at all: no `wp_insert_post`, `wp_insert_term`, `wp_set_object_terms`, or `set_post_format` calls except the single `wp_insert_post` inside a form-submission REST callback. There is no activation seeding routine; do NOT register `register_activation_hook` or `after_switch_theme` callbacks to seed anything.
+
+## What you receive
+
+After these instructions the tool appends the site spec JSON and the chosen design direction, followed by `manifest.companionPlugin`, which is your authoritative build order:
+
+- `slug` — the plugin slug, always `<themeSlug>-functionality`. Use it as the plugin's text domain and as the base for an underscore-prefixed function/hook namespace (the `<themeSlug>` part with hyphens converted to underscores, e.g. theme `nonnas-trattoria` → prefix `nonnas`).
+- `name` — the human-readable plugin name for the header docblock.
+- `postTypes` — array of `{ "slug", "name", "fields": [{ "key", "type" }] }`. `slug` is the registered post type (already ≤20 chars). `name` is the plural collection label. Each `field` is a structured atom persisted as post meta; `type` is one of `string|number|boolean`.
+- `restRoutes` — array of `{ "path", "purpose" }`. `path` is the full namespaced route (e.g. `/nonnas/v1/reservations`); split it into the REST namespace (`nonnas/v1`) and the route (`/reservations`) when you call `register_rest_route`.
+- `blocks` — array of `{ "slug", "title", "purpose" }`. Register each one from `blocks/<slug>/`. The `purpose` tells you whether a block is form-backed and, if so, which post type slug it stores submissions in and which REST route it POSTs to — honor that contract so the block, route, and post type agree at runtime.
+
+Produce exactly the registrations these arrays call for. Do not invent post types, routes, meta keys, or blocks the manifest did not list, and do not rename anything. If `postTypes`, `restRoutes`, or `blocks` is empty, simply omit that section.
+
+## File-level docblock and bootstrap
+
+Open with one `<?php` tag at the top of the file and never close it. Immediately follow with the WordPress plugin header docblock. The tool injects the real `Plugin Name`, slug, and text domain values; emit the full header structure using the manifest's `name` and `slug`:
+
+```php
+/**
+ * Plugin Name:       <manifest.name>
+ * Description:       Behavior for the <theme name> site: custom content types, REST endpoints, and blocks.
+ * Version:           1.0.0
+ * Requires at least: 6.5
+ * Requires PHP:      8.0
+ * Text Domain:       <manifest.slug>
+ */
+```
+
+Directly below the docblock, guard against direct access:
+
+```php
+defined( 'ABSPATH' ) || exit;
+```
+
+Use `declare( strict_types=1 );` is NOT valid after the header docblock for a WordPress plugin file (the docblock and `Plugin Name` line must come first), so do not add it. Instead, type every function signature explicitly as described in the code-quality rules below.
+
+## Namespacing
+
+Every function name, hook tag, option key, transient key, and REST namespace must be prefixed with the underscore-form plugin prefix derived from `<themeSlug>` (hyphens → underscores). For a theme `riverside-dental` the prefix is `riverside`; functions become `riverside_register_post_types()`, the REST namespace becomes `riverside/v1`, and so on. This prevents collisions with WordPress core and other plugins. Meta keys and the field keys exposed over REST stay UNprefixed (`price`, `allergens`, `booking_date`) — the post type slug they hang off already supplies scoping, and the front-end block reads them by their bare names.
+
+## Custom post types, taxonomies, and meta
+
+Register all post types on the `init` hook at default priority, each as its own `register_post_type` call (group them in one `init` callback or split per type — either is fine, but keep registration on `init`). Choose arguments by post-type kind:
+
+- **Content post types** (public, browsable collections — menu items, team members, projects, services, events): `'public' => true`, `'has_archive' => true`, `'show_in_rest' => true`, `'menu_icon'` a sensible `dashicons-*`, and `'supports' => array( 'title', 'editor', 'custom-fields', 'thumbnail' )`. These get rendered by the theme's `archive-<slug>` / `single-<slug>` templates and queried by page query loops, so their archive and REST visibility must be on.
+- **Submission post types** (admin-only form data — reservations, contacts, RSVPs, reviews): `'public' => false`, `'show_ui' => true`, `'show_in_menu' => true`, `'show_in_rest' => true`, and `'supports' => array( 'title', 'editor', 'custom-fields' )`. The owner manages these in wp-admin; they are not public single pages.
+
+Decide kind from the manifest: a post type that a page query loop renders is content; a post type that a form-backed block writes to is a submission type. The `purpose` strings on `blocks` reveal which post types are submission targets.
+
+For every entry in a post type's `fields`, emit a matching `register_post_meta` call in the same `init` callback, immediately after that type's `register_post_type`. `show_in_rest => true` is mandatory — it is what lets block bindings and the REST layer read the value:
+
+```php
+register_post_meta( '<cpt-slug>', '<field-key>', array(
+    'type'              => '<string|number|integer|boolean>',
+    'single'           => true,
+    'show_in_rest'      => true,
+    'auth_callback'     => static function (): bool { return current_user_can( 'edit_posts' ); },
+    'sanitize_callback' => '<sanitiser>',
+) );
+```
+
+Pick the meta `type` and `sanitize_callback` from the field's declared `type`:
+
+| Manifest field `type` | meta `type` | `sanitize_callback`                 |
+|-----------------------|-------------|-------------------------------------|
+| `string`              | `string`    | `'sanitize_text_field'`             |
+| `number`              | `number`    | `static fn ( $v ): float => (float) $v` |
+| `boolean`             | `boolean`   | `'rest_sanitize_boolean'`           |
+
+For an integer-shaped string field use `'absint'`. **Never pass a PHP internal function name (`floatval`, `intval`, `boolval`, `trim`, `strtolower`, …) as a string callback to `register_post_meta`.** WordPress wires `sanitize_callback` into the `sanitize_{type}_meta_{key}` filter and invokes it with four arguments; PHP 8 makes extra arguments fatal for internal functions, so the plugin hard-fatals the first time that meta is updated. WordPress userland sanitisers (`sanitize_text_field`, `absint`, `rest_sanitize_boolean`) tolerate the extra args; for anything else wrap it in a single-argument closure as shown for `number`.
+
+If the manifest implies a taxonomy (a content type that needs categorization — cuisines, project tags, service categories), register it on `init` with `register_taxonomy`, `'show_in_rest' => true`, and attach it to its post type. Only register taxonomies the spec or manifest actually calls for.
+
+After registering post types that declare `has_archive`, flush rewrite rules exactly once, guarded by an option so it does not run on every request:
+
+```php
+if ( ! get_option( '<prefix>_rewrite_flushed' ) ) {
+    flush_rewrite_rules();
+    update_option( '<prefix>_rewrite_flushed', true, '', false );
+}
+```
+
+## REST routes
+
+Register every route from `restRoutes` on the `rest_api_init` hook with `register_rest_route`. Each form-submission route is a `POST` route in the theme's namespace whose callback inserts one submission post. The `args` map is the validation gate: list every form field the paired block submits, with `required`, `type`, and a `sanitize_callback`, so WordPress rejects malformed requests before your callback runs. The `args` keys, the `meta_input` keys in `wp_insert_post`, and the field keys the block POSTs MUST be identical — a mismatch makes every submission fail with "Missing parameter(s)".
+
+```php
+add_action( 'rest_api_init', static function (): void {
+    register_rest_route(
+        '<prefix>/v1',
+        '/<route>',
+        array(
+            'methods'             => WP_REST_Server::CREATABLE,
+            'callback'            => '<prefix>_handle_<route>',
+            'permission_callback' => '__return_true',
+            'args'                => array(
+                'name'  => array( 'type' => 'string', 'required' => true, 'sanitize_callback' => 'sanitize_text_field' ),
+                'email' => array( 'type' => 'string', 'required' => true, 'sanitize_callback' => 'sanitize_email' ),
+                // ...one entry per form field, keys matching the block exactly...
+            ),
+        )
+    );
+} );
+```
+
+`permission_callback => '__return_true'` is acceptable ONLY for a public, anonymous form-submission endpoint, and ONLY because it is paired with strict `args` validation on every field plus the REST nonce the block sends in its `X-WP-Nonce` header (WordPress verifies that nonce against the cookie session for same-origin requests). For any route that reads, edits, or lists data, or that should be restricted, use a real `permission_callback` closure that verifies the nonce and checks a capability, returning a `WP_Error` (never bare `false`) on failure:
+
+```php
+'permission_callback' => static function ( WP_REST_Request $request ): bool|WP_Error {
+    if ( ! wp_verify_nonce( $request->get_header( 'X-WP-Nonce' ), 'wp_rest' ) ) {
+        return new WP_Error( 'rest_forbidden', __( 'Nonce verification failed.', '<text-domain>' ), array( 'status' => 401 ) );
+    }
+    if ( ! current_user_can( 'edit_posts' ) ) {
+        return new WP_Error( 'rest_forbidden', __( 'You cannot do this.', '<text-domain>' ), array( 'status' => 403 ) );
+    }
+    return true;
+},
+```
+
+The submission callback reads validated params off the request, performs any extra business validation (e.g. `is_email`), inserts one post of the submission type with the fields in `meta_input`, and returns a shaped response — never the raw post array. Title the submission with a human-readable label plus a timestamp so the wp-admin list is legible:
+
+```php
+function <prefix>_handle_<route>( WP_REST_Request $request ): WP_REST_Response|WP_Error {
+    $email = $request->get_param( 'email' );
+    if ( ! is_email( $email ) ) {
+        return new WP_Error( 'rest_invalid_param', __( 'Please provide a valid email address.', '<text-domain>' ), array( 'status' => 400 ) );
+    }
+
+    $post_id = wp_insert_post(
+        array(
+            'post_type'    => '<submission-cpt-slug>',
+            'post_status'  => 'publish',
+            'post_title'   => sanitize_text_field( $request->get_param( 'name' ) ) . ' — ' . current_time( 'Y-m-d H:i' ),
+            'post_content' => '',
+            'meta_input'   => array(
+                'email' => $email,
+                // ...one entry per declared field, keys matching args exactly...
+            ),
+        ),
+        true
+    );
+
+    if ( is_wp_error( $post_id ) ) {
+        return new WP_Error( 'rest_insert_failed', __( 'Could not save your submission.', '<text-domain>' ), array( 'status' => 500 ) );
+    }
+
+    return new WP_REST_Response( array( 'ok' => true, 'id' => $post_id ), 201 );
+}
+```
+
+Use `WP_REST_Server::CREATABLE` for POST and `WP_REST_Server::READABLE` for GET. Drive the `args` map and the `meta_input` keys straight from the submission post type's `fields` — they are the single source of truth.
+
+## Block registration
+
+Register every block in `blocks[]` from its source directory via `register_block_type` on `init`. These are build-less blocks: each `blocks/<slug>/` directory holds a `block.json` (generated separately) that points at plain `view.js` / `editor.js` files registered server-side — there is NO build step, NO `build/` subdirectory, and NO `@wordpress/scripts` pipeline. Point `register_block_type` at the source directory itself:
+
+```php
+add_action( 'init', static function (): void {
+    $blocks = array( '<block-slug-1>', '<block-slug-2>' );
+    foreach ( $blocks as $slug ) {
+        register_block_type( __DIR__ . '/blocks/' . $slug );
+    }
+} );
+```
+
+Do not enqueue block scripts or styles manually — `block.json` declares them and WordPress loads them. Do not register block names from this file (the names live in each `block.json`); you only register the block types by directory. The blocks use plain JavaScript and standard DOM APIs only — never the Interactivity API — but that is enforced in the per-block files, not here.
+
+## Code-quality rules (mandatory)
+
+- **Escape every output** with the context-appropriate function (`esc_html`, `esc_attr`, `esc_url`, `wp_kses_post`); escape translated strings (`esc_html__`). Never echo a raw variable.
+- **Sanitize every input** with a WordPress sanitiser keyed to the data (`sanitize_text_field`, `sanitize_email`, `sanitize_textarea_field`, `esc_url_raw`, `absint`). Never trust `$_POST`/`$_GET`/`$_REQUEST` or unvalidated REST params.
+- **Every write endpoint verifies a nonce AND checks a capability** in the same callback, except the public anonymous form-submission endpoint, which substitutes strict `args` validation plus the REST nonce sent by the block. Return `WP_Error` with an HTTP `status`, never bare `false`.
+- **Use `$wpdb->prepare`** for any direct SQL (you should not need raw SQL here — use the post/meta APIs).
+- **No autoloaded large options** — pass `false` as the autoload argument to `add_option`/`update_option` for anything over a few hundred bytes.
+- **Bound every `WP_Query`** with an explicit `posts_per_page`; never `-1` on data that can grow.
+- **Type every function signature** — parameter types and a return type (`void` when nothing is returned, `?Type` for nullable). Add a PHPDoc array-shape annotation wherever you pass or return an `array`. Avoid `mixed`.
+- Make all user-facing strings translatable with the plugin text domain.
+
+## Output
+
+Output a single complete PHP file: one `<?php` tag at the top, the header docblock, the `ABSPATH` guard, then the registrations in this order — post types + meta (and any taxonomies), REST routes, block registration. The example snippets above use markdown fences for readability in THIS prompt only; your output must contain no fences.
+
+Output ONLY the raw file content — no markdown code fences, no commentary, no explanation.
diff --git a/apps/cli/ai/skills/site-generator/generators/design-direction.md b/apps/cli/ai/skills/site-generator/generators/design-direction.md
new file mode 100644
index 0000000000..4998899308
--- /dev/null
+++ b/apps/cli/ai/skills/site-generator/generators/design-direction.md
@@ -0,0 +1,111 @@
+You are a world-class web designer. Produce ONE bold, topic-grounded visual design direction for a website, rendered as a self-contained first-fold HTML document — the header plus the hero section only (the first viewport). This is not a full page: stop at the bottom of the hero. The first fold establishes the aesthetic contract that the rest of the theme will be built against, so it must feel unmistakably purpose-built for this exact site.
+
+The site spec JSON, the chosen design direction (a title and a brief), and a per-call task line are appended after these instructions. Read all of them before composing. The direction's title and brief define the mood, palette intent, typography character, and hero idea you must commit to — honor them literally and push them as far as they will go.
+
+## Absolute rules
+
+- NO EMOJIS anywhere — not in headings, paragraphs, button text, navigation, or any visible text. If an icon is needed, use inline SVG.
+- NO decorative HTML or CSS comments. The only comments permitted are none — this is a plain HTML document, not WordPress block markup, so emit no comments at all.
+- A single self-contained `<!doctype html>` document. All styling lives in one inline `<style>` block in the `<head>`.
+- Google Fonts are loaded via a `<link>` in the `<head>`. No other external dependencies, no CDN frameworks, no external image URLs other than the placeholder described below.
+- Header navigation plus hero ONLY. No content sections, no feature grids, no testimonials, no pricing, no footer, nothing below the hero.
+
+## Pick the aesthetic — ground it in the topic
+
+Think like a specialist designer hired for exactly this brief. Derive every choice from the site's topic, industry, culture, and audience — the materials, spaces, cultural references, and design conventions of its field. A Georgian restaurant evokes Caucasus earth tones and ornate pattern; a photojournalist portfolio evokes high-contrast editorial layouts and documentary rawness; a precision-tools manufacturer evokes engineered grids and machined metal. A visitor should be able to guess what the site is about from the visual design alone, before reading a single word. If the design could belong to any random site, it is too generic — rework it.
+
+Commit fully to the assigned direction. Do not hedge toward a safe middle. Match implementation effort to the vision: maximalist directions need elaborate, layered CSS; minimalist directions need precision and restraint.
+
+Avoid AI-generic output:
+- Generic fonts: never Inter, Roboto, Arial, Open Sans, Helvetica, or system font stacks. Choose distinctive, characterful typefaces and pair a display face with a refined body face.
+- Generic palettes: no purple-gradient-on-white, no safe blue-and-gray corporate scheme, no arbitrary rainbow accents. Commit to a cohesive palette — dominant colors with sharp accents, not a timid even distribution.
+- Generic layout: do NOT default to "headline left, image right". Choose a hero composition that serves the direction.
+
+## Layout mode
+
+Read `layoutMode` from the site spec and honor it literally — it decides the shape of the page, not just the hero. If it is missing, treat it as `vertical-stack`. The first fold is the user's first chance to confirm the chrome they asked for survived. Choose the scaffold accordingly.
+
+### vertical-stack (default)
+Full-width `<header>` strip on top, full-width hero `<section>` below it. Constrain content to the width variables below; full-bleed background layers may span the viewport, but text stays within `--wide-size`.
+
+### landing-page (one-pager, sticky nav, anchor sections)
+Conventional header/main chrome, but nav items use anchor links (`href="#features"`, `href="#pricing"`, etc.) so the downstream build knows this is a one-pager. The header is `position: sticky; top: 0` with a subtle backdrop blur, and the hero fills `100vh` exactly. Set `html { scroll-behavior: smooth }`.
+
+### sidebar-left / sidebar-right
+A two-column frame: a sticky sidebar carries the wordmark and primary navigation; the header and hero live inside a scrolling main column. Use CSS Grid on the body and `position: sticky` on the sidebar grid item — never `body { display: flex }` and never `position: fixed` on the sidebar (both break the downstream WordPress layout even if the preview looks fine in isolation).
+
+```
+body { margin: 0; display: grid; grid-template-columns: var(--sidebar-width) 1fr; min-height: 100vh; }
+.site-sidebar { grid-column: 1; grid-row: 1; position: sticky; top: 0; align-self: start; height: 100vh; overflow-y: auto; }
+.main-content-area { grid-column: 2; grid-row: 1; min-width: 0; }
+```
+
+Both items need explicit `grid-row: 1`, or sidebar-right pushes the main column into a phantom row 2 and leaves a viewport-tall empty band. For sidebar-right, keep the sidebar element FIRST in source order and swap the visual column via CSS (`grid-template-columns: 1fr var(--sidebar-width)` plus column reassignment) — markup order stays invariant. In sidebar mode the width variables constrain the main column, not the viewport; "full-bleed" fills the main column, not the whole page. The header inside the main column is a thin utility bar (search, account, cart) or omitted — primary nav belongs in the sidebar. Compose a hero that reads well in the narrower column: typographic editorial heroes or asymmetric framed images work better here than full-bleed marketing heroes.
+
+### dual-sidebar (documentation chrome)
+Three-column grid: sticky left sidebar (wordmark + primary nav), scrolling middle column, sticky right rail (a small uppercase "On this page" label, 4–6 placeholder anchor entries, a hairline rule, then 2–3 mono-style metadata rows such as Version, Updated, License). All three columns share `grid-row: 1`. Documentation themes often have no marketing hero — the main column may open with a breadcrumb, an H1, and body lede instead.
+
+### magazine-grid (editorial homepage, no marketing hero)
+Conventional chrome, but the first fold is the post grid, not a hero. Compose a thin masthead (wordmark + 4–6 category links + hairline divider), then a feature row with one large lead story and 2–3 stacked secondary stories. The hero image placeholder is the lead story's image. Bylines render in monospace. Do not compose a headline-plus-CTA hero before the grid.
+
+### canvas-floating-chrome (full-bleed gallery, no header band)
+The hero image fills the entire viewport edge to edge. The only chrome is two small `position: fixed` floating modules: a wordmark in one corner and a menu link in another. Use `mix-blend-mode: difference` (or a backdrop blur) on the floating chrome so it stays legible over any image. No header band, no max-width on the hero.
+
+## Width contract (matches the downstream WordPress theme)
+
+```
+:root { --content-size: 800px; --wide-size: 1280px; }
+body { margin: 0; padding: 0; }
+.content-width { max-width: var(--content-size); margin: 0 auto; padding-left: 1rem; padding-right: 1rem; }
+.wide-width { max-width: var(--wide-size); margin: 0 auto; padding-left: 1rem; padding-right: 1rem; }
+```
+
+Header navigation and the hero composition use `.wide-width` (1280px). Body and paragraph text use `.content-width` (800px). Background colors and gradients may span the full viewport, but the actual text and content stay constrained. Use `min-height: 100vh` on the hero so it fills the viewport.
+
+For side-by-side hero layouts, use fractional or percentage column widths (`1fr 1fr`, `45% 55%`, `1fr 1.5fr`) — never fixed pixel widths that could sum past 1280px and force a stack. Keep headlines to 2–6 words per line and subtext to 1–2 short sentences so the composition fits.
+
+## Palette via CSS custom properties
+
+Declare the palette as CSS custom properties on `:root` (background, foreground, primary, accent, surface, plus whatever the direction needs) using specific hex values that realize the assigned direction. Reference them throughout. This makes the palette legible to the downstream theme.json build. Whenever a region sets a background color, ensure its text color is set in the same place so text is never invisible against its background.
+
+## Visual richness from CSS
+
+Beyond the single hero image, build atmosphere and depth with CSS only: linear / radial / conic gradients, bold color blocks, large distinctive display typography with deliberate weight and size contrast, CSS pattern backgrounds (stripes, dots, grids), box-shadow / text-shadow / drop-shadow for dimension, decorative borders and frames, `::before` / `::after` pseudo-elements, and layered semi-transparent overlays. Do not use any `background-image: url(...)` pointing at an external resource. The ONLY image in the document is the hero placeholder described next.
+
+## Hero image placeholder
+
+Include exactly ONE `<img>` for the hero (the lead-story image in magazine-grid; the full-bleed image in canvas-floating-chrome). The image is generated later from your alt text, so the alt must follow the AI_IMAGE convention exactly:
+
+```
+alt="AI_IMAGE: <description> | <style> | <aspect>"
+```
+
+- `<description>`: 1–3 specific sentences about composition, colors, mood, and concrete subject matter, directly relevant to this site's topic and matched to the chosen direction.
+- `<style>`: one of `photorealistic`, `digital-art`, `illustration`, `minimalist`, `flat-design`, `3d-render`, `abstract`, `watercolor`.
+- `<aspect>`: one of `landscape` (16:9, heroes and banners and full-bleed backgrounds), `portrait` (9:16, tall side-aligned images), `square` (1:1, centered or framed images). It must agree with how the image is sized in the layout.
+
+For the `src`, use a placeholder so the image can be generated later without a broken-image icon showing in the preview: either a transparent or solid-color inline data URI (for example a `data:image/svg+xml` solid rectangle tinted to a palette color), or render the image area as a CSS color block behind the `<img>` with the `<img>` itself transparent. The hero image must read as a prominent, intentional visual element — give it a CSS gradient or solid color fallback behind it and use `object-fit: cover` so it holds its frame.
+
+Vary the hero composition to fit the direction — full-bleed background with overlaid text, left-aligned image with text right, centered stack, asymmetric image breaking the grid, partial 60–70% coverage, split diagonal, or a framed/inset image. Do not reach for "image on the right" by default.
+
+## Motion
+
+Add 1–2 subtle ambient CSS animations (a slow gradient drift, a gentle floating element, a soft shimmer or parallax-feeling shift — chosen to suit the direction's mood) plus one entrance animation on the hero's primary content (a fade-and-rise on the headline and supporting text). Animation is CSS only — no JavaScript in this document. The CSS defines the final, visible resting state; animations move elements into that state. Wrap every animation so motion is removed under reduced-motion preference:
+
+```
+@media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after { animation: none !important; transition: none !important; }
+}
+```
+
+Keep motion tasteful and brief — it should feel like craftsmanship, not a screensaver.
+
+## Content
+
+Fill the header and hero with realistic placeholder copy appropriate to this specific site (a believable wordmark, real-sounding navigation labels, a concrete topic-specific headline, a supporting line, and a primary call-to-action label). No lorem ipsum, no emojis. Give classes self-explanatory names (`.site-header`, `.hero`, `.hero-headline`, `.hero-cta`, etc.) so a later model can read the design intent and rebuild it as a block theme.
+
+## Output
+
+Emit a single complete document: `<!doctype html>`, `<html lang="en">`, a `<head>` containing the charset and viewport meta tags, the Google Fonts `<link>`, and the inline `<style>`; then a `<body>` containing only the header and the hero with the single AI_IMAGE placeholder. No code fences, no XML wrapper tags, no preamble, no trailing notes.
+
+Output ONLY the raw file content — no markdown code fences, no commentary, no explanation.
diff --git a/apps/cli/ai/skills/site-generator/generators/manifest.md b/apps/cli/ai/skills/site-generator/generators/manifest.md
new file mode 100644
index 0000000000..caeaba595c
--- /dev/null
+++ b/apps/cli/ai/skills/site-generator/generators/manifest.md
@@ -0,0 +1,138 @@
+# Manifest Planner
+
+You plan the complete file manifest for a generated WordPress site and decide whether the site needs a companion plugin. This generator produces **only a JSON plan** — it does not write any theme or plugin files. Downstream generators consume your JSON to write real files to disk and to seed content into the live WordPress database.
+
+## The two-package model you are planning for
+
+A generated site is always two packages:
+
+1. **A pure presentation theme** at `<site>/wp-content/themes/<themeSlug>/`. It holds `theme.json`, `style.css`, `templates/`, `parts/`, `patterns/`, and `assets/`. Fonts are declared in `theme.json` via `settings.typography.fontFamilies` with `fontFace` entries — never enqueued from PHP. `functions.php` is minimal: it enqueues `style.css` on the front end and calls `add_editor_style`. The theme registers **no** custom post types, **no** REST routes, **no** blocks, and seeds **no** content.
+
+2. **An optional companion plugin** at `<site>/wp-content/plugins/<themeSlug>-functionality/`. It holds **all** behavior: custom post types + taxonomies + post meta, REST API routes, and custom build-less Gutenberg blocks (plain-JS `view.js`/`editor.js` registered server-side with `register_block_type`). The companion plugin exists only when the site actually needs behavior.
+
+Your manifest decides what goes in each package and what content gets seeded into the running database.
+
+## Inputs
+
+You receive the site spec (site type, audience, tone, layout requirements, content mode) plus the user's original request. Read both before planning.
+
+## What to decide
+
+### themeSlug and themeName
+
+- `themeSlug`: kebab-case, derived from the business or project name (`nonnas-trattoria`, `atlas-ventures`, `riverside-dental`). Lowercase letters, digits, hyphens only; must start with a letter.
+- `themeName`: human-readable display name (`Nonna's Trattoria`).
+
+The companion plugin slug is always `<themeSlug>-functionality` and its name is always `<themeName> Functionality`. Keep `themeSlug` short enough that custom post type slugs derived from it stay within WordPress's 20-character `register_post_type` limit.
+
+### layoutMode
+
+Pick the structural skeleton that matches the site's purpose. One of:
+
+- `vertical-stack` — standard full-width sections stacked top to bottom. The default for most marketing and brochure sites.
+- `sidebar-left` / `sidebar-right` — a persistent sidebar column beside the main content. Good for documentation, editorial, or app-like layouts.
+- `dual-sidebar` — content flanked by two rails.
+- `landing-page` — a single long-scroll page with no traditional multi-page navigation; conversion-focused.
+- `magazine-grid` — a grid-driven editorial front with multiple entry points.
+- `canvas-floating-chrome` — an immersive full-bleed canvas with floating header/footer chrome over the content.
+
+### contentMode
+
+Decides the page and template inventory. One of:
+
+- `homepage-and-pages` (default) — a designed homepage plus a handful of static pages. Templates always include `index` and `page`. The homepage is a real `home` page rendered through the `page` template's `wp:post-content`; there is no `front-page` template.
+- `blog-first` — the site is primarily a stream of posts. Usually drop the `home` page in favor of the posts index; always include an `about` page. Templates must include `archive` and `single` for native posts. Do not model "articles" / "blog posts" / "essays" as a custom post type — those are native WordPress posts.
+- `index-only` — the user explicitly opted out of a marketing homepage; the site is the posts index. Do **not** include a `home` page. Templates must include `index`, `archive`, and `single`. The `index` template carries a designed query loop instead of `wp:post-content`.
+
+### parts
+
+The template parts the theme needs. Always include `header` and `footer`. Add others only when the layout calls for them (e.g. a `sidebar` part for sidebar layouts).
+
+### templates
+
+Block templates at `templates/<name>.html`. Always include `index` and `page`. Add `single` and `archive` when the site has a blog (`blog-first` / `index-only`) or a public content post type. For every **public** custom post type the companion plugin registers, add `archive-<cpt-slug>` and `single-<cpt-slug>` so entries render the moment the theme activates. Templates are thin shells (header part, main wrapper, content, footer part); the rich homepage composition lives in the `home` page, not in a template.
+
+### pages
+
+Each page is `{ "slug": "<kebab>", "title": "<display>", "brief": "<one paragraph>" }`.
+
+- **Always include a `home` page unless `contentMode` is `index-only`.**
+- **If the user explicitly names pages, include every one of them.** Never silently drop a named page.
+- When the user is not specific, infer the pages natural to the business type:
+    - Restaurants / cafés / bakeries: home, menu, about, contact, reservations
+    - Portfolio / agency / studio: home, work, about, services, contact
+    - Business / corporate / professional services: home, about, services, team, contact
+    - Shop / retail: home, products, about, contact
+    - Blog / magazine: home (optional), about, contact
+- A typical site has 3–6 pages.
+- The `brief` is a one-paragraph cinematic composition brief in narrative prose — the section composition end to end: hero, intermediate sections (each named and anchored to this business: an asymmetric about-pitch, a three-card services grid, a full-bleed quote band, an edge-to-edge gallery strip), and the closing CTA. Be specific about images, alignment, and where typography versus imagery carries the weight. The homepage gets the richest treatment (5–8 sections); an About page is editorial (3–5 sections); a Contact page is functional (2–3 sections, composed around the form). Anchor every brief to the actual domain and the concrete items the user mentioned — a generic brief produces a generic page. Give each page at least one distinctive section the others do not have; never compose two pages identically.
+- When a page's body is fundamentally a list of entries from a content post type (a menu page listing menu items, a team page listing members, a portfolio listing projects), say so in the brief and note it should render via a `wp:query` loop against that post type rather than hardcoded entries. This implies a content post type in the companion plugin.
+
+### patterns
+
+Reusable block patterns for `patterns/`. Most sites need none — leave `[]` unless a section genuinely repeats across multiple pages and benefits from being a named pattern.
+
+### companionPlugin
+
+`companionPlugin.needed` is `true` **only** when the site needs behavior:
+
+- **Custom post types** — a repeatable, browsable collection the owner will add to without editing pages: menu items, team members, portfolio projects, testimonials, services, events, locations, case studies. Rule of thumb: emit a content post type when the user describes "a repeatable list of things."
+- **Forms** — any UI that persists user-submitted data: contact form, reservation/booking, RSVP, review submission, newsletter signup. A form needs a custom block to collect it, a REST route to receive it, and a post type to store submissions.
+- **Interactive / stateful blocks** — countdown timer, calculator, pricing configurator, before/after slider, multi-step quiz, filterable gallery: anything needing JavaScript state not achievable with core blocks. These blocks are build-less plain JS (`wp.blocks.registerBlockType` via `wp.element.createElement`, registered server-side with `register_block_type`) — never JSX, never a build step, never the Interactivity API.
+
+A plain brochure site — hero, about, services grid, testimonials, FAQ, CTA, contact info — needs **none** of this; those are all compositions of core blocks (`wp:cover`, `wp:columns`, `wp:group`, `wp:media-text`, `wp:quote`, `wp:buttons`, `wp:details`). For a brochure site set `"companionPlugin": { "needed": false }` and omit the inner arrays. **Do not invent a post type for a one-off static section** (a "three pillars" grid on the homepage is just core blocks).
+
+When `needed` is `true`, fill:
+
+- `slug`: always `<themeSlug>-functionality`.
+- `name`: always `<themeName> Functionality`.
+- `postTypes`: each `{ "slug": "", "name": "", "fields": [{ "key": "", "type": "string|number|boolean" }] }`. The post type `slug` MUST be ≤20 characters total — derive a short underscore-joined slug from the theme (e.g. `nonnas_menu_item`); prefer short nouns over noun-phrases. `name` is the plural human-readable collection name. `fields` are the structured atoms persisted as post meta (a menu item's `price` and `allergens`, a team member's `role`, a project's `client` and `year`); reserve the post body for prose and the featured image. For a form's submission post type, the `fields` are the form's field set (the single source of truth the block, the REST route, and the meta registration all share) — pick semantic snake_case keys (`booking_date`, `party_size`), never name a field `title`.
+- `restRoutes`: each `{ "path": "/namespace/v1/...", "purpose": "" }`. Namespace the path under the theme (e.g. `/nonnas/v1/reservations`). Emit one route per form submission endpoint.
+- `blocks`: each `{ "slug": "", "title": "", "purpose": "" }`. The `purpose` states what the block does, where it appears, and — for a form-backed block — which submission post type slug it POSTs to and via which REST route (this naming contract keeps the block, route, and post type aligned at runtime). Do **not** list a block for ordinary content sections.
+
+### seed
+
+The content seeded into the live WordPress database (never baked into the theme as files). Each entry is `{ "type": "page|post|<cpt>", "slug": "", "title": "" }`.
+
+- One `page` seed entry for every page in `pages[]` (so the homepage and static pages exist as real published content).
+- For `blog-first` / `index-only`, seed a handful of `post` entries.
+- For each content post type, seed 3–6 realistic entries with distinctive, domain-anchored titles. Invent plausible names; never reference real brands or real people. For a submission post type, seed 2–3 plausible sample submissions so wp-admin shows how a real submission looks.
+- Every seed slug is unique within its type and URL-safe (lowercase, hyphens).
+
+## Output
+
+Output **only** a single JSON object — no code fences, no prose before or after — with exactly this shape:
+
+```json
+{
+  "themeSlug": "<kebab>",
+  "themeName": "<display>",
+  "layoutMode": "vertical-stack|sidebar-left|sidebar-right|dual-sidebar|landing-page|magazine-grid|canvas-floating-chrome",
+  "contentMode": "homepage-and-pages|blog-first|index-only",
+  "parts": ["header", "footer"],
+  "templates": ["index", "page"],
+  "pages": [
+    { "slug": "home", "title": "Home", "brief": "one-paragraph composition brief" }
+  ],
+  "patterns": [],
+  "companionPlugin": {
+    "needed": true,
+    "slug": "<themeSlug>-functionality",
+    "name": "<display> Functionality",
+    "postTypes": [
+      { "slug": "", "name": "", "fields": [{ "key": "", "type": "string|number|boolean" }] }
+    ],
+    "restRoutes": [
+      { "path": "/namespace/v1/...", "purpose": "" }
+    ],
+    "blocks": [
+      { "slug": "", "title": "", "purpose": "" }
+    ]
+  },
+  "seed": [
+    { "type": "page|post|<cpt>", "slug": "", "title": "" }
+  ]
+}
+```
+
+Output ONLY the JSON object.
diff --git a/apps/cli/ai/skills/site-generator/generators/page-content.md b/apps/cli/ai/skills/site-generator/generators/page-content.md
new file mode 100644
index 0000000000..e187bcdfff
--- /dev/null
+++ b/apps/cli/ai/skills/site-generator/generators/page-content.md
@@ -0,0 +1,88 @@
+You are generating the block-markup BODY for one content page of a WordPress site.
+
+The site's design foundation is already established. The site spec JSON and the chosen design direction are appended after these instructions; a task line at the end gives the page slug, title, and a composition brief. Your output is the post_content body for that single page. This content will be seeded into the live WordPress database via WP-CLI — it is NOT a theme file, and it must NOT be wrapped in any XML, sentinel, or metadata header. Emit raw block-markup HTML and nothing else.
+
+Match the established design exactly. Use the same color slugs, typography, spacing presets, and class conventions the design direction and theme.json define. Do not invent a parallel palette or new font sizes. Let the site spec anchor the tone, the business domain, and any specific details the user mentioned — if the user named real services, products, locations, or language, use them. Do not substitute generic SaaS or consulting filler when the domain is concrete.
+
+## What to produce
+
+Build the page body as 4-7 well-composed top-level sections, in the order the composition brief implies. Each section is a self-contained band with its own rhythm. Do not compose every section from the same kit — vary archetype, alignment, and what carries the weight (image, typography, color band, or whitespace) section to section. A page where every band is a centered heading-plus-paragraph reads as a template, not a designed page.
+
+Pick from this section vocabulary, calibrated to the page's role:
+- Full-bleed band: an outer `wp:group` (or `wp:cover`) with `"align":"full"` carrying a saturated background color or an edge-to-edge image.
+- Asymmetric two-column: `wp:columns` with non-50/50 widths (e.g. `"width":"40%"` / `"width":"60%"`), or `wp:media-text` with `mediaPosition` for an image-beside-text split.
+- Card / feature grid: `wp:columns` of equal `wp:column` cards, each an inner `wp:group` with its own background and padding.
+- Editorial / centered: a content-width heading and generous prose for manifesto or story sections.
+- Zigzag rows: alternating `wp:media-text` blocks that flip `mediaPosition` left/right down the page.
+- Photographic strip or quote band: a full-bleed image or a large pull-quote on a colored band.
+
+Calibrate section count to the page: a content page lands at 4-7 bands. An opening section, two to four substantive middle sections, and a closing CTA is a sound default.
+
+## Width and alignment (translate to WordPress mechanics)
+
+Express width with the `align` attribute, never with hand-rolled max-width or horizontal padding wrappers:
+- Edge-to-edge background, image strip, full-bleed CTA, full-viewport hero → outer block carries `"align":"full"`.
+- A band that extends beyond reading width but not to the viewport edge → `"align":"wide"`.
+- Reading-width prose, forms, narrow content → default content width (no `align` attribute).
+
+For a full-bleed band that holds reading-width content, use an `"align":"full"` outer group for the background, with an inner default-width (or `"align":"wide"`) group holding the text. Do not re-emit horizontal padding on the wrapper — root padding is already set in theme.json, and `align` punches through it. Re-padding double-pads the page into a narrow fallback column.
+
+## Block markup rules (apply to every section)
+
+- Prefer core blocks for all content: `wp:group`, `wp:columns`/`wp:column`, `wp:cover`, `wp:media-text`, `wp:heading`, `wp:paragraph`, `wp:image`, `wp:buttons`/`wp:button`, `wp:list`, `wp:quote`, `wp:separator`, `wp:spacer`.
+- Put custom class names ONLY on the outermost block of a section, via that block's `"className"` attribute. Never add classes to inner DOM nodes the block serializer generates.
+- A full-bleed section is an outer `wp:group` (or `wp:cover`) with `"align":"full"`.
+- Whenever a block sets `backgroundColor`, it MUST also set `textColor`. A background without a paired text color produces invisible text on the front end. This applies to every group, column, cover, and button that carries a background.
+- A `wp:cover` already darkens its content; still set the text color on the inner heading/paragraph blocks so contrast is explicit.
+- Use spacing presets (`var:preset|spacing|NN`) for padding and margins, not raw rem/px values, so the page inherits the design's rhythm.
+- No emojis anywhere. No decorative HTML comments — the only comments in your output are WordPress block delimiter comments (`<!-- wp:... -->` / `<!-- /wp:... -->`).
+
+## Imagery
+
+Every image is an `AI_IMAGE` placeholder — you do not have real image URLs. Emit a `wp:image` (or a `wp:cover` whose background is an image) with the src left empty or pointing at a placeholder, and put the generation directive in the `alt` attribute in exactly this shape:
+
+```
+alt="AI_IMAGE: short subject description | art-direction style | aspect ratio"
+```
+
+For example: `alt="AI_IMAGE: a baker pulling sourdough from a stone oven | warm documentary photography, golden hour | 3:2"`. The downstream image pipeline reads these alt placeholders, generates each asset, and rewrites the src. Make the description concrete and specific to the page's domain; make the style consistent with the design direction's mood; pick an aspect ratio that fits the layout (wide hero `16:9` or `21:9`, portrait card `3:4`, square `1:1`).
+
+## Copy
+
+Write realistic, specific copy — never lorem ipsum, never bracketed `[placeholder]` tokens. Headlines should be concrete and on-brand; body paragraphs should say something real about the business. If the spec gives you facts (offerings, hours, neighborhood, founding story), weave them in. Invent plausible, grounded detail where the spec is silent, in the domain's own register.
+
+## Internal links
+
+When the page links to another page on this site, use a relative href to that page's slug — `href="/<slug>/"` — inside a core `wp:button` or as a plain `<a>` in a `wp:paragraph`. Do not fabricate absolute URLs with a domain, and do not link to slugs that are not real pages on this site (no `/cart/`, `/account/`, `/checkout/` unless the spec lists them). A cross-page CTA looks like:
+
+```
+<!-- wp:buttons -->
+<div class="wp-block-buttons">
+    <!-- wp:button -->
+    <div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="/<page-slug>/">Button label</a></div>
+    <!-- /wp:button -->
+</div>
+<!-- /wp:buttons -->
+```
+
+Primary site navigation is NOT your concern — it lives in the header template part. Do not emit `wp:navigation` or `wp:navigation-link` in the page body.
+
+## Custom blocks and dynamic content
+
+If the page needs behavior that the site's companion plugin provides — a contact form, a reservation widget, a custom block, or a loop over a custom post type — embed the plugin's block by its slug rather than hand-rolling the markup:
+
+```
+<!-- wp:<plugin-prefix>/<block-slug> /-->
+```
+
+Use the self-closing form for a block with no inner content, or an opening/closing pair when the block wraps inner blocks. Only reference a block slug the spec actually declares for this site. If no declared block matches a feature that would need JavaScript state or form submission, fall back to a static informational core-block composition rather than inventing a slug — an invented slug renders as broken markup. To surface a collection of custom-post-type entries, use a `wp:query` loop styled with core blocks, never hand-coded entry markup, so editors can add and remove entries without touching this page.
+
+## Scroll motion (hooks only)
+
+Add the class name `reveal-on-scroll` to the outermost block of each substantive section so the companion plugin's progressive-enhancement script can reveal it on scroll. The CSS defines the final visible state and the script adds the initial hidden state, so the page is fully readable with JavaScript disabled, and the effect respects `@media (prefers-reduced-motion: reduce)`. Do not emit any animation CSS or JavaScript here — only the class-name hooks. Do not add reveal hooks to a first-position hero; it is already in view on load.
+
+## First section
+
+If this page opens with a hero against the header, place the hero block first with no top margin and no top padding on its outer block, so it sits flush beneath the header. If the design's header overlays the hero, the first block must be a full-bleed `wp:cover` (or full-bleed image) at least ~80vh tall, with the hero text pushed down by generous top padding so it clears the overlaid header.
+
+Output ONLY the raw file content — no markdown code fences, no commentary, no explanation.
diff --git a/apps/cli/ai/skills/site-generator/generators/style-css.md b/apps/cli/ai/skills/site-generator/generators/style-css.md
new file mode 100644
index 0000000000..78654da8e5
--- /dev/null
+++ b/apps/cli/ai/skills/site-generator/generators/style-css.md
@@ -0,0 +1,197 @@
+You are generating the `style.css` file for a WordPress block theme that is part of a generated site. The site is split into two packages: a pure-presentation THEME (where this file lives) and a separate companion plugin that holds all behavior (custom post types, REST routes, custom blocks). This `style.css` is THEME-side presentation only — design CSS, never behavior.
+
+Write the file to disk at `<site>/wp-content/themes/<slug>/style.css`. The site spec JSON and the chosen design direction are appended after these instructions, plus the specific task line for this call. The theme's `theme.json` has already been generated and is the single source of truth for design tokens: use its color slugs, font-family slugs, font-size slugs, and spacing slugs. Do NOT introduce new design tokens or pick colors/sizes/fonts that aren't defined there. Do NOT redefine in CSS what `theme.json` already exposes.
+
+Fonts are declared in `theme.json` via `settings.typography.fontFamilies` with `fontFace` entries — they are NOT enqueued from PHP and NOT `@import`ed here. Reference them only through the generated custom properties (e.g. `var(--wp--preset--font-family--body)`). Do not add `@font-face` rules or font CDN imports in this file.
+
+## File header
+
+`style.css` MUST start with the standard WordPress theme header comment block, in this order: Theme Name, Theme URI, Author, Author URI, Description, Version, Requires at least, Tested up to, Requires PHP, License, License URI, Text Domain, Tags. The tool injects the real Theme Name / Text Domain / slug values, but you must emit the full header structure with sensible defaults filled from the site spec (Description from the site's purpose; Tags such as `full-site-editing, block-styles, blog` chosen to match the site type; `Requires at least: 6.5`, `Tested up to: 6.7`, `Requires PHP: 7.4`, `License: GNU General Public License v2 or later`, `License URI: http://www.gnu.org/licenses/gpl-2.0.html`). Start the file literally with `/*`.
+
+## What this file is for
+
+After the header, emit focused design CSS that the block editor cannot express through `theme.json` alone. Reference tokens via CSS custom properties — `var(--wp--preset--color--primary)`, `var(--wp--preset--font-family--heading)`, `var(--wp--preset--font-size--large)`, `var(--wp--preset--spacing--40)` — never hardcoded hex/px values where a token exists. Scope:
+
+- A small `:root` block that maps the design's own semantic CSS variables onto theme.json preset variables, so the rest of the stylesheet reads cleanly (e.g. `--accent: var(--wp--preset--color--accent);`, `--rhythm: var(--wp--preset--spacing--40);`). Define only variables you actually use below.
+- Typography polish that goes beyond theme.json: heading letter-spacing and line-height refinements, balanced/pretty text-wrap on headings, optical margin tweaks, link underline styling and hover transitions.
+- Button variants and link styles tuned to the design's aesthetic.
+- Image treatments (object-fit, aspect ratios on figures, subtle border-radius if the design calls for it, duotone-free hover scale).
+- The loop/layout utility classes (below) that templates and patterns rely on.
+- Animation helpers using progressive enhancement (below).
+- Header scroll-state CSS (below).
+- A `@media (prefers-reduced-motion: reduce)` block (below).
+
+Let the design direction drive the polish: a warm/editorial direction gets generous spacing, serif-forward refinement, and slow transitions; an industrial/brutalist direction gets tight tokens, hard edges, and snappy transitions. Anchor every choice in the picked design's palette and rhythm. No emojis anywhere. No decorative comments — only short section-label comments are acceptable; never narrate.
+
+## Block-markup CSS conventions (the templates and patterns follow these — match them)
+
+Custom classNames live ONLY on the outermost block wrapper (set via the block `className` attribute), never on inner DOM. So your selectors hook the WordPress-generated outer class, e.g. `.wp-block-group.site-header`, `.wp-block-query.is-style-loop-rail`, not invented inner-element classes. Full-bleed sections are an outer `wp:group` with `align: full` (`.alignfull`). Never style by tag-stripping the structure; target the block's wrapper class plus standard `.wp-block-*` descendants.
+
+## Loop layout utilities (mandatory — emit exactly these classes)
+
+The page templates and patterns compose `wp:query` blocks in several layout shapes (rail, list, zigzag, timeline, magazine) and reference the named utility classes below. You MUST include this block in every `style.css` you generate, exactly as shown — the templates are generated in parallel and you cannot see their markup, so these hooks must always exist. Tune colors and spacing to theme.json tokens where indicated, but keep the selectors and the structural CSS as-is. Do not rename anything.
+
+```css
+/* ---------- Loop layout utilities ---------- */
+/* Wired to the wp:query blocks emitted by pages and templates. Do not rename.
+   Tune colours and spacing to theme.json tokens. */
+
+/* Horizontal scrollable rail */
+.wp-block-query.is-style-loop-rail .wp-block-post-template {
+    overflow-x: auto;
+    scroll-snap-type: x mandatory;
+    scrollbar-width: thin;
+    padding-bottom: var(--wp--preset--spacing--20);
+}
+.wp-block-query.is-style-loop-rail .wp-block-post-template > * {
+    flex: 0 0 320px;
+    scroll-snap-align: start;
+}
+
+/* Compact list with hairline row dividers */
+.wp-block-query.is-style-loop-list .wp-block-post-template > * {
+    border-bottom: 1px solid var(--wp--preset--color--border, currentColor);
+    padding-block: var(--wp--preset--spacing--30);
+}
+.wp-block-query.is-style-loop-list .wp-block-post-template > *:last-child {
+    border-bottom: 0;
+}
+
+/* Zigzag — flip the columns inside every even entry */
+.wp-block-query.is-style-loop-zigzag .wp-block-post-template > *:nth-child(even) .wp-block-columns {
+    flex-direction: row-reverse;
+}
+
+/* Timeline — vertical line with node markers per entry */
+.wp-block-query.is-style-loop-timeline .wp-block-post-template {
+    position: relative;
+    padding-inline-start: 2.5rem;
+}
+.wp-block-query.is-style-loop-timeline .wp-block-post-template::before {
+    content: '';
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: 0.5rem;
+    width: 2px;
+    background: currentColor;
+    opacity: 0.15;
+}
+.wp-block-query.is-style-loop-timeline .wp-block-post-template > * {
+    position: relative;
+}
+.wp-block-query.is-style-loop-timeline .wp-block-post-template > *::before {
+    content: '';
+    position: absolute;
+    inset-inline-start: -2.25rem;
+    inset-block-start: 0.6rem;
+    width: 1rem;
+    height: 1rem;
+    border: 2px solid currentColor;
+    border-radius: 50%;
+    background: var(--wp--preset--color--background, #fff);
+}
+
+/* Magazine — first child spans 2 columns of the grid */
+.wp-block-query.is-style-loop-magazine .wp-block-post-template > *:first-child {
+    grid-column: span 2;
+}
+@media (max-width: 600px) {
+    .wp-block-query.is-style-loop-magazine .wp-block-post-template > *:first-child {
+        grid-column: auto;
+    }
+}
+```
+
+Keep this block intact. If `--wp--preset--color--border` does not exist in this theme's palette, the `currentColor` fallback already handles it — do not delete the rule.
+
+## Background/text-color pairing (invisible-text guard)
+
+Wherever this stylesheet sets a `background` or `background-color`, it MUST also set a matching `color` so text never becomes invisible against the new surface. This mirrors the block-markup rule (any block that sets `backgroundColor` also sets `textColor`); apply it in CSS too — every surface rule pairs background and color from the same palette family, with sufficient contrast.
+
+## Animation helpers (progressive enhancement — CSS defines the FINAL visible state)
+
+Scroll and entrance animations follow progressive enhancement so the page is fully legible with JavaScript disabled and inside the block editor: CSS defines the FINAL, visible resting state, and the companion plugin's plain-JS enhancement script adds the INITIAL hidden state at runtime (e.g. by toggling a `js-anim-ready` class on `<html>` or adding per-element initial styles) and then transitions elements to the CSS-defined visible state as they enter the viewport via `IntersectionObserver`.
+
+Therefore in this file:
+
+- Define reveal targets in their VISIBLE end state: `opacity: 1`, `transform: none`, full visibility. NEVER ship `opacity: 0` as the base rule for content — that would leave sections blank if JS never runs and blank inside the editor.
+- Gate the hidden start state behind the JS-added readiness class, e.g. `.js-anim-ready .reveal-on-scroll { opacity: 0; transform: translateY(1.5rem); }` and `.js-anim-ready .reveal-on-scroll.is-visible { opacity: 1; transform: none; }`, with a `transition` on the element. Use stable hook class names (`reveal-on-scroll`, `is-visible`) that the companion plugin's enhancement script can target; these classes are applied via the block `className` attribute on outer wrappers.
+- Keep transitions tasteful and tuned to the design (duration, easing). The JS lives in the companion plugin (plain JS, standard DOM APIs, IntersectionObserver), not in the theme — do not write or reference any JS here.
+
+## Header scroll-state
+
+The header is rendered by a header template part as `<header class="wp-block-template-part">`, a direct child of `.wp-site-blocks`. Sticky/fixed positioning goes on that `.wp-block-template-part` wrapper, never on the inner group (the wrapper's height equals the inner group's height, so sticky on the inner group is visible for 0px of scroll). Choose positioning from the site spec's header behavior:
+
+- Overlay hero (header floats over a full-viewport hero): `position: fixed; top: 0; left: 0; right: 0; z-index: 100;` on `.wp-site-blocks > header.wp-block-template-part`. Do not add `padding-top` to main — the hero is intentionally full height beneath it.
+- Sticky, non-overlay: `position: sticky; top: 0; z-index: 100;` on the same wrapper.
+- Static: no positioning rule.
+
+Scrolled-state chrome: the companion plugin's enhancement script toggles `body.is-scrolled` on the frontend (it never toggles in the editor, so editor-canvas legibility is preserved). Paint the scrolled background on a `::before` pseudo-element of the header — NEVER on the header element itself — so the header does not become a containing block that would trap the mobile navigation overlay's `position: fixed; inset: 0`:
+
+```css
+.wp-site-blocks > header.wp-block-template-part::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    z-index: -1;
+    pointer-events: none;
+    transition: background 0.4s ease, backdrop-filter 0.4s ease, -webkit-backdrop-filter 0.4s ease;
+}
+body.is-scrolled .wp-site-blocks > header.wp-block-template-part::before {
+    background: var(--wp--preset--color--<contrast-slug>);
+    box-shadow: 0 1px 0 var(--wp--preset--color--<rule-slug-or-rgba>);
+}
+```
+
+Pick `<contrast-slug>` as a palette slug that separates the header from the body content scrolling beneath it — do NOT use `--wp--preset--color--background`, since that equals the body color and yields zero contrast (an invisible header). For dark-chrome/light-body designs pick the design's dominant dark surface slug; for light-chrome/dark-body designs pick the lightest near-white slug. If the header's load-time text color does not also contrast with the scrolled background, add `body.is-scrolled .site-header { color: var(--wp--preset--color--<legible-slug>); }` and a matching navigation-link color rule so the wordmark and nav stay legible. For a translucent/blur variant, use `background: color-mix(in srgb, var(--wp--preset--color--<contrast-slug>) 80%, transparent); backdrop-filter: blur(12px); -webkit-backdrop-filter: blur(12px);` on the pseudo-element. If the design specifies no scrolled background, omit both pseudo-element rules.
+
+Shrink-on-scroll (only if the spec asks for it): put the transition and the shrunk padding on the inner group's class (e.g. `.site-header`), keyed off `body.is-scrolled` — the sticky/fixed behavior stays on the `.wp-block-template-part` wrapper.
+
+Overflow ancestors break sticky: if a sticky header or element fails, ensure no ancestor (`body`, `.wp-site-blocks`, intermediate groups) has a non-`visible` overflow.
+
+## Mobile navigation overlay
+
+The mobile navigation overlay surface (`.wp-block-navigation__responsive-container.is-menu-open`) renders with raw WordPress defaults unless styled — items butted against the viewport edge. Style it to match the design: pad the open container, set the menu container gap and `align-items: flex-start`, and bump the item font size. Use spacing slugs that match the design's rhythm (tight tokens like `spacing--20`/`spacing--30` for industrial; generous like `spacing--50`/`spacing--60` for editorial):
+
+```css
+.wp-block-navigation__responsive-container.is-menu-open {
+    padding: var(--wp--preset--spacing--<container-spacing>) var(--wp--preset--spacing--<gutter-spacing>);
+}
+.wp-block-navigation__responsive-container.is-menu-open .wp-block-navigation__container {
+    gap: var(--wp--preset--spacing--<item-gap>);
+    align-items: flex-start;
+}
+.wp-block-navigation__responsive-container.is-menu-open .wp-block-navigation-item__content {
+    font-size: var(--wp--preset--font-size--large);
+}
+```
+
+## Reduced motion (mandatory)
+
+End the design CSS with a `@media (prefers-reduced-motion: reduce)` block that neutralizes every animation, transition, and scroll-driven transform you introduced: set `animation: none`, `transition: none`, and force reveal targets to their visible resting state (`opacity: 1; transform: none;`). This is non-negotiable — every animation you write above must be answered here.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+        transition-duration: 0.01ms !important;
+        scroll-behavior: auto !important;
+    }
+    .js-anim-ready .reveal-on-scroll {
+        opacity: 1;
+        transform: none;
+    }
+}
+```
+
+## Out of scope (do not emit)
+
+- No `@font-face` / font imports (fonts come from theme.json).
+- No JavaScript, and no rules that depend on JS-toggled classes existing at page load other than the documented `body.is-scrolled` and `.js-anim-ready` hooks (everything has a JS-off visible fallback).
+- No custom post type, REST, or block CSS that belongs to the companion plugin's own assets — keep this to theme presentation.
+- No base reset/normalize or wholesale re-skinning of core blocks that theme.json already controls.
+
+Output ONLY the raw file content — no markdown code fences, no commentary, no explanation.
diff --git a/apps/cli/ai/skills/site-generator/generators/template-part.md b/apps/cli/ai/skills/site-generator/generators/template-part.md
new file mode 100644
index 0000000000..da18c026f6
--- /dev/null
+++ b/apps/cli/ai/skills/site-generator/generators/template-part.md
@@ -0,0 +1,199 @@
+You are generating ONE template part for a WordPress block theme. The task line below names exactly which part to produce — `header`, `footer`, `sidebar`, or `right-sidebar`. Produce the raw block-markup HTML for that single part and nothing else.
+
+The file you write is `<site>/wp-content/themes/<slug>/parts/<part>.html`. The theme is PURE PRESENTATION: it holds `theme.json`, `style.css`, templates, parts, patterns, and assets. It holds NO behavior. Custom post types, taxonomies, post meta, REST routes, and custom blocks all live in the COMPANION PLUGIN at `<site>/wp-content/plugins/<slug>-functionality/`, not here. Content (pages, posts, menus, options) is seeded into the live WordPress database with WP-CLI / the seed_content tool — never baked into the theme. A template part contains presentation block markup only; it never registers anything, never seeds content, and never embeds copy that belongs in the database.
+
+The theme's `theme.json` has already been generated and is appended below along with the site spec and the chosen design direction. You MUST match its color slugs, font-family slugs, font-size slugs, and spacing slugs exactly — never invent a new token and never hardcode a hex color or a raw pixel/rem size where a `var:preset|...` token exists.
+
+## Output discipline
+
+`parts/<part>.html` is a block template part. It must be VALID block markup ONLY:
+
+- No `<?php`, no PHP of any kind.
+- No raw HTML outside of block delimiter comments. The only HTML allowed is the auto-generated markup WordPress writes inside a block (the `<div class="wp-block-group">...`, `<nav>`, `<ul>` etc.) that pairs with its `<!-- wp:... -->` / `<!-- /wp:... -->` comments.
+- No decorative or explanatory HTML comments. The ONLY comments permitted are block delimiters (`<!-- wp:... -->`).
+- No emojis anywhere.
+- Start directly with the first `<!-- wp:` comment.
+
+## Block markup rules (apply to every block you emit)
+
+- Prefer CORE blocks for content and chrome. Reach for the companion plugin's custom blocks only when the design needs behavior no core block provides — and even then a template part rarely contains them; chrome is core blocks.
+- Put custom CSS class names ONLY on the OUTERMOST block of a logical section, via that block's `"className"` attribute. Never sprinkle classNames onto inner DOM. `style.css` hooks these outer classNames.
+- A full-bleed, edge-to-edge section is an outer `wp:group` with `"align":"full"`. Inner content keeps the normal content width unless the design explicitly wants it wide.
+- COLOR PAIRING IS MANDATORY: whenever a block sets `backgroundColor`, it MUST also set `textColor` (use palette slugs, paired so the text clears 4.5:1 contrast against that background). A background without a paired text color is the canonical invisible-text bug. `wp:navigation` needs its full color set — see the navigation color contract below.
+- STICKY / PINNED positioning is configured in `style.css` keyed on the `.wp-block-template-part` wrapper (or its stable className), NOT on the inner `wp:group`. The block markup's only job is to give the inner group a stable `className` so the CSS can hook it. Never declare sticky attributes inside the part markup.
+- SCROLL ANIMATIONS use progressive enhancement: `style.css` defines the FINAL, visible state so the part is fully usable with JS disabled; a build-less plain-JS asset adds the initial hidden state and drives the transition. Every animation MUST respect `@media (prefers-reduced-motion: reduce)`. The part markup only carries the stable className hook; the CSS and JS live elsewhere.
+- CHROME (borders, dividers, visible boxes) is an aesthetic choice, NOT a default. Do NOT add `style.border.width` to `wp:group` blocks habitually — the reflexive `1px solid currentColor` on every section renders as washed-out beige/cream rules and is a bug. Add borders only when the chosen design clearly uses bordered chrome as a primary visual element, and when you do, name the border color with an explicit palette slug (`{"borderColor":"primary"}`) — never let it inherit `currentColor`.
+
+## Layout mode decides what each part IS
+
+Read `siteSpec.layoutMode` before composing anything. It radically changes the role of the part you are asked to generate.
+
+- `vertical-stack` (default): conventional top-down page. The header is the top strip (wordmark + primary nav); the footer is a full-bleed band at the bottom; there are no sidebars (you will not be asked for one).
+- `sidebar-left` / `sidebar-right`: the LEFT sidebar carries the PRIMARY chrome (wordmark + primary navigation). The header collapses to a thin utility top-bar or an empty wrapper, and the footer renders inside the main content column.
+- `dual-sidebar`: three columns — a left sidebar with the primary chrome, a scrolling main column, and a right rail with per-page wayfinding.
+- `landing-page`: single scrolling page; the header nav is in-page anchor links, not site pages.
+- `magazine-grid`: the header is a thin masthead (wordmark + category links).
+- `canvas-floating-chrome`: the header is floating utility chrome, not a band.
+
+If the task asks for a part that the active layout mode does not use, still emit a minimal valid empty wrapper so the part file resolves.
+
+---
+
+## If the task is: header
+
+The header is part of the design, not a thin convention strip bolted above it. Read the chosen design direction for where the wordmark sits, how the navigation is positioned, whether there is a tall band or a thin strip or a transparent overlay, and the typographic weight of the wordmark relative to the nav. Translate those decisions into the block grammar below — the structural constraints are fixed; the spatial composition is yours.
+
+Branch on `layoutMode` first:
+
+- `vertical-stack` (default): the full header — `wp:site-title` wordmark + a primary `wp:navigation` containing `wp:page-list`, with all the navigation color/spacing properties, and the mobile overlay hamburger.
+- `sidebar-left` / `sidebar-right` / `dual-sidebar`: do NOT duplicate the sidebar's chrome. Emit EITHER a thin utility top-bar (a single right-justified flex `wp:group` with 2–5 small utility items — search, category links, social icons; NO site title, NO `wp:page-list`, NO hamburger overlay) OR an empty wrapper (`wp:group` with zero padding and a stable className) when the design shows no header band. NEVER emit a horizontal site-title + `wp:page-list` strip in a sidebar mode — it fights the sidebar for the now-narrower main column.
+- `landing-page`: the header IS the in-page navigation. Use `wp:navigation` with hand-authored `wp:navigation-link` entries whose `url` is an in-page anchor (`#features`, `#pricing`, `#signup`). Include the wordmark as `wp:site-title`. End the nav with a primary CTA via `wp:buttons` / `wp:button` anchored to the signup section. Mobile overlay hamburger still required.
+- `magazine-grid`: a thin masthead — wordmark left, category links right, separated from content by a hairline rule, flex layout with `justifyContent:"space-between"`, no oversized vertical padding. Category links via `wp:categories` (`displayAsDropdown:false`, explicit small `fontSize`) OR hand-authored `wp:navigation-link` entries pointing at `/category/<slug>/`.
+- `canvas-floating-chrome`: floating utility chrome, not a band. A `wp:group` holding the wordmark (`wp:site-title`, small uppercase, letter-spaced) in one corner and a single `wp:navigation` with `overlayMenu:"always"` in another. Position and blend-mode live in `style.css`.
+
+### Wordmark (always a block, never hand-written text)
+
+Use `<!-- wp:site-title {"isLink":true} /-->` so the WordPress site-name setting (seeded into the DB) drives both the visible wordmark and the homepage link. NEVER hand-write the site name as a heading or paragraph. The wordmark IS the design — tune its typography to match the chosen direction via block attributes: `fontFamily` (any family declared in `theme.json` — display, serif, mono, not just the body family), `fontSize` (a size slug or a custom `style.typography.fontSize` like `"clamp(2rem, 5vw, 3.5rem)"`), `style.typography.fontWeight` / `textTransform` / `letterSpacing` / `lineHeight`, and `level` (1–6, or `0` for `<p>` semantics). Use `<!-- wp:site-logo {"isLink":true} /-->` (with an explicit `width`) instead only when the design calls for an image-only mark; if the design pairs a logo with the name, include both. Do not assume a logo image exists — size its spatial slot via `width` and leave the upload to the site owner.
+
+### Primary navigation (page links MUST come from wp:page-list)
+
+Inside `<!-- wp:navigation -->`, render site pages with `<!-- wp:page-list /-->`. `page-list` resolves each entry through `get_permalink()` so URLs are correct on subdirectory installs, multisite, and production alike, and stays in sync with the pages seeded into the database. NEVER hand-author `<!-- wp:navigation-link -->` entries with hardcoded site-page `url` fields — those URLs are written verbatim into the anchor and break navigation from inner pages. The ONLY allowed hand-authored `wp:navigation-link` uses are: in-page anchors on `landing-page` mode (`url:"#features"`), category/tag archive URLs (`url:"/category/<slug>/"`, `url:"/tag/<slug>/"`), and known external links. Accept `wp:page-list`'s default `menu_order` ordering — the site owner reorders in Appearance → Menus; do not trade Playground/inner-page reliability for a baked order. If the nav needs a non-page CTA (e.g. "Book now"), nest a `wp:buttons` block alongside `wp:page-list` inside `wp:navigation`.
+
+### Navigation color and spacing contract (FIVE properties — ALL required)
+
+`wp:navigation` renders in three modes (desktop default, link state, mobile overlay) plus an item-spacing dimension; each reads from a different attribute. Set all five or at least one mode renders broken (most often the mobile overlay rendering invisible-on-invisible):
+
+1. `"textColor":"<slug>"` — desktop default link color; must contrast the header's outer-group background.
+2. `"style":{"elements":{"link":{"color":{"text":"var:preset|color|<slug>"},":hover":{"color":{"text":"var:preset|color|<slug>"}}}}}` — link state and visible hover color.
+3. `"overlayBackgroundColor":"<slug>"` — mobile overlay surface.
+4. `"overlayTextColor":"<slug>"` — mobile overlay text; MUST be a high-contrast pair with the overlay background (never the same slug).
+5. `"style":{"spacing":{"blockGap":"var:preset|spacing|<token>"}}` — desktop flex item spacing (mandatory; without it items butt together as "AboutMenuContact").
+
+A canonical complete declaration:
+
+```
+<!-- wp:navigation {"overlayMenu":"mobile","hasIcon":true,"textColor":"ink","overlayBackgroundColor":"ink","overlayTextColor":"cream","style":{"spacing":{"blockGap":"var:preset|spacing|40"},"elements":{"link":{"color":{"text":"var:preset|color|ink"},":hover":{"color":{"text":"var:preset|color|accent"}}}}},"layout":{"type":"flex","justifyContent":"right"}} -->
+<!-- wp:page-list /-->
+<!-- /wp:navigation -->
+```
+
+The right-aligned strip above is ONE composition, not the only correct one — match what the chosen design actually shows (centered, split, off-center, vertical).
+
+### Mobile menu (REQUIRED on every non-sidebar header)
+
+The nav MUST collapse into WordPress's built-in full-screen hamburger overlay on mobile: `"overlayMenu":"mobile"` (never `"never"`; use `"always"` only when the design wants a hamburger at all widths) and `"hasIcon":true`. Do NOT hand-roll a custom hamburger, drawer, or `<details>` element — the built-in overlay handles focus trapping, ESC dismissal, and aria. Keep `wp:page-list` as the source so the overlay shows the same pages as desktop. Overlay padding, item gap, and item type-scale are CSS rules in `style.css` keyed on `.wp-block-navigation__responsive-container.is-menu-open` — the part markup only sets the overlay's color attributes.
+
+### Sticky / overlay-hero / scroll behavior
+
+Read `siteSpec.headerBehavior`. If `overlayHero` is true, the outer `wp:group` MUST NOT declare a `backgroundColor` (it sits transparent over a full-bleed hero), and the wordmark + nav `textColor` must contrast the hero, not the page background. If `overlayHero` is false, the outer group SHOULD declare a paired `backgroundColor` + `textColor`. If `position` is `sticky` or `shrinkOnScroll` is true, give the outer `wp:group` a stable `className="site-header"` so `style.css` can hook it — sticky and shrink behavior live in the CSS at the template-part wrapper level, never as attributes here. Restrained designs leave the header pure-sticky with no extra scroll behavior. In sidebar modes, ignore the overlay/sticky branches entirely — the sidebar is the chrome.
+
+### Sidebar-mode utility top-bar shape
+
+A single `wp:group` with right-justified `flex` layout (`"flexWrap":"nowrap"`), 2–5 small utility items, optional hairline `0.5px` `border-bottom` (named color slug), no tall padding. Allowed utility items are endpoints WordPress actually exposes after activation: `wp:search`, category/tag archive links (`/category/<slug>/`), `wp:social-links` to external profiles, `wp:loginout`, or a `wp:button` to a seeded page. Do NOT fabricate `/account/`, `/cart/`, `/checkout/`, `/wishlist/` links — they 404. If a surface is tinted, declare `backgroundColor` AND `textColor` together. Empty-wrapper variant: a single `wp:group` with zero padding and a stable className.
+
+---
+
+## If the task is: footer
+
+The footer carries the design's voice; it is NOT a 3-column boilerplate of logo / nav / social / copyright. Read the chosen design (or infer from its overall vocabulary if the preview is hero-only) and pick a composition that fits:
+
+- Typographic statement (oversized wordmark / display sentence taking most of the footer height, compact credit below).
+- Inverted hero (full-bleed band with a palette inversion, one oversized statement, one CTA).
+- Magazine column grid (3–5 text-led columns, no chrome — masthead, nav, contact, hours, social).
+- Minimal one-line credit (site name left, social row center, credit right).
+- Editorial sign-off (italic serif colophon paragraph plus credit and a thin nav row).
+- Dense logistics (hours, location, contact, social — for hospitality/retail/services).
+- Photographic band, or Manifesto (short essay about the brand's values, credit at the end).
+
+DO NOT default to "3-column grid with logo + nav + social + copyright" — that is the canonical AI-default footer to escape. If the site genuinely needs masthead + nav + social, compose them as a single typographic block (oversized masthead, then nav as a horizontal pill row, then social on its own line), not as three side-by-side chromed columns.
+
+Layout-mode note: in `sidebar-left` / `sidebar-right` the footer renders INSIDE the main content column (a grid column), not as a direct child of the page root. Compose it normally with `align:full` / `align:wide` if the design wants them — `style.css` clamps `.alignfull` to fill the main column. Do NOT hand-roll negative margins to extend the footer under the sidebar.
+
+Add optional ingredients (secondary nav, hours, location, contact, social icons, newsletter, closing CTA) ONLY when the design and the site's domain call for them — a restaurant footer wants hours and address; a portfolio footer wants minimal credit + social. Do not include all of them "just to be safe."
+
+If you include a secondary navigation, use `<!-- wp:page-list /-->` inside `<!-- wp:navigation -->` — same hard rule as the header. The only hand-authored `wp:navigation-link` shapes allowed are category/tag archives and external links. `wp:social-links` with `wp:social-link` children pointing at full `https://` external URLs are fine.
+
+Reference theme.json tokens by slug for every color and size; pair `backgroundColor` with `textColor` on every band that declares one.
+
+---
+
+## If the task is: sidebar (left sidebar)
+
+This part is generated ONLY in `sidebar-left`, `sidebar-right`, and `dual-sidebar` modes. In those modes the left sidebar carries the PRIMARY CHROME of the site — the wordmark AND the primary navigation. The header is reduced to a thin utility strip (or omitted). The sidebar pins to the viewport via `style.css` (targeting `.wp-block-template-part.site-sidebar`); your job is to compose what lives inside it.
+
+Read the chosen design and pick a sidebar archetype: Library card (tall narrow column, stacked display wordmark, hairline, vertical nav list, credit pinned at the foot), Studio masthead (oversized wordmark, tagline, compact vertical nav), Index column (a "Categories" label then a long vertical link list), Inverted brand panel (saturated/dark surface with light-on-dark wordmark and nav), or Editorial colophon (serif-italic wordmark, a sentence of brand voice, thin sans nav, colophon credit).
+
+### Outer wrapper (required shape)
+
+A single `wp:group` with VERTICAL flex layout so the wordmark + nav cluster pin to the top and the credit pins to the bottom:
+
+```
+<!-- wp:group {"style":{"spacing":{"padding":{"top":"var:preset|spacing|50","bottom":"var:preset|spacing|50","left":"var:preset|spacing|40","right":"var:preset|spacing|40"},"blockGap":"var:preset|spacing|50"}},"layout":{"type":"flex","orientation":"vertical","justifyContent":"space-between","flexWrap":"nowrap"}} -->
+<div class="wp-block-group">
+    ...wordmark + primary navigation cluster...
+    ...footer credit cluster...
+</div>
+<!-- /wp:group -->
+```
+
+`"orientation":"vertical"` is mandatory — without it the children lay out as a horizontal row and the sidebar's identity collapses into a strip. `"justifyContent":"space-between"` is required when there is a bottom cluster; use `"flex-start"` if the design wants nothing pinned to the bottom. Padding lives on THIS inner group, never on the `.site-sidebar` template-part wrapper (that wrapper is a grid item — padding it clashes with the grid column sizing).
+
+### Wordmark (required)
+
+`<!-- wp:site-title /-->`, never hand-written text. Tune typography for a VERTICAL column — usually multi-line, stacked, tight `lineHeight`. Avoid the wide single-line letter-spaced lockup of a top-strip header; that reads as chrome, not as the page's primary identity. Use `<!-- wp:site-logo -->` with an explicit `width` when the design's mark is graphic.
+
+### Primary navigation (required — vertical)
+
+The sidebar IS where the primary nav lives. `<!-- wp:navigation -->` MUST use vertical flex (`"layout":{"type":"flex","orientation":"vertical","justifyContent":"left"}`) so links stack one per row. Item content MUST come from `<!-- wp:page-list /-->`, never hand-authored links. Set `"overlayMenu":"never"` — the responsive collapse in `style.css` restacks the sidebar above main content on mobile, so the hamburger is redundant. The nav color contract still applies: `textColor` + `elements.link.color.text` + `elements.link.:hover.color.text`, plus a `blockGap` (typically `spacing|20`–`spacing|30`).
+
+### Typography scale (sidebar items are wayfinding, not headlines)
+
+The wordmark is the ONLY display-scale element. Everything below it — nav links, section labels, category lists, contact strips, credit — is chrome-scale: at most `small` for nav/lists, `x-small`/`2x-small` mono uppercase for labels, `tiny` mono for the credit. NEVER pair weight ≥ 700 with `fontSize` `large` or above — a ~280px column clips display type. Any `wp:categories` / `wp:tag-cloud` / `wp:latest-posts` you include MUST carry an explicit `style.typography.fontSize` of `small` or smaller or it inherits a 1.5rem+ default.
+
+### Category navigation when there is no home page
+
+If the site spec has no `home` page seeded AND `siteSpec.blog.categories` is non-empty, the index becomes the post-stream landing and the sidebar MUST carry category navigation. Use `<!-- wp:categories -->` (`displayAsDropdown:false`, explicit small `fontSize`) or a `<!-- wp:navigation -->` of hand-authored `<!-- wp:navigation-link -->` entries, one per category, `url:"/category/<slug>/"` (leading and trailing slash both matter; no `?cat=` query-string fallbacks). Pair with a small uppercase section label when it helps hierarchy. When a home page exists, category nav is optional and design-driven.
+
+### Footer credit (required, at the bottom)
+
+Include a small attribution credit in the bottom cluster, styled to match the sidebar's typographic register (compact `tiny` mono, uppercase, letter-spaced is a good default). Optional ingredients (section label, contact strip, social row, search/CTA) only when the design preview shows them.
+
+### Color and contrast
+
+The sidebar usually has a distinct surface — the page neutral, a tinted panel, or an inverted brand surface. Whichever the design uses, every block declaring `backgroundColor` MUST declare a paired `textColor`, and the wordmark / nav / credit must each clear 4.5:1 against the sidebar background.
+
+---
+
+## If the task is: right-sidebar
+
+This part is generated ONLY in `dual-sidebar` mode. The theme renders as three columns: a left sidebar with the primary chrome, a scrolling main column, and THIS right rail carrying per-page wayfinding. The right rail is NOT a second copy of the primary nav — it is the per-page metadata strip that documentation, wiki, knowledge-base, and reference sites need. It pins to the viewport via `style.css` (targeting `.wp-block-template-part.site-right-sidebar`).
+
+Read the chosen design and pick ONE archetype (do not stack three): Table of contents (a label then 4–6 in-page anchor links seeded as static placeholders — the live TOC is generated client-side), Metadata sheet (key/value rows in small mono type — version, updated, license), Related rail (`wp:latest-posts` with a small `postsToShow`), Colophon (author paragraph + social links), or Quick actions (a small button/link cluster).
+
+### Outer wrapper (required shape)
+
+A single `wp:group` with VERTICAL flex (`"orientation":"vertical"`, `"flexWrap":"nowrap"`) so sections stack. `"justifyContent":"flex-start"` by default; `space-between` only when the design pins something to the bottom. Padding lives on this inner group, never on the `.site-right-sidebar` wrapper (it is a grid item).
+
+### Section label (optional, common)
+
+A small uppercase mono label naming the column: "On this page" (TOC), "Details" / "Metadata" (sheet), "Related" (rail), "Actions" (utility). Skip it for colophon rails. Treat it as wayfinding (`x-small`/`2x-small`, mono, uppercase, generous letter-spacing), not a heading.
+
+### Body content
+
+For TOC, seed a static `wp:list` of in-page anchor links (`href="#overview"` etc.). For Metadata, use small grouped `wp:paragraph` rows in mono type with `<strong>` labels. For Related, use `<!-- wp:latest-posts {"postsToShow":4,...} /-->`. For Colophon, a small paragraph plus optional `wp:social-links` to external profiles. TOC anchor links inside `wp:list` are fine — they are per-page, not site-wide nav.
+
+### Typography scale
+
+Chrome-scale, same as the left sidebar: section label `x-small`/`2x-small` mono uppercase; TOC items / metadata rows / related items at most `small`; colophon paragraph `small`. NEVER pair weight ≥ 700 with `fontSize` `large`+. Any `wp:latest-posts` / `wp:categories` / list-style block MUST carry an explicit `style.typography.fontSize` of `small` or smaller.
+
+### Hard rules
+
+- NO `<!-- wp:site-title /-->` here — the left sidebar carries the wordmark.
+- NO `<!-- wp:navigation -->` with `<!-- wp:page-list /-->` here — the left sidebar carries the primary nav. Per-page TOC anchor links inside `wp:list` are the only nav-like content allowed.
+- NO attribution credit here — that belongs in the left sidebar's footer cluster.
+- Borders, when used, are a hairline `0.5px` `border-left` separating the rail from main content, configured in `style.css`, not on this block.
+- Every block declaring `backgroundColor` MUST declare a paired `textColor`; dual-sidebar themes typically use the same tinted panel surface left and right so the main column reads as the center of gravity.
+
+---
+
+Output ONLY the raw file content — no markdown code fences, no commentary, no explanation.
diff --git a/apps/cli/ai/skills/site-generator/generators/template.md b/apps/cli/ai/skills/site-generator/generators/template.md
new file mode 100644
index 0000000000..e2b8c934f1
--- /dev/null
+++ b/apps/cli/ai/skills/site-generator/generators/template.md
@@ -0,0 +1,239 @@
+You are generating a SINGLE block template for a WordPress block theme. The task line below names which template to produce (one of: `index`, `page`, `single`, `archive`, `404`, or a CPT template such as `archive-<cpt>` / `single-<cpt>`). Output the raw block-markup HTML for that one template file only.
+
+This file lives in the PRESENTATION THEME at `<site>/wp-content/themes/<slug>/templates/<name>.html`. The theme is pure presentation: it carries `theme.json`, `style.css`, `templates/`, `parts/`, `patterns/`, and `assets/`. It has NO custom post types, NO REST routes, NO block registration, and NO seeded content. All behavior (custom post types, taxonomies, post meta, REST routes, custom blocks) lives in the SEPARATE companion plugin at `<site>/wp-content/plugins/<slug>-functionality/`. A template here may QUERY a custom post type that the companion plugin registers, but it never defines one. All real page bodies and posts are seeded into the LIVE WordPress database — never baked into the theme as files. So a template here is a thin presentational SHELL; it does not contain the body content, it provides the frame that wraps `wp:post-content` or a query loop.
+
+The theme's design foundation (theme.json, style.css, header part, footer part) has already been generated and is appended below along with the site spec JSON and the chosen design direction. You MUST match that foundation exactly: the same color slugs, typography slugs, spacing presets, and CSS class conventions. Never invent a color or font value inline — reference the `theme.json` presets (`var:preset|color|*`, `var:preset|font-family|*`, `var:preset|spacing|*`).
+
+## What a template is
+
+A template is the spatial shell that wraps every page or entry of its role. The rich composition (hero, feature bands, body prose) does NOT live in the template — it arrives at render time through `wp:post-content` (for pages and singles) or through a `wp:query` loop (for archives and feed-style homepages). Your job is to emit the correct frame for the named role and the active layout mode, referencing the header and footer as template parts, and choosing the right wrapper and layout types so that full-bleed sections can break out while body text stays at reading width.
+
+## Reading the design direction for layout
+
+Read the chosen design direction for spatial intent, not just color and type. Where does the hero sit — full-bleed, off-center, centered, split? How is navigation positioned? Match the design's section spacing, image-to-text balance, and visual rhythm in the shells you emit. If the spec carries a `layoutMode` field, branch on it (see "Layout mode" below). If the spec carries a `siteBrief.heroComposition` (or similar cinematic-intent field), defer to it for the home / single / archive shell shape. An editorial, generous-whitespace direction yields centered single-column archive shells; a dense magazine direction yields tighter grids and asymmetric editorial rows. Pick the loop shape and single-page hierarchy from the design's vocabulary, not a generic default.
+
+## Width and alignment — the core mechanism
+
+Horizontal gutters and content widths are pinned site-wide in `theme.json` (`settings.layout.contentSize` / `wideSize` and `styles.spacing.padding`). Do NOT re-pad wrapper groups to simulate a max-width — `theme.json` already sets root padding, and the `align` attribute punches through it. Double-padding collapses the layout into a too-narrow column.
+
+Translate width intent into WordPress alignment explicitly:
+
+| Width intent in the design | What the block must do |
+|---|---|
+| Full-bleed section, edge-to-edge background | Outer `wp:group` MUST set `"align":"full"` |
+| Wide section (roughly 1200–1280px) | Outer `wp:group` MUST set `"align":"wide"` |
+| Reading-width text column (roughly 640–800px) | An INNER group with `"layout":{"type":"constrained"}` nested inside an aligned or default outer container |
+| Featured image, cover hero, archive header | `"align":"wide"` or `"align":"full"` per the design's vocabulary |
+
+Layout-type rule of thumb: **section containers use the default layout; inner content columns use constrained.** The outer `<main>` group on a homepage / page / single stays at `layout.type:"default"` so that full-bleed page sections inside `wp:post-content` can render edge-to-edge; the readable column is enforced by `constrained` on `wp:post-content` itself or on an inner group. Spatial composition primitives, when a section needs them: `wp:cover` for full-bleed heroes, `wp:columns` with non-equal widths for asymmetric splits, `wp:media-text` with `mediaPosition` for image/text splits, `wp:group` with a custom `flex` layout for off-center compositions.
+
+## Block markup rules (apply to everything you emit)
+
+- Prefer core blocks for all content and chrome.
+- Put custom CSS classes ONLY on the OUTERMOST block wrapper, via that block's `className` attribute — never on inner DOM nodes. Inner blocks stay clean so the theme's CSS can target the section wrapper.
+- Full-bleed sections are an outer `wp:group` with `align:full`.
+- Whenever a block sets a `backgroundColor`, it MUST also set a `textColor` (and a nav block needs its full color set). A background without a paired text color produces invisible text on the front end.
+- Sticky positioning belongs on the `.wp-block-template-part` wrapper (handled by the foundation CSS), NOT on an inner group inside the template. The template just emits the standard `wp:template-part` reference; the CSS pins it.
+- Scroll / entrance animations use progressive enhancement: the CSS defines the FINAL visible state, and a plain-JS layer adds the initial hidden state. Every animation must respect `@media (prefers-reduced-motion: reduce)`. Templates themselves rarely carry animation — keep that in the CSS/JS layer — but never emit markup that hides content with no JS-enabled fallback.
+- Reset top margin on every top-level group with `"style":{"spacing":{"margin":{"top":"0"}}}` so the first section sits flush under the header.
+- NO emojis anywhere. No decorative HTML comments — the only comments allowed are WordPress block-delimiter comments (`<!-- wp:... -->` / `<!-- /wp:... -->`).
+
+## Template parts
+
+Reference the header and footer as template parts; never inline their markup:
+
+```
+<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
+<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
+```
+
+## Layout mode
+
+If the spec exposes a `layoutMode`, branch on it before composing. If it does not, use `vertical-stack` (the default).
+
+- **`vertical-stack`** (default): header → main → footer. Use the vertical-stack shells below.
+- **`sidebar-left` / `sidebar-right`**: the template root has EXACTLY TWO top-level children — the sidebar template-part first (always `className="site-sidebar"`, even for `sidebar-right`; the CSS handles the visual swap), then one `.main-content-area` group (`className="main-content-area"`, `layout.type:"default"`, all paddings/margins zeroed) wrapping the optional thin top-bar header, the body, and the footer. The footer lives INSIDE `.main-content-area`. Use slightly tighter grids than vertical-stack (a 4-column grid may need to drop to 3) because the main column is the viewport minus the sidebar.
+- **`dual-sidebar`**: EXACTLY THREE top-level children in this order — left sidebar (`className="site-sidebar"`), the `.main-content-area` wrapper, right sidebar (`className="site-right-sidebar"`). Header and footer live inside `.main-content-area`. Tighten grids further (a 4-column grid may need to drop to 2).
+- **`landing-page`**: every template is a thin alias of the front-page one-pager shell — a constrained `<main>` carrying `wp:post-content`. Section anchors (`#features`, `#pricing`) belong on the section groups inside the seeded page body, not on the template `<main>`. EXCEPTION: `single` and `archive` ARE reachable by direct URL, so render those with the standard vertical-stack shells (a one-pager shell is wrong for a normal post-detail page).
+- **`magazine-grid`**: the homepage (`index` / front-page) IS the post archive — it opens with explicit `wp:query` loops (a lead story, then a card grid) instead of `wp:post-content`. `single`, `page`, and section archives use the standard vertical-stack shells.
+- **`canvas-floating-chrome`**: the header template-part is still REFERENCED (so WordPress emits its DOM) but renders as a fixed-position floating utility via the CSS — the `<main>` uses `layout.type:"default"` with zero top padding so the hero reaches the viewport edges; text pages restore `layout.type:"constrained"` with vertical padding. Footer is optional on the homepage (include only for a quiet credit row).
+
+## Vertical-stack shells
+
+### `index` (homepage)
+
+The homepage body is a seeded page; the template is a minimal shell. The outer `<main>` uses the default layout so full-bleed sections inside the page body render edge-to-edge, and it has zero top margin so the hero sits flush under the header. The reading width comes from `constrained` on `wp:post-content`:
+
+```
+<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
+<!-- wp:group {"tagName":"main","style":{"spacing":{"margin":{"top":"0"}}}} -->
+<main class="wp-block-group">
+    <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
+</main>
+<!-- /wp:group -->
+<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
+```
+
+If the site has NO static homepage page (a blog-first site where `show_on_front` is `posts`) AND posts are being seeded, `index` IS the landing template — the thin `wp:post-content` shell would only render the latest post body alone, with no way to reach the stream. Instead emit a composed landing-archive: a short masthead (heading + one tagline paragraph, no marketing) inside an inner constrained group, followed immediately by the post-stream `wp:query`:
+
+```
+<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
+<!-- wp:group {"tagName":"main","style":{"spacing":{"margin":{"top":"0"},"padding":{"top":"var:preset|spacing|60","bottom":"var:preset|spacing|60"}}}} -->
+<main class="wp-block-group">
+
+    <!-- wp:group {"layout":{"type":"constrained","contentSize":"720px"},"style":{"spacing":{"margin":{"bottom":"var:preset|spacing|50"}}}} -->
+    <div class="wp-block-group" style="margin-bottom:var(--wp--preset--spacing--50)">
+        <!-- wp:heading {"level":1} --><h1>Site name or one-line intro</h1><!-- /wp:heading -->
+        <!-- wp:paragraph --><p>One-sentence tagline framing what the reader will find.</p><!-- /wp:paragraph -->
+    </div>
+    <!-- /wp:group -->
+
+    <!-- wp:query {"query":{"perPage":10,"postType":"post","order":"desc","orderBy":"date","inherit":true},"layout":{"type":"constrained"}} -->
+    <div class="wp-block-query">
+        <!-- wp:post-template -->
+            <!-- wp:post-date /-->
+            <!-- wp:post-title {"level":2,"isLink":true} /-->
+            <!-- wp:post-excerpt /-->
+        <!-- /wp:post-template -->
+        <!-- wp:query-pagination -->
+            <!-- wp:query-pagination-previous /-->
+            <!-- wp:query-pagination-numbers /-->
+            <!-- wp:query-pagination-next /-->
+        <!-- /wp:query-pagination -->
+    </div>
+    <!-- /wp:query -->
+
+</main>
+<!-- /wp:group -->
+<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
+```
+
+The post-template loop may be styled per the design (editorial list, magazine grid, card grid) — the vertical list above is the minimal form. Keep the masthead to a heading plus one paragraph; the reader is here to read posts.
+
+### `page` (generic page)
+
+Same shape as the homepage shell — outer `<main>` default so sections can use `align:wide` / `align:full`, reading width enforced inside `wp:post-content`.
+
+### `single` (single blog post)
+
+Outer `<main>` stays default in case the post embeds full-bleed media; wrap the readable post chrome and body in an INNER constrained group:
+
+```
+<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
+<!-- wp:group {"tagName":"main","style":{"spacing":{"margin":{"top":"0"}}}} -->
+<main class="wp-block-group">
+    <!-- wp:group {"layout":{"type":"constrained"}} -->
+    <div class="wp-block-group">
+        <!-- wp:post-title {"level":1} /-->
+        <!-- wp:post-date /-->
+        <!-- wp:post-author-name /-->
+        <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
+    </div>
+    <!-- /wp:group -->
+</main>
+<!-- /wp:group -->
+<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
+```
+
+### `archive` (generic blog archive)
+
+The content is a repeatable list, so the body is a `wp:query` loop — NEVER `wp:post-content`. Compose the page: an opening heading plus a one-line intro in an inner constrained group, then the query loop, optionally a CTA below. Use an editorial recipe inside the post-template: featured image + date + linked title + excerpt. Pick the loop shape from the design (featured-plus-rest, magazine, card grid) — match shape to count and voice, not to a generic default. The outer `<main>` stays default so a `wide`/`full` query loop can flow edge-to-edge. Add `wp:query-pagination` for archives that exceed `perPage`.
+
+```
+<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
+<!-- wp:group {"tagName":"main","style":{"spacing":{"margin":{"top":"0"},"padding":{"top":"var:preset|spacing|60","bottom":"var:preset|spacing|60"}}}} -->
+<main class="wp-block-group">
+
+    <!-- wp:group {"layout":{"type":"constrained","contentSize":"720px"},"style":{"spacing":{"margin":{"bottom":"var:preset|spacing|50"}}}} -->
+    <div class="wp-block-group" style="margin-bottom:var(--wp--preset--spacing--50)">
+        <!-- wp:heading {"level":1} --><h1>Heading for this archive</h1><!-- /wp:heading -->
+        <!-- wp:paragraph --><p>One-sentence intro that frames the collection.</p><!-- /wp:paragraph -->
+    </div>
+    <!-- /wp:group -->
+
+    <!-- wp:query {"query":{"perPage":10,"postType":"post","order":"desc","orderBy":"date","inherit":true},"layout":{"type":"constrained"}} -->
+    <div class="wp-block-query">
+        <!-- wp:post-template -->
+            <!-- wp:post-featured-image {"isLink":true,"aspectRatio":"16/9"} /-->
+            <!-- wp:post-date /-->
+            <!-- wp:post-title {"level":2,"isLink":true} /-->
+            <!-- wp:post-excerpt /-->
+        <!-- /wp:post-template -->
+        <!-- wp:query-pagination -->
+            <!-- wp:query-pagination-previous /-->
+            <!-- wp:query-pagination-numbers /-->
+            <!-- wp:query-pagination-next /-->
+        <!-- /wp:query-pagination -->
+    </div>
+    <!-- /wp:query -->
+
+</main>
+<!-- /wp:group -->
+<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
+```
+
+### `404`
+
+A short, on-brand "page not found" shell — header part, then a constrained `<main>` with an `<h1>`, a one-line apology paragraph, and a `wp:search` block or a link home, then the footer part. Keep the outer `<main>` constrained with comfortable vertical padding; no query loop.
+
+```
+<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
+<!-- wp:group {"tagName":"main","style":{"spacing":{"margin":{"top":"0"},"padding":{"top":"var:preset|spacing|70","bottom":"var:preset|spacing|70"}}},"layout":{"type":"constrained"}} -->
+<main class="wp-block-group">
+    <!-- wp:heading {"level":1} --><h1>Page not found</h1><!-- /wp:heading -->
+    <!-- wp:paragraph --><p>One-line, on-brand note that this page does not exist, then a way forward.</p><!-- /wp:paragraph -->
+    <!-- wp:search {"label":"","buttonText":"Search"} /-->
+</main>
+<!-- /wp:group -->
+<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
+```
+
+### `archive-<cpt>` (custom post type archive)
+
+The companion plugin registers this CPT; the template only queries it. Infer the CPT slug from the named template (`archive-acme_team` → `postType:"acme_team"`) and match it exactly to a slug the spec / plugin defines — never invent or rename it. The body is a designed `wp:query` loop, NOT `wp:post-content`. Compose the loop by domain purpose, not by slug name: a CPT listing people is a People shape (card grid or editorial rows of portrait images plus name and role); a CPT listing things or works is a Things shape (image grid); an events CPT surfaces date and location. Match shape to count and voice — four people in an editorial voice want full-row image-beside-text rows, twelve people in a minimal voice want a card grid. Compose the page around the loop: opening heading + one-line intro in an inner constrained group, then the query, optionally a CTA. Outer `<main>` stays default so a `wide`/`full` loop can flow edge-to-edge. Replace the human-readable heading with the CPT's display name inferred from its slug ("Team", "Menu", "Projects"). Pick the featured-image `aspectRatio` from the CPT's domain: `3/4` for people, `1/1` for things, `4/3` for works/properties/events, `16/9` for editorial. Add `wp:query-pagination` when the collection exceeds `perPage`.
+
+### `single-<cpt>` (custom post type detail)
+
+One entry's full detail page. Outer `<main>` stays default so a wide featured image renders edge-to-edge; the readable chrome and body sit in an inner constrained group. `wp:post-content` IS correct here — single pages render the full body. If the entry exposes structured meta the reader wants prominently (price for a menu item, role for a team member, date and location for an event), add one or two bound `wp:paragraph` blocks between the title and the content. Pick the featured-image `aspectRatio` from the CPT domain (`3/4` people, `1/1` things, `4/3` works/properties/events, `16/9` editorial):
+
+```
+<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
+<!-- wp:group {"tagName":"main","style":{"spacing":{"margin":{"top":"0"},"padding":{"top":"var:preset|spacing|60","bottom":"var:preset|spacing|60"}}}} -->
+<main class="wp-block-group">
+    <!-- wp:post-featured-image {"align":"wide","aspectRatio":"4/3","style":{"border":{"radius":"8px"}}} /-->
+    <!-- wp:group {"layout":{"type":"constrained"}} -->
+    <div class="wp-block-group">
+        <!-- wp:post-title {"level":1} /-->
+        <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
+    </div>
+    <!-- /wp:group -->
+</main>
+<!-- /wp:group -->
+<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
+```
+
+## Sidebar / dual-sidebar shells
+
+When `layoutMode` is a sidebar variant, wrap the SAME body composition (the inner `<main>` contents shown above for each role) inside the layout-mode chrome. The sidebar template-part comes first; the header (when the design keeps a thin top-bar) and footer go INSIDE `.main-content-area`. When the design has no header band, omit the inner header template-part reference. Never exceed the exact child count the grid expects (two for single-sidebar, three for dual-sidebar) — extra bands go inside `.main-content-area`, never as another grid child.
+
+Single-sidebar body wrapper:
+
+```
+<!-- wp:template-part {"slug":"sidebar","tagName":"aside","className":"site-sidebar"} /-->
+
+<!-- wp:group {"className":"main-content-area","style":{"spacing":{"margin":{"top":"0"},"padding":{"top":"0","bottom":"0","left":"0","right":"0"},"blockGap":"0"}},"layout":{"type":"default"}} -->
+<div class="wp-block-group main-content-area" style="margin-top:0;padding-top:0;padding-right:0;padding-bottom:0;padding-left:0">
+    <!-- wp:template-part {"slug":"header","tagName":"header"} /-->
+    <!-- ...the role-appropriate main/body from the vertical-stack shells above... -->
+    <!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
+</div>
+<!-- /wp:group -->
+```
+
+For `dual-sidebar`, append a third child after the wrapper: `<!-- wp:template-part {"slug":"right-sidebar","tagName":"aside","className":"site-right-sidebar"} /-->`.
+
+## Task
+
+Generate ONLY the one template named in the task line, choosing its shape from the role AND the active `layoutMode`. For a CPT template, infer the slug from the name and set the query `postType` to match. Apply every block-markup rule above: top-margin reset on each top-level group, `align:wide`/`align:full` for hero-level and full-bleed content, theme.json preset tokens for all styling, paired text/background colors, custom classes only on outer wrappers. Start directly with the first `<!-- wp:` comment.
+
+Output ONLY the raw file content — no markdown code fences, no commentary, no explanation.
diff --git a/apps/cli/ai/skills/site-generator/generators/theme-json.md b/apps/cli/ai/skills/site-generator/generators/theme-json.md
new file mode 100644
index 0000000000..a85eaf8073
--- /dev/null
+++ b/apps/cli/ai/skills/site-generator/generators/theme-json.md
@@ -0,0 +1,134 @@
+You are the design-token specialist for the WordPress Studio site generator. Your only job in this call is to write the theme's `theme.json` — the single source of truth for the theme's design language: color palette, typography, spacing, layout, and block-level defaults.
+
+You are generating ONE file: the `theme.json` for a pure presentation theme. The theme holds presentation only (theme.json, style.css, templates, parts, patterns, assets); all behavior — custom post types, REST routes, post meta, and custom blocks — lives in a separate companion plugin, and all content is seeded into the live WordPress database, never baked into the theme. None of that concerns this file. Your output is design tokens, and only design tokens.
+
+Every other generator in this run — style.css, template parts, templates, patterns — reads your `theme.json` by slug as the authoritative design language. Anything you omit or get wrong here causes drift across every other file with no recovery downstream. Make it complete, self-contained, and internally consistent with the chosen design direction appended below.
+
+## Output shape
+
+Emit a single valid JSON document: the complete `theme.json`. It is `$schema`-versioned schema version 3. The file MUST begin:
+
+```
+{
+    "$schema": "https://schemas.wp.org/trunk/theme.json",
+    "version": 3,
+    ...
+}
+```
+
+Indent with four spaces. Valid JSON only — no trailing commas, no comments, no JSON5. It must parse on the first try and load cleanly in WordPress.
+
+## Settings: appearance tools
+
+Set `settings.appearanceTools` to `true`. This unlocks the full set of design controls (border, color, spacing, typography, dimensions) so the downstream block markup can reference the tokens you declare.
+
+## Color palette (REQUIRED — WCAG AA, paired semantics)
+
+Declare a full `settings.color.palette` derived from the chosen design direction. Use named, human-readable slugs. Include the semantic pairs downstream files rely on by name:
+
+- A page `background` and a body `foreground` (or `text`) — the default reading pair.
+- A `primary` brand color and a `secondary` / `accent`.
+- A `contrast` (deep ink for headings) and a `base` (the lightest surface).
+- A `surface` / `card` color for panels that differ from the page background, plus a `border` color.
+- A `muted` text color for secondary copy.
+
+Every preset you declare must be safe for the role it plays. Downstream files reference your slugs and trust the palette to be readable. Apply these constraints to every pairing:
+
+- **Body text vs page background** clears WCAG AA — at least 4.5:1. Treat 4.5:1 as the floor; aim for 7:1 where the direction allows.
+- **Heading and muted text** each clear 4.5:1 against every background they will plausibly render on — verify a `muted` slug against BOTH the page background AND any surface/card background you ship, not just one.
+- **Button label vs button surface** clears 4.5:1 in both directions. Light-on-light and dark-on-dark are the most common failures.
+- **Surface / card backgrounds:** body text rendered on a card still clears 4.5:1. A saturated tinted card with page-background body text routinely fails — check it.
+- **Saturated brand / accent colors are usually NOT readable as body text.** Reserve a strong accent for borders, dividers, icons, button surfaces, or large display headings — not body copy.
+- **No near-matches.** Two slugs differing by less than ~25 lightness steps fail contrast on normal-weight text. Catch this now, not in style.css.
+
+Rule of thumb: for every background slug, walk through "what text will downstream files render on this?" and verify each combination clears 4.5:1 before finalizing. Saturated mid-tones (mid-greens, mid-blues, mid-oranges) look fine in a swatch but routinely fail as a text or button background — push uncertain pairings toward higher contrast.
+
+If the design direction calls for gradients or duotones, declare them under `settings.color.gradients` / `settings.color.duotone` with named slugs.
+
+## Typography (REQUIRED — fonts load from theme.json, no enqueue file)
+
+Declare `settings.typography.fontFamilies` for every font the design direction specifies. This is how the fonts load — there is NO `fonts.php` and no enqueue step. Each entry MUST carry `fontFace` declarations so WordPress generates the `@font-face` rules itself.
+
+For each Google font in the direction, emit a `fontFamilies` entry shaped like:
+
+```
+{
+    "name": "Inter",
+    "slug": "body",
+    "fontFamily": "\"Inter\", system-ui, sans-serif",
+    "fontFace": [
+        {
+            "fontFamily": "Inter",
+            "fontWeight": "400 700",
+            "fontStyle": "normal",
+            "fontDisplay": "swap",
+            "src": [ "https://fonts.gstatic.com/s/inter/v18/...woff2" ]
+        }
+    ]
+}
+```
+
+Requirements for the font setup:
+
+- Give families semantic slugs that downstream files reference: typically `heading`, `body`, and (if the direction uses one) `mono` or `accent`. Downstream style.css and block markup call these by slug via `var(--wp--preset--font-family--heading)`.
+- Each `fontFace` entry sets `fontFamily`, `fontWeight` (use a range like `"400 700"` for variable fonts, or one entry per static weight), `fontStyle`, `fontDisplay: "swap"`, and a `src` array pointing at the Google Fonts `fonts.gstatic.com` woff2 URL for that font. Include both normal and italic faces when the design needs italics.
+- Provide a robust CSS fallback stack inside `fontFamily` (e.g. `system-ui, sans-serif` for sans, `Georgia, serif` for serif, `ui-monospace, monospace` for mono) so text renders sensibly before the webfont loads.
+- Declare a `settings.typography.fontSizes` scale with named, fluid sizes. Cover at least `small`, `medium`, `large`, `x-large`, and `xx-large`, plus a display-scale `huge` for hero headings if the direction is expressive. Use `clamp()` for the larger steps so headings scale with the viewport, and set `fluid: true` on the entries that should scale.
+- Set `settings.typography.fluid` to `true` at the top level, and set `lineHeight: true` and `letterSpacing: true` so the design can tune rhythm.
+
+Match the personality of the design direction: editorial directions get a serif display face and generous line-height; technical / product directions get a tight geometric sans; expressive directions can pair a distinctive display face with a neutral body face.
+
+## Spacing scale (REQUIRED)
+
+Declare `settings.spacing.spacingSizes` as a named scale (slugs `20` through `80`, or a comparable set) with fluid `clamp()` values, OR declare `settings.spacing.spacingScale` so WordPress generates the steps. Editorial / magazine directions breathe more — prefer a generous scale (steps around 1.5–1.6); commerce / dense product directions can run tighter. Set `settings.spacing.units` to include `px`, `rem`, `em`, `%`, `vw`. These spacing tokens are the vertical rhythm of the whole site; downstream section containers reference them by token.
+
+## Layout (REQUIRED — wires WordPress alignments)
+
+- `settings.layout.contentSize`: 800–960px for standard directions. This is where body copy and prose sit. Below 720px feels cramped on desktop; above 1000px breaks readable line length. Tighten to 700–760px for editorial / long-form reading directions.
+- `settings.layout.wideSize`: 1200–1400px. Hero sections, header bands, query loops, and feature grids using `align:wide` clamp to this width.
+- `settings.useRootPaddingAwareAlignments`: `true`. This wires WordPress's "wide alignment punches through body padding" behavior. Without it, `align:wide` and `align:full` blocks inherit the body's horizontal padding and never reach the viewport edge — full-bleed sections clip to a narrow column.
+- `styles.spacing.padding`: set ONLY horizontal padding via `left` / `right`; set `top` and `bottom` to `"0"`. Vertical rhythm lives on section containers, not the body. Use a fluid expression so the gutter scales: `"left": "clamp(1.5rem, 5vw, 4rem)"`, `"right": "clamp(1.5rem, 5vw, 4rem)"`. Do NOT use a fixed spacing token here — on a wide desktop it produces a cramped gutter, on a phone it overflows.
+- `styles.spacing.blockGap`: REQUIRED. Set a spacing token (e.g. `"var:preset|spacing|40"` cozy, `"var:preset|spacing|50"` editorial, `"var:preset|spacing|60"` magazine). This is the default vertical gap between sibling blocks in any default-layout container — the single most-leveraged setting for prose rhythm. Without it, paragraphs touch paragraphs and headings sit on the next paragraph. Block-specific overrides below still win where declared.
+
+## Template parts (REQUIRED)
+
+Declare `templateParts` with a `header` (area `header`) and a `footer` (area `footer`). Do not declare a sidebar entry unless the design direction is explicitly a sidebar/documentation layout — an unused part clutters the Site Editor with an empty slot. If the direction is a sidebar layout, add a `sidebar` part with `"area": "uncategorized"` and pin its width as a custom token under `settings.custom.sidebarWidth` (240–320px; 280px is a safe default), readable in CSS as `var(--wp--custom--sidebar-width)`.
+
+If the design direction is a single-page / landing direction with a sticky anchor nav, add `settings.custom.scrollPaddingTop` (e.g. `"80px"`) so anchor jumps clear the sticky header.
+
+## Element and block styles (REQUIRED — kill invisible-text bugs)
+
+Downstream block markup doesn't always declare every color and spacing property; WP grammar inheritance falls through to body defaults that may not contrast against tinted parent surfaces. Theme.json `styles.elements` and `styles.blocks` defaults catch every untouched block.
+
+**Paired-contrast rule — non-negotiable:** every `color` declaration in `styles` MUST set BOTH `background` and `text` together — never one alone. Same for every `:hover`. The "we forgot the text color and everything inherited to body white" bug class lives entirely in this gap. Use only slugs you already verified above.
+
+Declare at least:
+
+- `styles.color.background` and `styles.color.text`: the default page reading pair (the verified body-vs-background pair).
+- `styles.typography.fontFamily`: the `body` family slug; `styles.typography.fontSize`, `lineHeight`.
+- `styles.elements.heading.typography.fontFamily`: the `heading` family slug, plus per-level sizes via `styles.elements.h1` … `styles.elements.h6` (or `elements.heading` + descending sizes). Headings use the heading font; line-height tighter than body.
+- `styles.elements.link.color.text` AND `styles.elements.link.:hover.color.text`: declared together — links inherit from this; without the hover color, hover is invisible.
+- `styles.elements.button.color.background` AND `.color.text`, plus `styles.elements.button.:hover.color.{background,text}`: all declared together, all verified pairs, and the default pair must DIFFER from the hover pair or hover does nothing. Add `styles.elements.button.spacing.padding` (e.g. `{"top":"var:preset|spacing|20","bottom":"var:preset|spacing|20","left":"var:preset|spacing|40","right":"var:preset|spacing|40"}`) so buttons have a touchable surface, and `styles.elements.button.border.radius` matching the direction.
+- `styles.elements.caption.color.text`: the `muted` slug.
+
+Block-level defaults — WordPress flex/grid containers do NOT space children by default, and untouched blocks fall through to body inheritance:
+
+- `styles.blocks.core/button.color.background` + `.text` + `:hover.color.{background,text}` + `.spacing.padding` — same rules as the button element above; declare both so the block and element agree.
+- `styles.blocks.core/buttons.spacing.blockGap`: REQUIRED (e.g. `"var:preset|spacing|30"`). Without it, buttons in a row touch.
+- `styles.blocks.core/navigation.spacing.blockGap`: REQUIRED (e.g. `"var:preset|spacing|30"`; tighter `spacing|20` for industrial/brutalist directions, generous `spacing|40` for editorial/luxury). The nav block uses flex layout and does not space links by default — without this, header links butt together.
+- `styles.blocks.core/post-template.spacing.blockGap`: REQUIRED (e.g. `"var:preset|spacing|40"` cozy, `"var:preset|spacing|50"` generous). Without it, query-loop cards touch and any card border collapses into one stripe.
+- `styles.blocks.core/query.spacing.blockGap`: RECOMMENDED, generous (`var:preset|spacing|50` or `60`).
+- `styles.blocks.core/columns.spacing.blockGap`: RECOMMENDED — gap between columns when markup doesn't set it per-block.
+
+Tune every style to the chosen design direction's personality: border radii, the weight and rhythm of headings, the boldness of the accent, whether surfaces are flat or have subtle borders. The defaults you set here are what makes the site feel like one coherent design rather than a stack of default WordPress blocks.
+
+## Self-check before output
+
+- Valid JSON, `version: 3`, `$schema` present, four-space indent.
+- Every font in the design direction has a `fontFamilies` entry WITH `fontFace` and a `fonts.gstatic.com` woff2 `src` — fonts load with no enqueue file.
+- Every `color` block in `styles` sets both `background` and `text`; every `:hover` does too.
+- contentSize/wideSize, root-padding-aware alignments, horizontal-only body padding, and `blockGap` are all set.
+- All button, nav, post-template gaps are declared. No invisible-text gaps remain.
+- No emojis, no decorative comments — JSON only.
+
+Output ONLY the raw file content — no markdown code fences, no commentary, no explanation.
diff --git a/apps/cli/ai/skills/theme-architecture/SKILL.md b/apps/cli/ai/skills/theme-architecture/SKILL.md
new file mode 100644
index 0000000000..9c1394062e
--- /dev/null
+++ b/apps/cli/ai/skills/theme-architecture/SKILL.md
@@ -0,0 +1,243 @@
+---
+name: theme-architecture
+description: WordPress block-theme architecture for full site generation — theme = pure presentation, the layout-mode and content-mode taxonomy, theme.json/templates/parts conventions, and theme invariants. Load before planning or generating theme files.
+---
+
+# Theme Architecture
+
+Use this skill before planning a site's structure or writing any theme file (`theme.json`, `style.css`, templates, parts, `functions.php`). It defines how a generated WordPress block theme is shaped, which files to emit, and the invariants every file must hold.
+
+## The two-package model (read first)
+
+A generated site is **two packages**, never one:
+
+1. **A pure presentation theme** at `<site>/wp-content/themes/<slug>/`. It holds look and layout ONLY: `theme.json`, `style.css`, `templates/`, `parts/`, `patterns/` (rare), `assets/`, and a deliberately minimal `functions.php`.
+2. **A companion plugin** at `<site>/wp-content/plugins/<slug>-functionality/`. It holds ALL behavior: custom post types + taxonomies + post meta, REST API routes, and custom Gutenberg blocks.
+
+This split is non-negotiable. Behavior moved into the theme breaks on theme switch and pollutes presentation; presentation moved into the plugin is unreachable in the Site Editor. When you catch yourself about to register a CPT, a REST route, or a block inside the theme, **stop** — that work belongs in the companion plugin. Load the `companion-plugin` skill for how to build it.
+
+What the theme MUST NOT contain:
+
+- No custom post types, taxonomies, or post meta.
+- No REST API routes.
+- No block registration (`register_block_type`) and no custom block source.
+- No content seeding — no `wp_insert_post` loops, no `content/*.html` files, no `after_switch_theme` seeders. Content is seeded into the live database (next section).
+- No font enqueue file (`fonts.php`) and no `wp_enqueue_style` for Google Fonts. Fonts are declared in `theme.json` via `settings.typography.fontFamilies[].fontFace` (see "Fonts live in theme.json").
+
+What `functions.php` MAY contain (and nothing more):
+
+```php
+<?php
+add_action( 'wp_enqueue_scripts', function () {
+    wp_enqueue_style(
+        '<slug>-style',
+        get_stylesheet_uri(),
+        array(),
+        wp_get_theme()->get( 'Version' )
+    );
+} );
+
+add_action( 'after_setup_theme', function () {
+    add_editor_style( 'style.css' );
+} );
+```
+
+That is the whole theme `functions.php`: enqueue `style.css` on the front end, and `add_editor_style` so the editor matches. If a section needs JavaScript (scroll animation, sticky shrink-on-scroll), enqueue a small front-end script here too — but the script is progressive enhancement, not behavior (see invariants). Anything stateful goes to the plugin.
+
+## Content is seeded into the live database
+
+The model writes real files to disk and seeds content into the running WordPress DB via WP-CLI / the `seed_content` tool — content is NEVER baked into the theme.
+
+- Pages (Home, About, Contact, Services, etc.) are inserted as published pages in the database. The home page is set as the static front page by setting `show_on_front` = `page` and `page_on_front` to its ID.
+- CPT entries (portfolio items, team members, menu items, testimonials) are inserted as posts of their type — registered by the companion plugin — and seeded into the DB.
+- Blog posts, categories, and tags are created in the DB.
+
+There is no `content-loader.php`, no `<!-- meta -->` header convention, no `theme:./assets/...` reference rewriting, no `page-url-rewrite.php` / `post-url-rewrite.php`. Pages link to each other with normal site-root-relative permalinks (`/about/`), which resolve correctly on a real Studio site. Images referenced by seeded content are real media-library attachments or real theme asset URLs, not placeholder tokens.
+
+The theme's templates are thin shells (below); the rich content they display comes from the seeded database, queried by core blocks (`core/post-content`, `core/query`).
+
+## File layout
+
+```
+wp-content/themes/<slug>/
+  theme.json            design tokens — single source of truth
+  style.css             theme header + custom CSS (polish, motion, layout utilities)
+  functions.php         minimal: enqueue style.css + add_editor_style (+ optional PE script)
+  templates/
+    index.html          required — fallback / blog-or-archive landing
+    front-page.html     static homepage shell (homepage-and-pages mode)
+    page.html           required — single page shell
+    single.html         when there are posts or content CPTs
+    archive.html        when there are posts or content CPTs
+    404.html, search.html  optional but recommended
+  parts/
+    header.html         required — site-title + navigation
+    footer.html         required — credit + nav/meta
+    sidebar.html        only in sidebar-left / sidebar-right / dual-sidebar
+    right-sidebar.html  only in dual-sidebar
+  patterns/             rare — only when explicitly requested
+  assets/               fonts (woff2), images, svg
+```
+
+Emit visible-first for a good live preview: `theme.json` → `style.css` → `parts/header.html` → `parts/footer.html` → `templates/front-page.html` (or `index.html`) → remaining templates → assets. The homepage's rich content is seeded into the DB, not written as a file.
+
+## layout-mode drives the page frame
+
+`layoutMode` (from the site spec) decides the overall page shape. Every template, part, and the `style.css` grid branch on it. Read the spec's value and pick one branch — do not mix.
+
+- **`vertical-stack`** (default): header band on top, main in the middle, footer at the bottom. Primary nav in the header. theme.json declares `header` + `footer` template parts only.
+- **`sidebar-left` / `sidebar-right`**: a fixed sidebar flanking a scrolling main column. The sidebar holds the site title + primary nav (and optional footer credit). The header is omitted or reduced to a thin utility top-bar inside `.main-content-area`. theme.json adds a `sidebar` part (`area: uncategorized`) and a `settings.custom.sidebarWidth` token (240–320px, 280px default). The CSS grid lives at `.wp-site-blocks` level. Never duplicate the sidebar inside the page body — the template grid pins it.
+- **`dual-sidebar`**: three-column documentation chrome. Left sidebar = site title + nav tree; right rail = per-page TOC / metadata. Main scrolls between. theme.json declares `header`, `sidebar`, `right-sidebar`, `footer`; tokens `sidebarWidth` (240–280px) and `rightSidebarWidth` (220–260px); tighten `contentSize` to 680–760px.
+- **`landing-page`**: single-viewport one-pager. Every route renders the same composition: hero + 3–6 anchor-linked sections (`#features`, `#pricing`, `#faq`, `#signup`). Nav uses anchor links, not page links. theme.json declares `header` + `footer` and a `settings.custom.scrollPaddingTop` token (e.g. `"80px"`) applied as `html { scroll-padding-top: var(--wp--custom--scroll-padding-top); }`.
+- **`magazine-grid`**: the homepage IS the post archive — a tiled grid of latest posts, no marketing hero above it. Thin masthead band (wordmark + category nav). theme.json: `contentSize` 700–760px, `wideSize` 1280–1440px, generous `core/post-template.spacing.blockGap` (`var:preset|spacing|50`+).
+- **`canvas-floating-chrome`**: full-bleed gallery / portfolio. Imagery reaches all four viewport edges; the only chrome is a small `position:fixed` floating module (wordmark + menu link) overlaid on content. theme.json sets `styles.spacing.padding.left` AND `.right` to `"0"` (NO clamp), keeps `useRootPaddingAwareAlignments: true`, and sets a mid-gray `core/site-title.color.text` so the wordmark survives any `mix-blend-mode: difference` filter.
+
+When the prompt gives no explicit cue for a non-default mode, pick `vertical-stack`.
+
+## content-mode drives which templates and the homepage shape
+
+`contentMode` decides whether the site is marketing-first, blog-first, or has no front page.
+
+- **`homepage-and-pages`** (default): a static front page plus interior pages. Seed a Home page into the DB and set it as the front page. `templates/front-page.html` (or `index.html`) is a **thin shell**:
+
+  ```html
+  <!-- wp:template-part {"slug":"header","tagName":"header"} /-->
+  <!-- wp:group {"tagName":"main","style":{"spacing":{"margin":{"top":"0"}}}} -->
+  <main class="wp-block-group">
+      <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
+  </main>
+  <!-- /wp:group -->
+  <!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
+  ```
+
+  The outer `<main>` carries no layout (default) so a full-bleed hero in the seeded home page renders edge-to-edge; `core/post-content` carries the constrained layout for readable body width. The rich homepage composition lives in the seeded page's content, NOT in the template.
+
+- **`blog-first`**: the post stream is the experience. A small intro home page is optional (ship one only when the user wants a marketing intro alongside the blog). Otherwise drop `front-page.html` and let `index.html` show the post stream at `/`.
+
+- **`index-only-no-homepage`**: the user opted out of a marketing landing. Do NOT seed a Home page and do NOT emit `front-page.html`. `templates/index.html` becomes the landing — a composed masthead (heading + one-line tagline) above a `core/query` loop of recent posts, with `postType: "post"` and `inherit: true` so category/tag archives reuse the same template. NO `core/post-content` shell in this mode.
+
+In sidebar modes, wrap whichever shell applies in the sidebar grid: sidebar part(s) flanking a `.main-content-area` group that holds the optional top-bar + `<main>` + footer.
+
+Template coverage: always emit `page.html`. Emit `single.html` and `archive.html` when there are posts or content CPTs (registered by the companion plugin). Content-CPT archives/singles display entries via `core/post-content` (or `core/post-featured-image` where the design calls for it), reading from the seeded DB.
+
+## header-behavior
+
+The spec carries a `headerBehavior` object — `position`, `overlayHero`, `scrolledBackground`, `shrinkOnScroll`. The header part, `style.css`, and any PE script must agree on these.
+
+- **`position`**: `"sticky"` only when the design shows persistent top nav across the scroll range; else `"static"`. Sticky goes on the template-part wrapper, not the inner group (see sticky invariant).
+- **`overlayHero`**: `true` only when the header sits visually ON TOP OF a full-bleed hero (transparent header over imagery/color reaching the very top). A tall light-on-light header is NOT overlay. When `true`, the header part has no background until scrolled, and the hero sits flush against it (zero gap — no top margin/padding on the hero, no bottom margin/padding on the header).
+- **`scrolledBackground`**: required when sticky. `"opaque-surface"` (crisp) or `"translucent-blur"` (glassmorphic backdrop-blur). `"none"` only when static or already-solid.
+- **`shrinkOnScroll`**: `true` only when the design shows a reduced scrolled header. The PE script toggles `.is-shrunk` on the inner group; `style.css` defines the shrunk state.
+
+When `layoutMode` starts with `sidebar-`, force `{ "position": "static", "overlayHero": false, "scrolledBackground": "none", "shrinkOnScroll": false }` — the sidebar is the chrome, the header can't overlay or stick.
+
+## theme.json token discipline
+
+`theme.json` is the single source of truth. Every color, font, size, and spacing value used in block markup and `style.css` references a token declared here. No hardcoded hex, px, or font names in block attributes; CSS reads tokens as `var(--wp--preset--color--<slug>)`, `var(--wp--preset--font-family--<slug>)`, `var(--wp--preset--spacing--<n>)`.
+
+**Color palette** — declare a complete, self-contained palette and verify WCAG AA before finalizing:
+
+- Body text vs page background ≥ 4.5:1 (aim 7:1).
+- Any heading / muted slug ≥ 4.5:1 against every background AND surface/card slug it could render on.
+- Button label vs button surface ≥ 4.5:1 (check both light-on-light and dark-on-dark).
+- Reserve saturated accents for borders, icons, button surfaces, large display headings — not body copy.
+- No two slugs within ~25 lightness steps for normal-weight text. Catch contrast failures here, not in `style.css` — downstream files trust the palette to be readable and there is no recovery later.
+
+**Typography** — pick distinctive, characterful fonts (avoid Inter / Roboto / Arial / system defaults). Pair a display font with a refined body font.
+
+- Font size scale stays grounded: body 1rem, headings scale modestly, cap display at ~3.5rem via `clamp(2.5rem, 4vw, 3.5rem)`. Avoid sizes above 4rem. A good 6-step scale: `0.875 / 1 / 1.25 / 1.75 / 2.25 / clamp(2.5rem, 4vw, 3.5rem)`.
+- Line height: body 1.5–1.65, headings 1.1–1.3, never below 1.0. Set via `styles.typography.lineHeight` and `styles.elements.heading.typography.lineHeight`.
+
+**Spacing scale** — declare a `spacingScale` (or explicit `spacingSizes`) and set:
+
+- `styles.spacing.blockGap` (REQUIRED) — site-wide vertical rhythm between sibling blocks (`var:preset|spacing|40` cozy, `50` editorial, `60` magazine). This is the single most-leveraged setting for prose rhythm.
+- `styles.blocks.core/navigation.spacing.blockGap`, `core/buttons.spacing.blockGap`, `core/post-template.spacing.blockGap` (all REQUIRED) — WP flex/grid layouts have no default gap; without these, nav items, buttons, and cards touch.
+
+**Layout** (REQUIRED — wires alignments):
+
+- `settings.layout.contentSize` 800–960px (prose width); `wideSize` 1200–1400px (hero/grid clamp). Tighten `contentSize` for dual-sidebar (680–760) and magazine-grid (700–760).
+- `settings.useRootPaddingAwareAlignments: true` — without it, `align:wide`/`align:full` inherit body padding and never reach the edge.
+- `styles.spacing.padding`: set horizontal only via fluid clamp (`"left"/"right": "clamp(1.5rem, 5vw, 4rem)"`), `top`/`bottom` to `"0"`. Exception: `canvas-floating-chrome` sets left/right to `"0"`. Never add horizontal padding to `<main>`, page groups, or template shells — that double-pads. Sections break out via `align`, never via wrapper padding.
+
+**Block-level defaults** (REQUIRED — defends against inheritance):
+
+- `styles.blocks.core/button.color.{background,text}` declared TOGETHER, plus a distinct `:hover.color.{background,text}` pair, plus `spacing.padding`.
+- `styles.elements.link.color.text` AND `.:hover.color.text` together.
+- Paired-contrast rule: every `styles.blocks.<block>.color` sets BOTH background and text — never one alone.
+
+## Fonts live in theme.json
+
+Declare every font in `theme.json` under `settings.typography.fontFamilies`, each with a `fontFace` array pointing at bundled woff2 files in `assets/`. Do NOT enqueue Google Fonts and do NOT ship a `fonts.php`.
+
+```json
+{
+  "settings": {
+    "typography": {
+      "fontFamilies": [
+        {
+          "fontFamily": "\"Fraunces\", serif",
+          "name": "Fraunces",
+          "slug": "display",
+          "fontFace": [
+            {
+              "fontFamily": "Fraunces",
+              "fontWeight": "400 700",
+              "fontStyle": "normal",
+              "src": [ "file:./assets/fonts/fraunces.woff2" ]
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+This loads the font in both front end and editor with no enqueue code, and keeps the theme self-contained and offline-capable.
+
+## Theme invariants (apply to every file)
+
+These are absolute unless the user's original request explicitly overrides one.
+
+**Block markup**
+
+- Prefer core blocks for content (`core/group`, `core/columns`, `core/cover`, `core/media-text`, `core/heading`, `core/paragraph`, `core/buttons`, `core/query`, `core/gallery`, `core/details`). Custom blocks (in the companion plugin) are for named interactive features only.
+- Custom classNames go ONLY on the outermost block wrapper via the block `className` attribute — never on inner DOM elements. Section identity lives in `className`, not in decorative HTML comments.
+- Full-bleed sections use an outer `core/group` with `"align":"full"`. Every top-level section MUST declare an `align` (`"full"` for edge-to-edge bands, `"wide"` for most sections); default alignment is reserved for inner content holders only. A section with no `align` renders as a narrow column — that's the symptom of forgetting it.
+- Section containers use `"layout":{"type":"default"}` (or omit layout); only inner content holders that wrap readable prose use `"layout":{"type":"constrained"}`. Never put constrained on the section container or page root.
+- Every top-level group resets top margin: `"style":{"spacing":{"margin":{"top":"0"}}}`.
+- No `core/html` for content sections — only for exotic decoration (an embed core blocks can't express). No `<inner-blocks>` placeholders; emit full expanded markup.
+- No decorative HTML comments — only WordPress block delimiter comments. No emojis anywhere (and no `:)` / `<3` auto-emoji glyphs). Use custom SVG for icons.
+
+**Color pairing (the invisible-text rule)** — WordPress inheritance is unreliable; a child whose text color falls through to the body default renders invisible on any non-default surface. Defend block-level:
+
+- When a block declares `backgroundColor` (or `style.color.background`), it MUST also declare `textColor` (or `style.color.text`). No exceptions, at every level.
+- When a block declares `style.border.width`, it MUST also declare `borderColor` (a palette slug).
+- `core/button` MUST declare both background and text colors; `is-style-outline` buttons MUST declare `textColor` AND `borderColor` together.
+- `core/navigation` MUST declare ALL FIVE: `textColor`, `style.elements.link.color.text`, `overlayBackgroundColor`, `overlayTextColor`, and `style.spacing.blockGap`. Missing any one breaks at least one render mode — the mobile overlay defaulting to invisible is the canonical nav bug.
+- Any block with `layout.type:"grid"` or `"flex"` MUST declare `style.spacing.blockGap`.
+
+**Sticky positioning** — apply `position: sticky` to the template-part wrapper, never the inner group. The inner group is the only child of `<header class="wp-block-template-part">`, so making it sticky gives it ~0px of scroll room (looks broken). Target the wrapper, whose containing block is the page-height `.wp-site-blocks`:
+
+```css
+.wp-site-blocks > header.wp-block-template-part {
+    position: sticky;
+    top: 0;
+    z-index: 100;
+}
+```
+
+Keep visual transitions and any JS-toggled `.is-shrunk` class on the inner group. Ensure no ancestor between the sticky element and the viewport has `overflow` other than `visible` (a common `body { overflow-x: hidden }` or `.wp-site-blocks { overflow: clip }` silently kills sticky — override to `overflow: visible` if so).
+
+**Scroll animations (progressive enhancement)** — CSS defines the FINAL visible state; JS adds the initial hidden state (so the content is visible with JS disabled). Every animation respects `@media (prefers-reduced-motion: reduce)`. The optional PE script enqueued from theme `functions.php` adds initial classes and toggles reveal on scroll with a passive, null-checked listener. This is presentation enhancement, not behavior — never use the Interactivity API; behavior goes to the companion plugin.
+
+**Design tokens** — all colors, sizes, fonts, spacing referenced by slug/variable, never hardcoded. `style.css` custom CSS is reserved for polish (typography detail, link/button variants, image effects, motion) and named layout utilities — not for re-implementing layout that the editor handles.
+
+**Footer credit** — include a credit line in the footer, styled to match the theme (font size, color). Compose its position freely; presence is the constraint.
+
+## Cross-references
+
+- Behavior (CPTs, taxonomies, post meta, REST routes, custom blocks): load the `companion-plugin` skill. Custom blocks there are build-less plain JS (`block.json` + plain `view.js`/`editor.js` calling `wp.blocks.registerBlockType` with `wp.element.createElement`, registered via `register_block_type`) — never JSX, never `@wordpress/scripts`, never the Interactivity API.
+- Writing block markup for pages/templates/parts: load `block-content`.
+- Determining `layoutMode` / `contentMode` / `headerBehavior` from the user prompt: load `site-spec`.
+- Aesthetic direction (palette, type, motion): load `visual-design`.
diff --git a/apps/cli/ai/skills/wp-best-practices/SKILL.md b/apps/cli/ai/skills/wp-best-practices/SKILL.md
new file mode 100644
index 0000000000..287e598ee2
--- /dev/null
+++ b/apps/cli/ai/skills/wp-best-practices/SKILL.md
@@ -0,0 +1,393 @@
+---
+name: wp-best-practices
+description: WordPress code-quality rules for generated PHP — output escaping, input sanitization, nonces and capability checks, performance, and type safety. Load before writing or reviewing companion-plugin PHP.
+---
+
+# WordPress Code Quality Rules
+
+Every line of PHP you write for a generated site MUST follow the rules below. These are not stylistic preferences — they are correctness, security, and performance constraints that protect the people who will run the generated site. Violating any rule is a defect, not a nitpick.
+
+## Where this applies
+
+A generated site is two packages:
+
+- A **pure presentation theme** at `<site>/wp-content/themes/<slug>/`. Its `functions.php` is minimal — only enqueue `style.css` on the front end and call `add_editor_style`. It has no custom post types, no REST routes, no block registration, and no content seeding. There is almost no security-sensitive PHP here.
+- A **companion plugin** at `<site>/wp-content/plugins/<slug>-functionality/`. ALL behavior lives here: custom post types, taxonomies, post meta, REST API routes, and custom Gutenberg blocks (build-less plain JS registered server-side with `register_block_type`). **This is where every rule below earns its keep.** If you are writing PHP that touches `$_POST`, the database, a REST request, or user capabilities, you are in the companion plugin and these rules are mandatory.
+
+Content is seeded into the live WordPress database via WP-CLI / the seed-content tool — never baked into theme files. So "input" below means input arriving at a live request (form posts, REST bodies, query args), not build-time data.
+
+When the rules below mention `<slug>` or `'textdomain'`, substitute the site's actual slug. The theme text domain is the theme slug; the plugin text domain is `<slug>-functionality` (or whatever the plugin header declares).
+
+---
+
+## Security rules
+
+### 1. Escape every output
+
+Choose the escape function by **output context**, not by what feels safe. The same value escaped for HTML text is not safe inside an attribute or a URL.
+
+```php
+echo esc_html( $title );          // text between HTML tags
+echo esc_attr( $value );          // values inside an attribute
+echo esc_url( $href );            // URLs in href / src / action
+echo wp_kses_post( $rich_html );  // post-content HTML (allows <a>, <strong>, <em>, etc.)
+echo esc_js( $js_string );        // strings injected into inline JS
+echo esc_textarea( $multiline );  // textarea content
+```
+
+Never echo a variable directly. Even data you "control" (an option you set, a post title) can be changed by another plugin, another admin, or a future you.
+
+```php
+// WRONG
+echo '<h2 class="event-title">' . $title . '</h2>';
+echo '<a href="' . $cta_url . '">' . $cta_label . '</a>';
+
+// RIGHT
+printf(
+    '<h2 class="event-title">%s</h2>',
+    esc_html( $title )
+);
+printf(
+    '<a href="%s">%s</a>',
+    esc_url( $cta_url ),
+    esc_html( $cta_label )
+);
+```
+
+When you output a translated string, escape the **result** of the translation, not the literal:
+
+```php
+echo esc_html__( 'Submit', 'textdomain' );   // returns the escaped, translated string
+esc_html_e( 'Submit', 'textdomain' );          // echoes it directly
+```
+
+In a block `render_callback` (the typical companion-plugin block), the same rule holds — every interpolated attribute or meta value passes through an `esc_*` function before it reaches the markup string you return.
+
+### 2. Sanitize every input
+
+Sanitize on the way in, with the function that matches the data type. Never trust `$_POST`, `$_GET`, `$_REQUEST`, `$_COOKIE`, or `$_SERVER` directly.
+
+```php
+$title   = sanitize_text_field( wp_unslash( $_POST['title'] ?? '' ) );
+$email   = sanitize_email( wp_unslash( $_POST['email'] ?? '' ) );
+$content = wp_kses_post( wp_unslash( $_POST['content'] ?? '' ) ); // rich HTML, strips disallowed tags
+$count   = absint( $_POST['count'] ?? 0 );
+$slug    = sanitize_title( wp_unslash( $_POST['slug'] ?? '' ) );  // URL slugs only — lossy on prose
+$key     = sanitize_key( wp_unslash( $_POST['key'] ?? '' ) );
+$file    = sanitize_file_name( wp_unslash( $_POST['file'] ?? '' ) );
+$url     = esc_url_raw( wp_unslash( $_POST['url'] ?? '' ) );      // sanitize-for-storage variant of esc_url
+$int     = (int) ( $_POST['qty'] ?? 0 );
+```
+
+`wp_unslash` first (WordPress adds slashes to superglobals), then sanitize. Use `?? ''` / `?? 0` so a missing key never becomes a PHP warning.
+
+Notes:
+- `wp_kses_post` is both a sanitizer and an escaper for post-content HTML. Content stored after `wp_kses_post` is safe to echo directly **only in post-content context**. Put that same value in an attribute or URL and you still need `esc_attr` / `esc_url`.
+- `sanitize_text_field` collapses whitespace and strips tags — wrong for multi-line input; use `sanitize_textarea_field` for that.
+
+```php
+// WRONG — trusts raw input, no unslash
+$name = $_POST['name'];
+update_post_meta( $post_id, '_attendee_name', $name );
+
+// RIGHT
+$name = sanitize_text_field( wp_unslash( $_POST['name'] ?? '' ) );
+update_post_meta( $post_id, '_attendee_name', $name );
+```
+
+### 3. Nonce AND capability on every state change — in the same callback
+
+Every form submission and every REST write endpoint MUST verify a nonce **and** check a capability, **in the same callback**. Splitting them across functions invites an endpoint that has one check but not the other. A nonce proves the request came from your UI; a capability proves the user is allowed to do it. You need both.
+
+```php
+// Admin form / AJAX handler
+function handle_rsvp_submit(): void {
+    if (
+        ! isset( $_POST['rsvp_nonce'] )
+        || ! wp_verify_nonce( sanitize_key( $_POST['rsvp_nonce'] ), 'rsvp_action' )
+    ) {
+        wp_die( esc_html__( 'Security check failed.', 'textdomain' ) );
+    }
+    if ( ! current_user_can( 'edit_posts' ) ) {
+        wp_die( esc_html__( 'You are not allowed to do this.', 'textdomain' ) );
+    }
+    // ...mutate state...
+}
+```
+
+Emit the nonce field in the form with `wp_nonce_field( 'rsvp_action', 'rsvp_nonce' )`.
+
+For REST endpoints the `permission_callback` is where this lives:
+
+```php
+// WRONG — write endpoint with no permission gate. This is publicly writable.
+register_rest_route( '<slug>/v1', '/rsvp', [
+    'methods'  => 'POST',
+    'callback' => 'create_rsvp',
+    // missing permission_callback entirely
+] );
+
+// WRONG — never do this; it disables the gate.
+'permission_callback' => '__return_true',  // only acceptable for genuinely public READ endpoints
+```
+
+```php
+// RIGHT — nonce + capability, returning WP_Error so the client learns what failed.
+register_rest_route( '<slug>/v1', '/rsvp', [
+    'methods'             => WP_REST_Server::CREATABLE, // 'POST'
+    'callback'            => 'create_rsvp',
+    'permission_callback' => 'rsvp_can_create',
+    'args'                => [
+        'event_id' => [
+            'type'              => 'integer',
+            'required'          => true,
+            'sanitize_callback' => 'absint',
+        ],
+        'email' => [
+            'type'              => 'string',
+            'required'          => true,
+            'sanitize_callback' => 'sanitize_email',
+            'validate_callback' => static fn( $v ): bool => is_email( $v ) !== false,
+        ],
+    ],
+] );
+
+function rsvp_can_create( WP_REST_Request $request ): bool|WP_Error {
+    if ( ! wp_verify_nonce( (string) $request->get_header( 'X-WP-Nonce' ), 'wp_rest' ) ) {
+        return new WP_Error(
+            'rest_forbidden',
+            __( 'Nonce verification failed.', 'textdomain' ),
+            [ 'status' => 401 ]
+        );
+    }
+    if ( ! current_user_can( 'edit_posts' ) ) {
+        return new WP_Error(
+            'rest_forbidden',
+            __( 'You are not allowed to do this.', 'textdomain' ),
+            [ 'status' => 403 ]
+        );
+    }
+    return true;
+}
+```
+
+### 4. REST `permission_callback` discipline
+
+- Every `register_rest_route` call MUST include a `permission_callback`. Omitting it triggers a `_doing_it_wrong()` notice and, worse, leaves the route ungated.
+- Read-only public endpoints (e.g. a list of published events) may use `'__return_true'` — but only after you confirm the data is genuinely public. Default to a real check.
+- Return `bool|WP_Error`, never a bare `false`. WordPress turns bare `false` into a generic 403 with no message; the client has no signal about *what* failed (not logged in? wrong role? bad nonce?). A `WP_Error` carries a code, a message, and a status.
+- Validate and sanitize per-argument via the `args` schema (`sanitize_callback`, `validate_callback`, `required`, `type`). This runs before your callback, so the callback receives clean data.
+- The capability in `permission_callback` MUST match the capability your editor/UI uses to decide whether to show the control — otherwise the button appears, the user clicks, and the request fails.
+
+### 5. Use prepared statements
+
+If you ever touch `$wpdb` directly (most companion plugins should prefer `WP_Query`, `get_posts`, `get_post_meta`, and the REST/CPT APIs), never concatenate input into SQL.
+
+```php
+// WRONG
+$wpdb->query( "SELECT * FROM {$wpdb->posts} WHERE ID = $id" );
+
+// RIGHT
+$rows = $wpdb->get_results(
+    $wpdb->prepare(
+        "SELECT ID, post_title FROM {$wpdb->posts} WHERE post_author = %d AND post_status = %s",
+        $author_id,
+        'publish'
+    )
+);
+```
+
+`%d` for integers, `%s` for strings, `%f` for floats. Table names come from `$wpdb` properties, not from input.
+
+### 6. Prefer the Abilities API for recurring permission boundaries
+
+When the same capability check appears in more than one place, needs to be auditable, REST-discoverable (so the editor can ask "can I do this?" before showing UI), or finer-grained than built-in caps, register a named **Ability** instead of scattering `current_user_can()` calls.
+
+Hook order is strict: register **categories** on `wp_abilities_api_categories_init`, then **abilities** on `wp_abilities_api_init`. Registering an ability outside `wp_abilities_api_init` triggers `_doing_it_wrong()` and silently fails.
+
+```php
+add_action( 'wp_abilities_api_categories_init', static function (): void {
+    wp_register_ability_category( '<slug>', [
+        'label' => __( 'Site Features', 'textdomain' ),
+    ] );
+} );
+
+add_action( 'wp_abilities_api_init', static function (): void {
+    wp_register_ability( '<slug>/publish-event', [
+        'label'               => __( 'Publish Event', 'textdomain' ),
+        'description'         => __( 'Publishes a draft event.', 'textdomain' ),
+        'category'            => '<slug>',
+        'execute_callback'    => static function ( array $args ): array {
+            $id = wp_update_post( [ 'ID' => (int) $args['id'], 'post_status' => 'publish' ], true );
+            return [ 'published' => ! is_wp_error( $id ) ];
+        },
+        // bool|WP_Error — required for anything that mutates data.
+        'permission_callback' => static function (): bool|WP_Error {
+            if ( ! current_user_can( 'publish_posts' ) ) {
+                return new WP_Error( 'rest_forbidden', __( 'You cannot publish.', 'textdomain' ), [ 'status' => 403 ] );
+            }
+            return true;
+        },
+        'input_schema'        => [
+            'type'       => 'object',
+            'properties' => [ 'id' => [ 'type' => 'integer' ] ],
+            'required'   => [ 'id' ],
+        ],
+        'meta'                => [ 'show_in_rest' => true ],
+    ] );
+} );
+```
+
+Abilities with `meta.show_in_rest => true` appear under `/wp-json/wp-abilities/v1/abilities`. The REST layer applies `permission_callback` automatically — if the editor's `getAbility( name )` returns `undefined`, the user cannot run it, so the UI stays in sync with permissions. The Abilities API ships in WordPress 6.9+; for earlier targets, feature-detect before registering. Abilities **complement** sanitization and escaping — they do not replace either. For one-off gates with no UI implications, a plain `current_user_can()` check is fine.
+
+---
+
+## Performance rules
+
+### 1. Never autoload large options
+
+Options with autoload on are loaded into memory on **every** request. The default autoloads, which is the wrong default for anything bigger than a few hundred bytes. Pass `false` to keep it out of the autoload set (the old `'yes'`/`'no'` string forms are deprecated as of WP 6.6).
+
+```php
+// WRONG — a multi-KB blob loaded on every page view, forever
+add_option( 'mysite_event_cache', $big_array );
+
+// RIGHT — third arg is the deprecated $deprecated (always ''), fourth is autoload.
+add_option( 'mysite_event_cache', $big_array, '', false );
+update_option( 'mysite_event_cache', $big_array, false );
+```
+
+Rule of thumb: autoload only options under ~1 KB that are genuinely read on every page load. Plugin settings that are small and read everywhere can autoload; caches, logs, and serialized blobs must not.
+
+### 2. Cache expensive operations with transients
+
+Wrap slow queries, external API calls, and computed values in a transient.
+
+```php
+$key   = 'mysite_upcoming_events';
+$value = get_transient( $key );
+
+if ( false === $value ) {
+    $value = compute_upcoming_events(); // DB-heavy query, REST call, etc.
+    set_transient( $key, $value, HOUR_IN_SECONDS );
+}
+```
+
+Invalidate on the relevant hooks (`save_post`, `deleted_post`, `wp_update_user`) — `delete_transient( $key )` — rather than relying on the TTL alone for correctness.
+
+### 3. Bound every WP_Query
+
+Never use `'posts_per_page' => -1` on data that can grow without limit (this is the most common cause of memory-exhaustion crashes on generated sites). Set an explicit bound. Disable the counters and caches you do not use — but **only** disable the meta/term caches if the loop body never calls `get_post_meta()` / `get_the_terms()`, because disabling them and then calling those functions per-row produces N+1 queries that are worse than the default.
+
+```php
+$query = new WP_Query( [
+    'post_type'              => 'event',
+    'post_status'            => 'publish',
+    'posts_per_page'         => 12,      // explicit bound, never -1 on unbounded data
+    'no_found_rows'          => true,    // skip SQL_CALC_FOUND_ROWS when you don't paginate
+    'update_post_meta_cache' => false,   // ONLY if the loop body never calls get_post_meta()
+    'update_post_term_cache' => false,   // ONLY if the loop body never calls get_the_terms()
+    'fields'                 => 'ids',   // when you only need IDs
+] );
+```
+
+If you *do* read meta in the loop, leave `update_post_meta_cache` at its default (`true`) so WordPress batch-primes the cache in one query.
+
+### 4. Never run a query inside the loop
+
+Pre-fetch everything before `while ( $query->have_posts() )`, or rely on the primed caches above. A query per iteration is an N+1 problem.
+
+```php
+// WRONG — one extra query per post
+while ( $query->have_posts() ) {
+    $query->the_post();
+    $author = get_userdata( get_the_author_meta( 'ID' ) ); // queried every iteration
+}
+
+// RIGHT — gather IDs first, fetch authors in one pass, look up from the map.
+```
+
+### 5. HTTP calls: timeout, check, fail safely, cache
+
+Never use `file_get_contents()` for remote URLs. Use `wp_remote_get()` / `wp_remote_post()` with an explicit timeout, check for errors, and degrade gracefully — a remote failure must never break the page.
+
+```php
+$response = wp_remote_get( $url, [
+    'timeout'   => 10,
+    'sslverify' => true,
+] );
+
+if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
+    return $fallback; // never let a third party take the page down
+}
+
+$body = json_decode( wp_remote_retrieve_body( $response ), true );
+```
+
+Cache the result in a transient so you are not hitting the remote on every request.
+
+---
+
+## Type safety rules
+
+### 1. Type every signature
+
+Parameter types **and** a return type on every function and method. `void` for functions that return nothing; `?Type` for nullable.
+
+```php
+public function create_attendee( int $event_id, string $email, ?string $name = null ): int|WP_Error {
+    // ...
+}
+
+private function flush_cache(): void {
+    delete_transient( 'mysite_upcoming_events' );
+}
+```
+
+### 2. PHPDoc array shapes
+
+A bare `array` tells the reader nothing. Document the shape with array-shape syntax.
+
+```php
+/**
+ * @param array{id: int, label: string, items: array<int, string>} $config
+ * @return array<int, WP_Post>
+ */
+public function build( array $config ): array {
+    // ...
+}
+```
+
+### 3. Avoid `mixed`
+
+If you reach for `mixed`, the function is usually doing two things at once. Split it or narrow the type. Reserve `mixed` for genuine pass-through (e.g. a generic cache getter) and even then document the real shapes in PHPDoc.
+
+### 4. JavaScript (build-less block view/editor scripts): typed JSDoc on exports
+
+Custom blocks live in the companion plugin as plain-JS `view.js` / `editor.js` that call `wp.blocks.registerBlockType` via `wp.element.createElement` (no JSX, no `@wordpress/scripts`, no build step, never the Interactivity API — plain JS and standard DOM APIs only). Annotate exported and shared functions with JSDoc.
+
+```javascript
+/**
+ * @param {string} name
+ * @param {{count: number, items: string[]}} options
+ * @returns {Promise<boolean>}
+ */
+function register( name, options ) {
+    // ...
+}
+```
+
+---
+
+## Pre-ship checklist
+
+- [ ] Every output passes through an `esc_*` / `wp_kses_*` function chosen for its context.
+- [ ] Every input passes through `wp_unslash` then a `sanitize_*` / `wp_kses_*` function.
+- [ ] Every form and every REST/AJAX write verifies a nonce **and** a capability in the same callback.
+- [ ] Every `register_rest_route` has a real `permission_callback` returning `bool|WP_Error` (not bare `false`, not a stray `__return_true` on a write route).
+- [ ] No `$wpdb` query without `$wpdb->prepare()` for any interpolated value.
+- [ ] No `add_option()` / `update_option()` autoloading anything larger than a few hundred bytes.
+- [ ] No `'posts_per_page' => -1` on unbounded data; queries are bounded and unused caches disabled only when safe.
+- [ ] No `file_get_contents()` for HTTP — `wp_remote_get()` with timeout, error check, fallback, and a transient.
+- [ ] Every function signature has parameter types and a return type; array params/returns have PHPDoc shapes.
+- [ ] No `mixed` unless genuinely unavoidable and documented.
diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts
index ff3b099c06..a60919ba42 100644
--- a/apps/cli/ai/system-prompt.ts
+++ b/apps/cli/ai/system-prompt.ts
@@ -214,6 +214,8 @@ const REMOTE_DESIGN_GUIDELINES = `## Design capabilities by plan
 
 const LOCAL_SKILL_ROUTING = `## Skill routing
 
+For building a COMPLETE new site or theme from a description ("build me a site for…", "make a website", "generate a theme"), load the \`site-generator\` skill FIRST. It runs the full pipeline — spec → design directions → parallel theme generation (generate_theme) → companion plugin (generate_companion_plugin) → content seeding (seed_content) → AI imagery (generate_image) → validation. It produces a pure-presentation theme plus a companion plugin for behaviour, rather than hand-writing files one per turn.
+
 For any site creation, redesign, landing page, homepage, layout, style, CSS, typography, color, motion, or visual polish work, load the \`visual-design\` skill before writing design files or block markup.
 
 For any page/post content, template or template-part content, block markup, block-theme layout, full-width section, or \`core/html\` use, load the \`block-content\` skill before writing markup or validating block content.
diff --git a/apps/cli/ai/tests/wsg-generation.test.ts b/apps/cli/ai/tests/wsg-generation.test.ts
new file mode 100644
index 0000000000..081644f4ca
--- /dev/null
+++ b/apps/cli/ai/tests/wsg-generation.test.ts
@@ -0,0 +1,211 @@
+import { describe, expect, it } from 'vitest';
+import {
+	findAiImages,
+	getAttr,
+	parseAiImageAlt,
+	stripAiImagePlaceholders,
+} from 'cli/ai/generation/images';
+import { extractJson, isTransientError, runPooled, stripCodeFences } from 'cli/ai/generation/llm';
+import { parseManifest } from 'cli/ai/generation/manifest';
+import { assertInside, deriveSlug, isValidSlug } from 'cli/ai/generation/paths';
+import { aspectFromHint } from 'cli/ai/generation/wpcom-image';
+
+describe( 'stripCodeFences', () => {
+	it( 'removes a single wrapping fence', () => {
+		expect( stripCodeFences( '```json\n{"a":1}\n```' ) ).toBe( '{"a":1}' );
+		expect( stripCodeFences( '```\nhello\n```' ) ).toBe( 'hello' );
+	} );
+
+	it( 'strips a fence with no newline before the closing backticks', () => {
+		expect( stripCodeFences( '```json\n{"a":1}```' ) ).toBe( '{"a":1}' );
+	} );
+
+	it( 'recovers content from an unclosed (truncated) opening fence', () => {
+		expect( stripCodeFences( '```json\n{"a":1}' ) ).toBe( '{"a":1}' );
+	} );
+
+	it( 'leaves unfenced content untouched', () => {
+		expect( stripCodeFences( '  <div>x</div>  ' ) ).toBe( '<div>x</div>' );
+	} );
+} );
+
+describe( 'extractJson', () => {
+	it( 'extracts an object from a fenced + prose-wrapped response', () => {
+		const raw = 'Here is the manifest:\n```json\n{ "themeSlug": "acme", "n": 1 }\n```\nDone.';
+		expect( JSON.parse( extractJson( raw ) ) ).toEqual( { themeSlug: 'acme', n: 1 } );
+	} );
+
+	it( 'extracts an object from an unclosed fence (truncated wrapper)', () => {
+		expect( JSON.parse( extractJson( '```json\n{ "a": [1,2], "b": "x" }' ) ) ).toEqual( {
+			a: [ 1, 2 ],
+			b: 'x',
+		} );
+	} );
+
+	it( 'extracts a JSON array', () => {
+		expect(
+			JSON.parse( extractJson( '```json\n[ { "name": "A" }, { "name": "B" } ]\n```' ) )
+		).toEqual( [ { name: 'A' }, { name: 'B' } ] );
+	} );
+} );
+
+describe( 'isTransientError', () => {
+	it( 'flags retryable statuses and messages', () => {
+		expect( isTransientError( { status: 503 } ) ).toBe( true );
+		expect( isTransientError( { status: 429 } ) ).toBe( true );
+		expect( isTransientError( { status: 529 } ) ).toBe( true );
+		expect( isTransientError( new Error( 'WordPress.com — 503 Error' ) ) ).toBe( true );
+		expect( isTransientError( new Error( 'Overloaded' ) ) ).toBe( true );
+		expect( isTransientError( new Error( 'ECONNRESET' ) ) ).toBe( true );
+	} );
+
+	it( 'does not flag client errors', () => {
+		expect( isTransientError( { status: 400 } ) ).toBe( false );
+		expect( isTransientError( { status: 401 } ) ).toBe( false );
+		expect( isTransientError( new Error( 'invalid request: missing field' ) ) ).toBe( false );
+	} );
+} );
+
+describe( 'runPooled', () => {
+	it( 'runs every task and preserves order regardless of completion timing', async () => {
+		const tasks = [ 30, 5, 20, 1, 10 ].map(
+			( delay, index ) => () =>
+				new Promise< number >( ( resolve ) => setTimeout( () => resolve( index ), delay ) )
+		);
+		const results = await runPooled( tasks, 2 );
+		expect( results ).toEqual( [ 0, 1, 2, 3, 4 ] );
+	} );
+
+	it( 'handles an empty task list', async () => {
+		expect( await runPooled( [], 4 ) ).toEqual( [] );
+	} );
+} );
+
+describe( 'paths', () => {
+	it( 'derives and validates slugs', () => {
+		expect( deriveSlug( 'Ember & Oak!' ) ).toBe( 'ember-oak' );
+		expect( isValidSlug( 'ember-oak' ) ).toBe( true );
+		expect( isValidSlug( '-bad' ) ).toBe( false );
+		expect( isValidSlug( 'Bad Slug' ) ).toBe( false );
+	} );
+
+	it( 'allows writes inside the package and rejects escapes', () => {
+		const base = '/tmp/site/wp-content/themes/acme';
+		expect( assertInside( base, 'parts/header.html' ) ).toBe(
+			'/tmp/site/wp-content/themes/acme/parts/header.html'
+		);
+		expect( () => assertInside( base, '../../../../etc/passwd' ) ).toThrow();
+		expect( () => assertInside( base, '/etc/passwd' ) ).toThrow();
+	} );
+} );
+
+describe( 'aspectFromHint', () => {
+	it( 'maps tokens, keywords, and dimensions to Imagen aspect ratios', () => {
+		expect( aspectFromHint( '16:9' ) ).toBe( '16:9' );
+		expect( aspectFromHint( 'hero' ) ).toBe( '16:9' );
+		expect( aspectFromHint( 'portrait' ) ).toBe( '3:4' );
+		expect( aspectFromHint( 'square' ) ).toBe( '1:1' );
+		expect( aspectFromHint( '1792x1024' ) ).toBe( '16:9' );
+		expect( aspectFromHint( '1080x1920' ) ).toBe( '9:16' );
+		expect( aspectFromHint( undefined ) ).toBe( '16:9' );
+	} );
+} );
+
+describe( 'AI_IMAGE parsing', () => {
+	it( 'parses the alt convention', () => {
+		expect( parseAiImageAlt( 'AI_IMAGE: a wood-fired oven | photographic | 16:9' ) ).toEqual( {
+			description: 'a wood-fired oven',
+			style: 'photographic',
+			aspect: '16:9',
+		} );
+		expect( parseAiImageAlt( 'just an alt' ) ).toBeNull();
+	} );
+
+	it( 'reads attributes from a tag', () => {
+		const tag = '<img src="x.png" alt="AI_IMAGE: hero | photo | 16:9" />';
+		expect( getAttr( tag, 'src' ) ).toBe( 'x.png' );
+		expect( getAttr( tag, 'alt' ) ).toBe( 'AI_IMAGE: hero | photo | 16:9' );
+	} );
+
+	it( 'finds only AI_IMAGE placeholders among images', () => {
+		const html =
+			'<img src="real.jpg" alt="A real photo">' +
+			'<img src="ph.png" alt="AI_IMAGE: a cafe interior | photographic | 16:9">';
+		const found = findAiImages( html );
+		expect( found ).toHaveLength( 1 );
+		expect( found[ 0 ].description ).toBe( 'a cafe interior' );
+	} );
+
+	it( 'strips AI_IMAGE placeholders but keeps real images', () => {
+		const html =
+			'<p>x</p><img src="real.jpg" alt="A real photo" />' +
+			'<img class="bg" src="ph.png" alt="AI_IMAGE: hero | photo | 16:9" /><p>y</p>';
+		const stripped = stripAiImagePlaceholders( html );
+		expect( stripped ).toContain( 'real.jpg' );
+		expect( stripped ).not.toContain( 'AI_IMAGE' );
+		expect( stripped ).toBe( '<p>x</p><img src="real.jpg" alt="A real photo" /><p>y</p>' );
+	} );
+} );
+
+describe( 'parseManifest', () => {
+	it( 'parses a full manifest', () => {
+		const manifest = parseManifest(
+			JSON.stringify( {
+				themeSlug: 'Ember Oak',
+				themeName: 'Ember & Oak',
+				layoutMode: 'landing-page',
+				contentMode: 'homepage-and-pages',
+				parts: [ 'header', 'footer' ],
+				templates: [ 'index', 'page' ],
+				pages: [ { slug: 'Home', title: 'Home', brief: 'hero + menu teaser' } ],
+				companionPlugin: {
+					needed: true,
+					slug: 'ember-oak-functionality',
+					name: 'Ember & Oak Functionality',
+					postTypes: [
+						{ slug: 'dish', name: 'Dish', fields: [ { key: 'price', type: 'number' } ] },
+					],
+					restRoutes: [ { path: '/ember/v1/reserve', purpose: 'reservations' } ],
+					blocks: [ { slug: 'reservation-form', title: 'Reservation Form', purpose: 'booking' } ],
+				},
+				seed: [ { type: 'page', slug: 'home', title: 'Home' } ],
+			} )
+		);
+
+		expect( manifest.themeSlug ).toBe( 'ember-oak' );
+		expect( manifest.layoutMode ).toBe( 'landing-page' );
+		expect( manifest.pages[ 0 ].slug ).toBe( 'home' );
+		expect( manifest.companionPlugin.needed ).toBe( true );
+		expect( manifest.companionPlugin.postTypes[ 0 ].fields[ 0 ].type ).toBe( 'number' );
+	} );
+
+	it( 'applies safe defaults for a sparse manifest', () => {
+		const manifest = parseManifest( JSON.stringify( { themeName: 'Tiny' } ) );
+		expect( manifest.themeSlug ).toBe( 'tiny' );
+		expect( manifest.layoutMode ).toBe( 'vertical-stack' );
+		expect( manifest.contentMode ).toBe( 'homepage-and-pages' );
+		expect( manifest.parts ).toEqual( [ 'header', 'footer' ] );
+		expect( manifest.templates ).toEqual( [ 'index', 'page' ] );
+		expect( manifest.companionPlugin.needed ).toBe( false );
+	} );
+
+	it( 'normalizes an unknown layout mode and bad field types', () => {
+		const manifest = parseManifest(
+			JSON.stringify( {
+				themeName: 'X',
+				layoutMode: 'spaceship',
+				companionPlugin: {
+					needed: true,
+					postTypes: [ { slug: 'thing', name: 'Thing', fields: [ { key: 'k', type: 'weird' } ] } ],
+				},
+			} )
+		);
+		expect( manifest.layoutMode ).toBe( 'vertical-stack' );
+		expect( manifest.companionPlugin.slug ).toBe( 'x-functionality' );
+		expect( manifest.companionPlugin.postTypes[ 0 ].fields[ 0 ].type ).toBe( 'string' );
+	} );
+
+	it( 'throws on invalid JSON', () => {
+		expect( () => parseManifest( 'not json' ) ).toThrow();
+	} );
+} );
diff --git a/apps/cli/ai/tools/generate-companion-plugin.ts b/apps/cli/ai/tools/generate-companion-plugin.ts
new file mode 100644
index 0000000000..14f273efb2
--- /dev/null
+++ b/apps/cli/ai/tools/generate-companion-plugin.ts
@@ -0,0 +1,175 @@
+import { Type } from 'typebox';
+import { runBlockGenerator, runGenerator } from 'cli/ai/generation/generators';
+import { runPooled } from 'cli/ai/generation/llm';
+import { parseManifest } from 'cli/ai/generation/manifest';
+import { pluginDir, writePackageFile } from 'cli/ai/generation/paths';
+import { isSiteRunning, withDaemon, wpCli } from 'cli/ai/generation/site-wp';
+import { defineTool } from './define-tool';
+import { resolveSite, textResult } from './utils';
+
+function normalizeSpecJson( spec: string ): string {
+	const trimmed = spec.trim();
+	try {
+		return JSON.stringify( JSON.parse( trimmed ), null, 2 );
+	} catch {
+		return JSON.stringify( { description: trimmed }, null, 2 );
+	}
+}
+
+function renderPluginHeader( name: string, slug: string ): string {
+	return `<?php
+/**
+ * Plugin Name: ${ name }
+ * Description: Behaviour for the site — custom post types, REST routes, and build-less blocks. Lives in a plugin so it survives a theme switch.
+ * Version: 0.1.0
+ * Requires at least: 6.7
+ * Requires PHP: 7.4
+ * Text Domain: ${ slug }
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+`;
+}
+
+// The generator is told to include the header; guarantee it so WordPress
+// recognises the plugin even if the model omitted it.
+function ensurePluginHeader( php: string, name: string, slug: string ): string {
+	// A leading UTF-8 BOM before <?php breaks WordPress's plugin-header parser,
+	// so strip it unconditionally — including when the model emitted a valid
+	// header that happens to be BOM-prefixed.
+	const clean = php.charCodeAt( 0 ) === 0xfeff ? php.slice( 1 ) : php;
+	if ( /Plugin Name:/i.test( clean ) ) {
+		return clean;
+	}
+	const body = clean.replace( /^\s*<\?php\s*/, '' );
+	return `${ renderPluginHeader( name, slug ) }\n${ body }`;
+}
+
+async function activatePlugin( siteId: string, slug: string ): Promise< string > {
+	return withDaemon( async () => {
+		if ( ! ( await isSiteRunning( siteId ) ) ) {
+			return `Site is not running — plugin written but not activated. Start it (site_start), then run: wp plugin activate ${ slug }`;
+		}
+		const result = await wpCli( siteId, [ 'plugin', 'activate', slug ] );
+		if ( result.exitCode !== 0 ) {
+			const detail = ( result.stderr || result.stdout ).trim();
+			return `Plugin written but activation failed${
+				detail ? `: ${ detail }` : ''
+			}. Activate manually with: wp plugin activate ${ slug }`;
+		}
+		return `Activated plugin '${ slug }'.`;
+	} );
+}
+
+export const generateCompanionPluginTool = defineTool(
+	'generate_companion_plugin',
+	'Generates the companion plugin for a site: custom post types, taxonomies, post meta, REST routes, and BUILD-LESS plain-JS Gutenberg blocks (block.json + plain registerBlockType JS, no @wordpress/scripts, no build step). Writes into wp-content/plugins/<slug>-functionality/ and activates it. This is where ALL site behaviour lives — keeping the theme pure presentation. Requires the manifest from generate_theme. No-ops when the manifest marks the companion plugin as not needed (brochure sites).',
+	{
+		nameOrPath: Type.String( {
+			description: 'The site name or filesystem path of the target site.',
+		} ),
+		spec: Type.String( {
+			description: 'The site spec as a JSON string (same one passed to generate_theme).',
+		} ),
+		manifest: Type.String( {
+			description:
+				'The file manifest JSON returned by generate_theme. Required — it declares the post types, REST routes, and blocks.',
+		} ),
+	},
+	async ( args ) => {
+		const site = await resolveSite( args.nameOrPath );
+		const specJson = normalizeSpecJson( args.spec );
+		const manifest = parseManifest( args.manifest );
+		const plugin = manifest.companionPlugin;
+
+		if ( ! plugin.needed ) {
+			return textResult(
+				'No companion plugin needed — the manifest marks this site as presentation-only (no custom post types, REST routes, or interactive blocks). Nothing generated.'
+			);
+		}
+
+		const slug = plugin.slug;
+		const dir = pluginDir( site.path, slug );
+
+		const planSummary = JSON.stringify(
+			{ postTypes: plugin.postTypes, restRoutes: plugin.restRoutes, blocks: plugin.blocks },
+			null,
+			2
+		);
+
+		const mainPhpRaw = await runGenerator( {
+			name: 'companion-plugin',
+			specJson,
+			task: `Plugin name: ${ plugin.name }\nPlugin slug: ${ slug }\nGenerate the main plugin PHP file. Plan to implement:\n${ planSummary }\nRegister each block with register_block_type( __DIR__ . '/blocks/<block-slug>' ).`,
+			maxTokens: 12_000,
+			temperature: 0.3,
+		} );
+
+		const written: string[] = [];
+		await writePackageFile(
+			dir,
+			`${ slug }.php`,
+			ensurePluginHeader( mainPhpRaw, plugin.name, slug )
+		);
+		written.push( `${ slug }.php` );
+
+		// Build-less blocks, generated in parallel, one directory each. A single
+		// block failure must not abort the whole call and leave a half-written
+		// plugin, so each is best-effort and failures are reported.
+		const blockResults = await runPooled(
+			plugin.blocks.map( ( block ) => async () => {
+				try {
+					const generated = await runBlockGenerator(
+						specJson,
+						`Block slug: ${ block.slug }\nBlock title: ${ block.title }\nPurpose: ${ block.purpose }\nBlock namespace: ${ slug }/${ block.slug }`
+					);
+					return { block, files: generated.files, error: null as string | null };
+				} catch ( error ) {
+					return {
+						block,
+						files: {} as Record< string, string >,
+						error: error instanceof Error ? error.message : String( error ),
+					};
+				}
+			} ),
+			3
+		);
+
+		const failedBlocks: string[] = [];
+		for ( const { block, files, error } of blockResults ) {
+			if ( error ) {
+				failedBlocks.push( `${ block.slug } (${ error.slice( 0, 120 ) })` );
+				continue;
+			}
+			for ( const [ rel, content ] of Object.entries( files ) ) {
+				const target = `blocks/${ block.slug }/${ rel }`;
+				await writePackageFile( dir, target, content );
+				written.push( target );
+			}
+		}
+
+		const activation = await activatePlugin( site.id, slug );
+
+		const summary = [
+			`Generated companion plugin '${ plugin.name }' at wp-content/plugins/${ slug }/`,
+			'',
+			`Post types: ${ plugin.postTypes.map( ( p ) => p.slug ).join( ', ' ) || 'none' }`,
+			`REST routes: ${ plugin.restRoutes.map( ( r ) => r.path ).join( ', ' ) || 'none' }`,
+			`Blocks (build-less plain JS): ${
+				plugin.blocks.map( ( b ) => b.slug ).join( ', ' ) || 'none'
+			}`,
+			failedBlocks.length ? `Blocks that FAILED to generate: ${ failedBlocks.join( '; ' ) }` : '',
+			'',
+			'Files written:',
+			...written.map( ( f ) => `  ${ f }` ),
+			'',
+			activation,
+			'',
+			'NEXT: seed_content to publish pages, then generate_image, then validate_and_fix_blocks + take_screenshot.',
+		].join( '\n' );
+
+		return textResult( summary );
+	}
+);
diff --git a/apps/cli/ai/tools/generate-design-previews.ts b/apps/cli/ai/tools/generate-design-previews.ts
new file mode 100644
index 0000000000..2ba22dc25e
--- /dev/null
+++ b/apps/cli/ai/tools/generate-design-previews.ts
@@ -0,0 +1,118 @@
+import { mkdir, writeFile } from 'fs/promises';
+import path from 'path';
+import { Type } from 'typebox';
+import { runGenerator } from 'cli/ai/generation/generators';
+import { completeText, extractJson, runPooled } from 'cli/ai/generation/llm';
+import { openBrowser } from 'cli/lib/browser';
+import { defineTool } from './define-tool';
+import { resolveSite, textResult } from './utils';
+
+function normalizeSpecJson( spec: string ): string {
+	const trimmed = spec.trim();
+	try {
+		return JSON.stringify( JSON.parse( trimmed ), null, 2 );
+	} catch {
+		return JSON.stringify( { description: trimmed }, null, 2 );
+	}
+}
+
+interface DirectionBrief {
+	name: string;
+	brief: string;
+}
+
+async function planDirections( specJson: string, count: number ): Promise< DirectionBrief[] > {
+	const raw = await completeText( {
+		system: `You are an art director. Given a website spec, invent ${ count } RADICALLY DISTINCT visual design directions grounded in the site's topic and industry — not a generic style menu. Each should feel like a different designer made it (different typography, color strategy, layout philosophy, mood). Avoid generic AI aesthetics. Output ONLY a JSON array of exactly ${ count } objects of shape {"name": "short evocative name", "brief": "2-3 sentences: color strategy with hex codes, exact Google Font pairings, layout philosophy, mood"}. No prose, no code fences.`,
+		user: `SITE SPEC (JSON):\n${ specJson }`,
+		maxTokens: 2_000,
+		temperature: 0.9,
+	} );
+
+	try {
+		const parsed = JSON.parse( extractJson( raw ) ) as unknown;
+		if ( Array.isArray( parsed ) ) {
+			const briefs = parsed
+				.filter( ( d ): d is Record< string, unknown > => !! d && typeof d === 'object' )
+				.map( ( d, i ) => ( {
+					name:
+						typeof d.name === 'string' && d.name.trim() ? d.name.trim() : `Direction ${ i + 1 }`,
+					brief: typeof d.brief === 'string' ? d.brief.trim() : '',
+				} ) );
+			if ( briefs.length ) {
+				return briefs.slice( 0, count );
+			}
+		}
+	} catch {
+		// Fall through to generic briefs below.
+	}
+
+	return Array.from( { length: count }, ( _, i ) => ( {
+		name: `Direction ${ i + 1 }`,
+		brief: 'Invent a distinct, topic-grounded direction that differs clearly from the others.',
+	} ) );
+}
+
+export const generateDesignPreviewsTool = defineTool(
+	'generate_design_previews',
+	"Generates several distinct visual design directions as self-contained first-fold HTML previews (header + hero) and writes them to <site>/design/design-N.html, opening each in the browser. Use this BEFORE generate_theme so the user can pick a direction; pass the chosen preview's HTML (or its brief) as the `design` argument to generate_theme. Each direction is grounded in the site's topic, not a generic template.",
+	{
+		nameOrPath: Type.String( {
+			description: 'The site name or filesystem path of the target site.',
+		} ),
+		spec: Type.String( {
+			description: 'The site spec as a JSON string (site type, audience, tone, topic).',
+		} ),
+		directions: Type.Optional(
+			Type.Number( { description: 'How many directions to generate (default 3, max 4).' } )
+		),
+	},
+	async ( args ) => {
+		const site = await resolveSite( args.nameOrPath );
+		const specJson = normalizeSpecJson( args.spec );
+		const count = Math.max( 1, Math.min( 4, Math.round( args.directions ?? 3 ) ) );
+
+		const designDir = path.join( site.path, 'design' );
+		await mkdir( designDir, { recursive: true } );
+
+		const briefs = await planDirections( specJson, count );
+
+		const htmls = await runPooled(
+			briefs.map( ( brief, index ) => async () => {
+				const html = await runGenerator( {
+					name: 'design-direction',
+					specJson,
+					task: `Direction ${ index + 1 } of ${ count }.\nName: ${ brief.name }\nBrief: ${
+						brief.brief
+					}\nMake this direction clearly distinct from the others.`,
+					maxTokens: 12_000,
+					temperature: 0.8,
+				} );
+				return { brief, html, index };
+			} ),
+			Math.min( count, 3 )
+		);
+
+		const written: Array< { name: string; file: string } > = [];
+		for ( const { brief, html, index } of htmls ) {
+			const file = path.join( designDir, `design-${ index + 1 }.html` );
+			await writeFile( file, html, 'utf8' );
+			written.push( { name: brief.name, file } );
+			try {
+				await openBrowser( `file://${ file }` );
+			} catch {
+				// Opening a browser is best-effort; the file path is reported regardless.
+			}
+		}
+
+		const summary = [
+			`Generated ${ written.length } design direction(s) for ${ site.name }:`,
+			'',
+			...written.map( ( w, i ) => `  ${ i + 1 }. ${ w.name }\n     ${ w.file }` ),
+			'',
+			"Ask the user to pick one. Then call generate_theme with that preview's HTML (or its brief) as the `design` argument so the full theme matches the chosen direction.",
+		].join( '\n' );
+
+		return textResult( summary );
+	}
+);
diff --git a/apps/cli/ai/tools/generate-image.ts b/apps/cli/ai/tools/generate-image.ts
new file mode 100644
index 0000000000..14d872e61e
--- /dev/null
+++ b/apps/cli/ai/tools/generate-image.ts
@@ -0,0 +1,155 @@
+import { mkdir, readFile, readdir, writeFile } from 'fs/promises';
+import path from 'path';
+import { Type } from 'typebox';
+import { resolveAiImagesInHtml } from 'cli/ai/generation/images';
+import { themeDir, uploadsDir } from 'cli/ai/generation/paths';
+import { aspectFromHint, generateImageBytes } from 'cli/ai/generation/wpcom-image';
+import { getSiteUrl } from 'cli/lib/cli-config/sites';
+import { defineTool } from './define-tool';
+import { resolveSite, textResult } from './utils';
+
+const SCAN_SUBDIRS = [ 'templates', 'parts', 'patterns' ];
+
+async function listHtmlFiles( dir: string ): Promise< string[] > {
+	const out: string[] = [];
+	let entries;
+	try {
+		entries = await readdir( dir, { withFileTypes: true } );
+	} catch {
+		return out;
+	}
+	for ( const entry of entries ) {
+		const full = path.join( dir, entry.name );
+		if ( entry.isDirectory() ) {
+			out.push( ...( await listHtmlFiles( full ) ) );
+		} else if ( /\.(html|php)$/i.test( entry.name ) ) {
+			out.push( full );
+		}
+	}
+	return out;
+}
+
+function slugifyFileName( description: string, index: number ): string {
+	const base = description
+		.toLowerCase()
+		.replace( /[^a-z0-9]+/g, '-' )
+		.replace( /^-+|-+$/g, '' )
+		.slice( 0, 40 );
+	return `${ base || 'image' }-${ index }`;
+}
+
+export const generateImageTool = defineTool(
+	'generate_image',
+	'Generates AI imagery via the WordPress.com AI proxy (Google Imagen) and fills AI_IMAGE placeholders. Two modes: (1) pass themeSlug to scan the theme\'s templates/parts/patterns for `alt="AI_IMAGE: ..."` placeholders, generate each image into the theme\'s assets/images/, and rewrite the markup in place; (2) pass an explicit prompts list to generate standalone images saved to the uploads directory, returning their URLs. Requires WordPress.com authentication.',
+	{
+		nameOrPath: Type.String( {
+			description: 'The site name or filesystem path of the target site.',
+		} ),
+		themeSlug: Type.Optional(
+			Type.String( {
+				description:
+					"Scan this theme's templates/parts/patterns for AI_IMAGE placeholders and fill them in place.",
+			} )
+		),
+		prompts: Type.Optional(
+			Type.Array(
+				Type.Object( {
+					description: Type.String( { description: 'What the image depicts.' } ),
+					style: Type.Optional(
+						Type.String( {
+							description: 'Visual style, e.g. "photographic", "minimalist illustration".',
+						} )
+					),
+					aspect: Type.Optional(
+						Type.String( {
+							description: 'Aspect hint, e.g. "16:9", "square", "portrait", or "1792x1024".',
+						} )
+					),
+				} ),
+				{ description: 'Explicit image prompts to generate into the uploads directory.' }
+			)
+		),
+	},
+	async ( args ) => {
+		const site = await resolveSite( args.nameOrPath );
+		const siteUrl = getSiteUrl( site ).replace( /\/+$/, '' );
+
+		if ( ! args.themeSlug && ( ! args.prompts || args.prompts.length === 0 ) ) {
+			throw new Error(
+				'Provide either themeSlug (to scan a theme) or a prompts list (to generate standalone images).'
+			);
+		}
+
+		const lines: string[] = [];
+
+		// Mode 1: scan a theme and fill placeholders in place.
+		if ( args.themeSlug ) {
+			const slug = args.themeSlug;
+			const root = themeDir( site.path, slug );
+			const assetsRel = path.join( 'assets', 'images' );
+			const assetsAbs = path.join( root, assetsRel );
+
+			const files: string[] = [];
+			for ( const sub of SCAN_SUBDIRS ) {
+				files.push( ...( await listHtmlFiles( path.join( root, sub ) ) ) );
+			}
+
+			let generated = 0;
+			let failed = 0;
+			let touched = 0;
+
+			for ( const file of files ) {
+				const html = await readFile( file, 'utf8' );
+				const resolution = await resolveAiImagesInHtml( html, async ( bytes, ctx ) => {
+					const name = `${ slugifyFileName( ctx.description, ctx.index ) }.png`;
+					await mkdir( assetsAbs, { recursive: true } );
+					await writeFile( path.join( assetsAbs, name ), bytes );
+					return `${ siteUrl }/wp-content/themes/${ slug }/${ assetsRel.replace(
+						/\\/g,
+						'/'
+					) }/${ name }`;
+				} );
+				generated += resolution.generated;
+				failed += resolution.failed;
+				if ( resolution.html !== html ) {
+					await writeFile( file, resolution.html, 'utf8' );
+					touched++;
+				}
+			}
+
+			lines.push(
+				`Theme scan (${ slug }): ${ generated } image(s) generated, ${ failed } failed, ${ touched } file(s) updated across ${ files.length } scanned.`
+			);
+		}
+
+		// Mode 2: explicit prompts → uploads.
+		if ( args.prompts && args.prompts.length > 0 ) {
+			const wsgUploads = uploadsDir( site.path );
+			await mkdir( wsgUploads, { recursive: true } );
+			const urls: string[] = [];
+			let failed = 0;
+
+			for ( let i = 0; i < args.prompts.length; i++ ) {
+				const prompt = args.prompts[ i ];
+				try {
+					const bytes = await generateImageBytes(
+						`${ prompt.description }.${
+							prompt.style ? ` Style: ${ prompt.style }.` : ''
+						} High quality, no text, no watermark.`,
+						aspectFromHint( prompt.aspect )
+					);
+					const name = `${ slugifyFileName( prompt.description, i + 1 ) }.png`;
+					await writeFile( path.join( wsgUploads, name ), bytes );
+					urls.push( `${ siteUrl }/wp-content/uploads/wsg/${ name }` );
+				} catch {
+					failed++;
+				}
+			}
+
+			lines.push( `Standalone images: ${ urls.length } generated, ${ failed } failed.` );
+			urls.forEach( ( url ) => lines.push( `  ${ url }` ) );
+		}
+
+		return textResult( lines.join( '\n' ) );
+	}
+);
diff --git a/apps/cli/ai/tools/generate-theme.ts b/apps/cli/ai/tools/generate-theme.ts
new file mode 100644
index 0000000000..a7b979f604
--- /dev/null
+++ b/apps/cli/ai/tools/generate-theme.ts
@@ -0,0 +1,256 @@
+import { Type } from 'typebox';
+import { runGenerator, runManifest } from 'cli/ai/generation/generators';
+import { runPooled } from 'cli/ai/generation/llm';
+import { parseManifest, type SiteManifest } from 'cli/ai/generation/manifest';
+import { themeDir, writePackageFile } from 'cli/ai/generation/paths';
+import { isSiteRunning, withDaemon, wpCli } from 'cli/ai/generation/site-wp';
+import { defineTool } from './define-tool';
+import { resolveSite, textResult } from './utils';
+
+// Normalize the agent-supplied spec into a JSON string. The agent should pass
+// a JSON site spec; if it passes prose, wrap it so generators still get
+// structured-looking input.
+function normalizeSpecJson( spec: string ): string {
+	const trimmed = spec.trim();
+	try {
+		return JSON.stringify( JSON.parse( trimmed ), null, 2 );
+	} catch {
+		return JSON.stringify( { description: trimmed }, null, 2 );
+	}
+}
+
+function renderFunctionsPhp( name: string, slug: string ): string {
+	return `<?php
+/**
+ * ${ name } theme functions.
+ *
+ * Presentation only. All behaviour (custom post types, REST routes, blocks)
+ * lives in the companion plugin, not the theme.
+ *
+ * @package ${ slug }
+ */
+
+add_action( 'wp_enqueue_scripts', function () {
+	wp_enqueue_style(
+		'${ slug }-style',
+		get_parent_theme_file_uri( 'style.css' ),
+		array(),
+		wp_get_theme()->get( 'Version' )
+	);
+} );
+
+add_action( 'after_setup_theme', function () {
+	add_editor_style( 'style.css' );
+} );
+`;
+}
+
+function renderStyleHeader( name: string, slug: string ): string {
+	return `/*
+Theme Name: ${ name }
+Description: A custom block theme generated by WordPress Studio.
+Requires at least: 6.7
+Tested up to: 6.9
+Requires PHP: 7.4
+Version: 0.1.0
+License: GNU General Public License v2 or later
+License URI: http://www.gnu.org/licenses/gpl-2.0.html
+Text Domain: ${ slug }
+Tags: full-site-editing, block-patterns, block-styles, wide-blocks
+*/
+`;
+}
+
+// WordPress only recognises a theme when style.css carries the header block as
+// its first bytes. The generator is asked to include it, but guarantee it here
+// — and strip a leading BOM unconditionally, since a BOM before the header
+// corrupts the parser whether or not the header is otherwise present.
+function ensureStyleHeader( css: string, name: string, slug: string ): string {
+	const clean = css.charCodeAt( 0 ) === 0xfeff ? css.slice( 1 ) : css;
+	if ( /Theme Name:/i.test( clean ) ) {
+		return clean;
+	}
+	return `${ renderStyleHeader( name, slug ) }\n${ clean }`;
+}
+
+interface PlannedWrite {
+	rel: string;
+	run: () => Promise< string >;
+}
+
+async function activateTheme( siteId: string, slug: string ): Promise< string > {
+	return withDaemon( async () => {
+		if ( ! ( await isSiteRunning( siteId ) ) ) {
+			return `Site is not running — theme written but not activated. Start it (site_start), then run: wp theme activate ${ slug }`;
+		}
+		const result = await wpCli( siteId, [ 'theme', 'activate', slug ] );
+		if ( result.exitCode !== 0 ) {
+			const detail = ( result.stderr || result.stdout ).trim();
+			return `Theme written but activation failed${
+				detail ? `: ${ detail }` : ''
+			}. Activate manually with: wp theme activate ${ slug }`;
+		}
+		return `Activated theme '${ slug }'.`;
+	} );
+}
+
+export const generateThemeTool = defineTool(
+	'generate_theme',
+	'Generates a complete PURE-PRESENTATION WordPress block theme (theme.json, style.css, template parts, templates, minimal functions.php) into a site at wp-content/themes/<slug>/ and activates it. Runs the file generators in parallel from a site spec and a chosen design direction, writing the whole theme in one call. Behaviour (custom post types, REST routes, custom blocks) is NOT generated here — call generate_companion_plugin for that. Page content is NOT written as files — call seed_content to populate the live database. Returns the resolved manifest (pass it verbatim to generate_companion_plugin and seed_content). The functions.php is intentionally minimal. Best run after generate_design_previews so a design direction has been chosen.',
+	{
+		nameOrPath: Type.String( {
+			description: 'The site name or filesystem path of the target site.',
+		} ),
+		spec: Type.String( {
+			description:
+				'The site spec as a JSON string (site type, audience, tone, layout preference, pages). Gather it with the site-spec / theme-architecture skills before calling.',
+		} ),
+		design: Type.Optional(
+			Type.String( {
+				description:
+					'The chosen design direction — the first-fold HTML from generate_design_previews, or a detailed prose design brief. Strongly recommended for visual coherence.',
+			} )
+		),
+		manifest: Type.Optional(
+			Type.String( {
+				description:
+					'Optional file manifest as a JSON string (from a prior generate_theme call). When omitted, a manifest is generated from the spec.',
+			} )
+		),
+	},
+	async ( args ) => {
+		const site = await resolveSite( args.nameOrPath );
+		const specJson = normalizeSpecJson( args.spec );
+		const design = args.design?.trim() || '';
+
+		const manifest: SiteManifest = args.manifest
+			? parseManifest( args.manifest )
+			: await runManifest( specJson );
+
+		const slug = manifest.themeSlug;
+		const dir = themeDir( site.path, slug );
+
+		const planned: PlannedWrite[] = [
+			{
+				rel: 'theme.json',
+				run: () =>
+					runGenerator( {
+						name: 'theme-json',
+						specJson,
+						design,
+						maxTokens: 6_000,
+						temperature: 0.4,
+					} ),
+			},
+			{
+				rel: 'style.css',
+				run: async () =>
+					ensureStyleHeader(
+						await runGenerator( {
+							name: 'style-css',
+							specJson,
+							design,
+							maxTokens: 14_000,
+							temperature: 0.5,
+						} ),
+						manifest.themeName,
+						slug
+					),
+			},
+		];
+
+		for ( const part of manifest.parts ) {
+			planned.push( {
+				rel: `parts/${ part }.html`,
+				run: () =>
+					runGenerator( {
+						name: 'template-part',
+						specJson,
+						design,
+						task: `Part: ${ part }\nLayout mode: ${ manifest.layoutMode }`,
+						maxTokens: 6_000,
+						temperature: 0.5,
+					} ),
+			} );
+		}
+
+		for ( const template of manifest.templates ) {
+			planned.push( {
+				rel: `templates/${ template }.html`,
+				run: () =>
+					runGenerator( {
+						name: 'template',
+						specJson,
+						design,
+						task: `Template: ${ template }\nLayout mode: ${ manifest.layoutMode }\nContent mode: ${ manifest.contentMode }`,
+						maxTokens: 6_000,
+						temperature: 0.5,
+					} ),
+			} );
+		}
+
+		const generated = await runPooled(
+			planned.map( ( item ) => async () => ( { rel: item.rel, content: await item.run() } ) ),
+			4
+		);
+
+		const written: string[] = [];
+		for ( const file of generated ) {
+			await writePackageFile( dir, file.rel, file.content );
+			written.push( file.rel );
+		}
+		await writePackageFile( dir, 'functions.php', renderFunctionsPhp( manifest.themeName, slug ) );
+		written.push( 'functions.php' );
+
+		const activation = await activateTheme( site.id, slug );
+
+		const plugin = manifest.companionPlugin;
+		const nextSteps: string[] = [];
+		if ( plugin.needed ) {
+			nextSteps.push(
+				`1. generate_companion_plugin — the spec needs behaviour (${
+					[
+						plugin.postTypes.length ? `${ plugin.postTypes.length } post type(s)` : '',
+						plugin.restRoutes.length ? `${ plugin.restRoutes.length } REST route(s)` : '',
+						plugin.blocks.length ? `${ plugin.blocks.length } custom block(s)` : '',
+					]
+						.filter( Boolean )
+						.join( ', ' ) || 'a companion plugin'
+				}). Pass the manifest below.`
+			);
+		}
+		nextSteps.push(
+			`${ plugin.needed ? '2' : '1' }. seed_content — generate and publish the ${
+				manifest.pages.length
+			} page(s) into the database. Pass the manifest below.`
+		);
+		nextSteps.push(
+			`${
+				plugin.needed ? '3' : '2'
+			}. generate_image — fill AI_IMAGE placeholders in the theme (themeSlug: ${ slug }).`
+		);
+		nextSteps.push(
+			`${
+				plugin.needed ? '4' : '3'
+			}. validate_and_fix_blocks on generated content, then take_screenshot (viewport: "all") to verify and fix.`
+		);
+
+		const summary = [
+			`Generated block theme '${ manifest.themeName }' at wp-content/themes/${ slug }/`,
+			`Layout mode: ${ manifest.layoutMode } · Content mode: ${ manifest.contentMode }`,
+			'',
+			'Files written:',
+			...written.map( ( f ) => `  ${ f }` ),
+			'',
+			activation,
+			'',
+			'NEXT STEPS:',
+			...nextSteps.map( ( s ) => `  ${ s }` ),
+			'',
+			'MANIFEST (pass verbatim to the next tools):',
+			JSON.stringify( manifest ),
+		].join( '\n' );
+
+		return textResult( summary );
+	}
+);
diff --git a/apps/cli/ai/tools/index.ts b/apps/cli/ai/tools/index.ts
index 1e281feccf..43c4484ecf 100644
--- a/apps/cli/ai/tools/index.ts
+++ b/apps/cli/ai/tools/index.ts
@@ -4,6 +4,10 @@ import { createSiteTool } from './create-site';
 import { deletePreviewTool } from './delete-preview';
 import { deleteSiteTool } from './delete-site';
 import { exportSiteTool } from './export-site';
+import { generateCompanionPluginTool } from './generate-companion-plugin';
+import { generateDesignPreviewsTool } from './generate-design-previews';
+import { generateImageTool } from './generate-image';
+import { generateThemeTool } from './generate-theme';
 import { importSiteTool } from './import-site';
 import { installTaxonomyScriptsTool } from './install-taxonomy-scripts';
 import { listConnectedRemoteSitesTool } from './list-connected-remote-sites';
@@ -15,6 +19,7 @@ import { pullSiteTool } from './pull-site';
 import { pushSiteTool } from './push-site';
 import { auditSeoTool } from './rank-me-up';
 import { scaffoldThemeTool } from './scaffold-theme';
+import { seedContentTool } from './seed-content';
 import { shareScreenshotTool } from './share-screenshot';
 import { getSiteInfoTool } from './site-info';
 import { startSiteTool } from './start-site';
@@ -43,6 +48,11 @@ export const studioToolDefinitions: AnyStudioAgentTool[] = [
 	deletePreviewTool,
 	runWpCliTool,
 	scaffoldThemeTool,
+	generateDesignPreviewsTool,
+	generateThemeTool,
+	generateCompanionPluginTool,
+	seedContentTool,
+	generateImageTool,
 	validateHtmlBlocksTool,
 	validateAndFixBlocksTool,
 	takeScreenshotTool,
diff --git a/apps/cli/ai/tools/seed-content.ts b/apps/cli/ai/tools/seed-content.ts
new file mode 100644
index 0000000000..16948bdc64
--- /dev/null
+++ b/apps/cli/ai/tools/seed-content.ts
@@ -0,0 +1,493 @@
+import { mkdir, writeFile } from 'fs/promises';
+import path from 'path';
+import { readAuthToken } from '@studio/common/lib/shared-config';
+import { Type } from 'typebox';
+import { runGenerator } from 'cli/ai/generation/generators';
+import { resolveAiImagesInHtml, stripAiImagePlaceholders } from 'cli/ai/generation/images';
+import { completeText, extractJson, runPooled } from 'cli/ai/generation/llm';
+import { parseManifest, type PostTypePlan, type SiteManifest } from 'cli/ai/generation/manifest';
+import { deriveSlug, uploadsDir } from 'cli/ai/generation/paths';
+import { isSiteRunning, withDaemon, wpCli } from 'cli/ai/generation/site-wp';
+import { getSiteUrl } from 'cli/lib/cli-config/sites';
+import { defineTool } from './define-tool';
+import { resolveSite, textResult } from './utils';
+
+function normalizeSpecJson( spec: string ): string {
+	const trimmed = spec.trim();
+	try {
+		return JSON.stringify( JSON.parse( trimmed ), null, 2 );
+	} catch {
+		return JSON.stringify( { description: trimmed }, null, 2 );
+	}
+}
+
+// An item ready to publish: post type, slug, title, block-markup content, and
+// (for custom post types) meta fields.
+interface PreparedItem {
+	postType: string;
+	slug: string;
+	title: string;
+	content: string;
+	meta: Record< string, string >;
+	isHome: boolean;
+}
+
+// Page-like targets (pages + native posts) take their body from the
+// page-content generator. CPT entries are generated separately with meta.
+interface PageTarget {
+	postType: string;
+	slug: string;
+	title: string;
+	brief: string;
+	isHome: boolean;
+}
+
+function collectPageTargets( manifest: SiteManifest ): PageTarget[] {
+	const targets: PageTarget[] = [];
+	const seen = new Set< string >();
+
+	for ( const page of manifest.pages ) {
+		const key = `page:${ page.slug }`;
+		if ( seen.has( key ) ) {
+			continue;
+		}
+		seen.add( key );
+		targets.push( {
+			postType: 'page',
+			slug: page.slug,
+			title: page.title,
+			brief: page.brief,
+			isHome: page.slug === 'home' || page.title.trim().toLowerCase() === 'home',
+		} );
+	}
+
+	// Native blog posts declared in the manifest's seed list.
+	for ( const item of manifest.seed ) {
+		if ( item.type !== 'post' ) {
+			continue;
+		}
+		const key = `post:${ item.slug }`;
+		if ( seen.has( key ) ) {
+			continue;
+		}
+		seen.add( key );
+		targets.push( {
+			postType: 'post',
+			slug: item.slug,
+			title: item.title,
+			brief: '',
+			isHome: false,
+		} );
+	}
+
+	return targets;
+}
+
+interface CptEntry {
+	title: string;
+	content: string;
+	meta: Record< string, string >;
+}
+
+// Generate realistic sample entries (title + short body + meta) for a custom
+// post type. Inline prompt (no bundled fragment) keyed on the CPT's declared
+// fields so the meta keys line up with what the companion plugin registered.
+async function runCptEntries(
+	specJson: string,
+	postType: PostTypePlan,
+	count: number
+): Promise< CptEntry[] > {
+	const fieldKeys = postType.fields.map( ( f ) => f.key );
+	const fieldList = postType.fields.length
+		? postType.fields.map( ( f ) => `${ f.key } (${ f.type })` ).join( ', ' )
+		: '(no meta fields)';
+
+	const raw = await completeText( {
+		system: `You generate realistic sample entries for a WordPress custom post type on a generated site. Output ONLY a JSON array of exactly ${ count } objects — no prose, no code fences. Each object is {"title": string, "content": "WordPress block markup body, 2-4 core blocks (wp:paragraph, wp:heading, wp:list)", "meta": { ... }}. The meta object MUST use exactly these keys: ${
+			fieldKeys.join( ', ' ) || '(none — use an empty object)'
+		}. Invent plausible, domain-anchored values grounded in the site; never reference real brands or real people. No emojis.`,
+		user: `Site spec (JSON):\n${ specJson }\n\nPost type: ${ postType.name } (slug: ${ postType.slug })\nMeta fields: ${ fieldList }\nGenerate ${ count } distinct entries.`,
+		maxTokens: 8_000,
+		temperature: 0.7,
+	} );
+
+	const parsed = JSON.parse( extractJson( raw ) ) as unknown;
+	if ( ! Array.isArray( parsed ) ) {
+		return [];
+	}
+	return parsed
+		.filter( ( e ): e is Record< string, unknown > => !! e && typeof e === 'object' )
+		.map( ( e ) => ( {
+			title: typeof e.title === 'string' ? e.title.trim() : '',
+			content: typeof e.content === 'string' ? e.content : '',
+			meta:
+				e.meta && typeof e.meta === 'object'
+					? Object.fromEntries(
+							Object.entries( e.meta as Record< string, unknown > )
+								.filter( ( [ key ] ) => fieldKeys.length === 0 || fieldKeys.includes( key ) )
+								.map( ( [ key, value ] ) => [ key, String( value ) ] )
+					  )
+					: {},
+		} ) )
+		.filter( ( e ) => e.title );
+}
+
+async function wpcomImagesAvailable(): Promise< boolean > {
+	if ( process.env.STUDIO_WPCOM_TOKEN?.trim() ) {
+		return true;
+	}
+	try {
+		return Boolean( ( await readAuthToken() )?.accessToken );
+	} catch {
+		return false;
+	}
+}
+
+async function findExistingPostId(
+	siteId: string,
+	postType: string,
+	slug: string
+): Promise< number | null > {
+	const result = await wpCli( siteId, [
+		'post',
+		'list',
+		`--post_type=${ postType }`,
+		`--name=${ slug }`,
+		'--post_status=any',
+		'--format=ids',
+	] );
+	if ( result.exitCode !== 0 ) {
+		return null;
+	}
+	const match = result.stdout.match( /\b\d+\b/ );
+	const id = match ? Number.parseInt( match[ 0 ], 10 ) : NaN;
+	return Number.isFinite( id ) && id > 0 ? id : null;
+}
+
+// WordPress root as PHP sees it. The Studio site's wp-content is the live WP
+// filesystem (theme/plugin files written host-side appear in the running site),
+// so a file written to <site>/wp-content/uploads/... is readable by WP-CLI at
+// <ABSPATH>wp-content/uploads/... — letting us pass post content via a file
+// path instead of a giant `--post_content=` arg that the IPC bus truncates.
+async function getAbspath( siteId: string ): Promise< string > {
+	const result = await wpCli( siteId, [ 'eval', 'echo ABSPATH;' ] );
+	const value = result.stdout.trim();
+	if ( ! value ) {
+		throw new Error( 'Could not determine WordPress ABSPATH; cannot seed content reliably.' );
+	}
+	return value.endsWith( '/' ) ? value : `${ value }/`;
+}
+
+export const seedContentTool = defineTool(
+	'seed_content',
+	"Generates and publishes a site's pages, posts, and custom-post-type entries into the LIVE WordPress database from the manifest (content is NOT baked into the theme). Page bodies come from the composition briefs; CPT entries (from the companion plugin's post types) are generated with their meta fields so collections like products/events/team actually populate. Large content is written via a file the WP filesystem reads, avoiding WP-CLI argument truncation. AI_IMAGE placeholders are filled when logged into WordPress.com, otherwise removed. Upserts by slug (idempotent) and sets the home page as the static front page. Requires the manifest from generate_theme and a running site.",
+	{
+		nameOrPath: Type.String( {
+			description: 'The site name or filesystem path of the target site.',
+		} ),
+		spec: Type.String( {
+			description: 'The site spec as a JSON string (same one passed to generate_theme).',
+		} ),
+		manifest: Type.String( { description: 'The file manifest JSON returned by generate_theme.' } ),
+		withImages: Type.Optional(
+			Type.Boolean( {
+				description:
+					'Fill AI_IMAGE placeholders with generated imagery (default true; requires WordPress.com login). When false or not logged in, placeholders are removed instead.',
+			} )
+		),
+	},
+	async ( args ) => {
+		const site = await resolveSite( args.nameOrPath );
+		const specJson = normalizeSpecJson( args.spec );
+		const manifest = parseManifest( args.manifest );
+		const withImages = args.withImages ?? true;
+		const imagesOk = withImages && ( await wpcomImagesAvailable() );
+
+		const pageTargets = collectPageTargets( manifest );
+		const cptPlans = manifest.companionPlugin.needed ? manifest.companionPlugin.postTypes : [];
+		if ( pageTargets.length === 0 && cptPlans.length === 0 ) {
+			return textResult(
+				'The manifest lists no pages, posts, or post types to seed. Nothing to do.'
+			);
+		}
+
+		const siteUrl = getSiteUrl( site ).replace( /\/+$/, '' );
+		const wsgUploads = uploadsDir( site.path );
+
+		const finalizeImages = async (
+			content: string,
+			fileBase: string
+		): Promise< { content: string; generated: number; failed: number } > => {
+			if ( ! withImages ) {
+				return { content, generated: 0, failed: 0 };
+			}
+			if ( ! imagesOk ) {
+				return { content: stripAiImagePlaceholders( content ), generated: 0, failed: 0 };
+			}
+			const resolution = await resolveAiImagesInHtml( content, async ( bytes, ctx ) => {
+				const fileName = `${ fileBase }-${ ctx.index }.png`;
+				await mkdir( wsgUploads, { recursive: true } );
+				await writeFile( path.join( wsgUploads, fileName ), bytes );
+				return `${ siteUrl }/wp-content/uploads/wsg/${ fileName }`;
+			} );
+			return {
+				content: resolution.html,
+				generated: resolution.generated,
+				failed: resolution.failed,
+			};
+		};
+
+		// --- Phase 1: generate all content (no daemon held; runs for a while). ---
+
+		const pagePrepared = await runPooled(
+			pageTargets.map( ( target ) => async () => {
+				try {
+					const body = await runGenerator( {
+						name: 'page-content',
+						specJson,
+						task: `Page post type: ${ target.postType }\nPage slug: ${ target.slug }\nPage title: ${
+							target.title
+						}\nComposition brief: ${
+							target.brief || '(none — infer from the spec and page title)'
+						}`,
+						maxTokens: 12_000,
+						temperature: 0.6,
+					} );
+					const img = await finalizeImages( body, target.slug );
+					const item: PreparedItem = {
+						postType: target.postType,
+						slug: target.slug,
+						title: target.title,
+						content: img.content,
+						meta: {},
+						isHome: target.isHome,
+					};
+					return {
+						item,
+						label: `${ target.postType }:${ target.slug }`,
+						generated: img.generated,
+						failed: img.failed,
+						error: null as string | null,
+					};
+				} catch ( error ) {
+					return {
+						item: null as PreparedItem | null,
+						label: `${ target.postType }:${ target.slug }`,
+						generated: 0,
+						failed: 0,
+						error: error instanceof Error ? error.message : String( error ),
+					};
+				}
+			} ),
+			Math.min( Math.max( pageTargets.length, 1 ), 5 )
+		);
+
+		const cptPrepared = await runPooled(
+			cptPlans.map( ( postType ) => async () => {
+				try {
+					const entries = await runCptEntries( specJson, postType, 4 );
+					const items: PreparedItem[] = [];
+					const usedSlugs = new Set< string >();
+					let generated = 0;
+					let failed = 0;
+					for ( const entry of entries ) {
+						let slug = deriveSlug( entry.title ) || postType.slug;
+						const base = slug;
+						let suffix = 1;
+						while ( usedSlugs.has( slug ) ) {
+							suffix += 1;
+							slug = `${ base }-${ suffix }`;
+						}
+						usedSlugs.add( slug );
+						const img = await finalizeImages( entry.content, `${ postType.slug }-${ slug }` );
+						generated += img.generated;
+						failed += img.failed;
+						items.push( {
+							postType: postType.slug,
+							slug,
+							title: entry.title,
+							content: img.content,
+							meta: entry.meta,
+							isHome: false,
+						} );
+					}
+					return { items, label: postType.slug, generated, failed, error: null as string | null };
+				} catch ( error ) {
+					return {
+						items: [] as PreparedItem[],
+						label: postType.slug,
+						generated: 0,
+						failed: 0,
+						error: error instanceof Error ? error.message : String( error ),
+					};
+				}
+			} ),
+			Math.min( Math.max( cptPlans.length, 1 ), 4 )
+		);
+
+		const prepared: PreparedItem[] = [];
+		const generationFailed: string[] = [];
+		const cptCounts: string[] = [];
+		let imagesGenerated = 0;
+		let imagesFailed = 0;
+
+		for ( const r of pagePrepared ) {
+			imagesGenerated += r.generated;
+			imagesFailed += r.failed;
+			if ( r.item ) {
+				prepared.push( r.item );
+			} else {
+				generationFailed.push( r.label );
+			}
+		}
+		for ( const r of cptPrepared ) {
+			imagesGenerated += r.generated;
+			imagesFailed += r.failed;
+			prepared.push( ...r.items );
+			if ( r.error ) {
+				generationFailed.push( `cpt:${ r.label }` );
+			} else {
+				cptCounts.push( `${ r.label }: ${ r.items.length }` );
+			}
+		}
+
+		// --- Phase 2: write content files + upsert into the DB (one connection). ---
+
+		const report = await withDaemon( async () => {
+			if ( ! ( await isSiteRunning( site.id ) ) ) {
+				throw new Error(
+					`Site "${ site.name }" is not running. Start it with site_start, then re-run seed_content.`
+				);
+			}
+			const abspath = await getAbspath( site.id );
+			const seedDirHost = path.join( site.path, 'wp-content', 'uploads', 'wsg-seed' );
+			await mkdir( seedDirHost, { recursive: true } );
+
+			const created: string[] = [];
+			const updated: string[] = [];
+			const failed: string[] = [];
+			let homeId: number | null = null;
+			let firstPageId: number | null = null;
+
+			for ( const item of prepared ) {
+				const fileName =
+					`${ item.postType }-${ item.slug }`.replace( /[^a-zA-Z0-9._-]/g, '-' ) + '.html';
+				await writeFile( path.join( seedDirHost, fileName ), item.content, 'utf8' );
+				// WP-CLI reads post content from this file path (no large arg over IPC).
+				const wpPath = `${ abspath }wp-content/uploads/wsg-seed/${ fileName }`;
+
+				const existingId = await findExistingPostId( site.id, item.postType, item.slug );
+				let postId: number | null = existingId;
+
+				if ( existingId ) {
+					const result = await wpCli( site.id, [
+						'post',
+						'update',
+						String( existingId ),
+						wpPath,
+						'--post_status=publish',
+						`--post_title=${ item.title }`,
+					] );
+					if ( result.exitCode === 0 ) {
+						updated.push( `${ item.postType }:${ item.slug }` );
+					} else {
+						failed.push(
+							`${ item.postType }:${ item.slug } (${ ( result.stderr || result.stdout )
+								.trim()
+								.slice( 0, 120 ) })`
+						);
+						continue;
+					}
+				} else {
+					const result = await wpCli( site.id, [
+						'post',
+						'create',
+						wpPath,
+						`--post_type=${ item.postType }`,
+						`--post_name=${ item.slug }`,
+						'--post_status=publish',
+						`--post_title=${ item.title }`,
+						'--porcelain',
+					] );
+					if ( result.exitCode === 0 ) {
+						const match = result.stdout.match( /\b\d+\b/ );
+						postId = match ? Number.parseInt( match[ 0 ], 10 ) : null;
+						if ( ! ( postId && postId > 0 ) ) {
+							postId = await findExistingPostId( site.id, item.postType, item.slug );
+						}
+						created.push( `${ item.postType }:${ item.slug }` );
+					} else {
+						failed.push(
+							`${ item.postType }:${ item.slug } (${ ( result.stderr || result.stdout )
+								.trim()
+								.slice( 0, 120 ) })`
+						);
+						continue;
+					}
+				}
+
+				if ( postId && postId > 0 ) {
+					for ( const [ key, value ] of Object.entries( item.meta ) ) {
+						await wpCli( site.id, [ 'post', 'meta', 'update', String( postId ), key, value ] );
+					}
+					if ( item.isHome ) {
+						homeId = postId;
+					}
+					if ( item.postType === 'page' && firstPageId === null ) {
+						firstPageId = postId;
+					}
+				}
+			}
+
+			if ( ! homeId && firstPageId && manifest.contentMode === 'homepage-and-pages' ) {
+				homeId = firstPageId;
+			}
+
+			let frontPage = '';
+			if ( homeId ) {
+				const showOnFront = await wpCli( site.id, [ 'option', 'update', 'show_on_front', 'page' ] );
+				const pageOnFront = await wpCli( site.id, [
+					'option',
+					'update',
+					'page_on_front',
+					String( homeId ),
+				] );
+				frontPage =
+					showOnFront.exitCode === 0 && pageOnFront.exitCode === 0
+						? `Set the home page (ID ${ homeId }) as the static front page.`
+						: 'Could not set the static front page automatically.';
+			}
+
+			return { created, updated, failed, frontPage };
+		} );
+
+		const imageNote =
+			withImages && ! imagesOk
+				? 'AI images skipped — not logged into WordPress.com. Run `studio auth login`, then re-run seed_content (or run generate_image) to fill imagery. Placeholders were removed so nothing renders broken.'
+				: '';
+
+		const summary = [
+			`Seeded content into ${ site.name }.`,
+			`Created: ${ report.created.length ? report.created.join( ', ' ) : 'none' }`,
+			`Updated: ${ report.updated.length ? report.updated.join( ', ' ) : 'none' }`,
+			cptCounts.length ? `CPT entries: ${ cptCounts.join( ' · ' ) }` : '',
+			generationFailed.length
+				? `Content generation FAILED for: ${ generationFailed.join(
+						', '
+				  ) }. Re-run seed_content to fill them (upsert is idempotent).`
+				: '',
+			report.failed.length ? `Database write failed: ${ report.failed.join( '; ' ) }` : '',
+			withImages && imagesOk
+				? `AI images: ${ imagesGenerated } generated, ${ imagesFailed } failed.`
+				: '',
+			imageNote,
+			report.frontPage,
+			'',
+			'NEXT: generate_image for any theme-level AI_IMAGE placeholders, then validate_and_fix_blocks + take_screenshot (viewport: "all") to verify.',
+		]
+			.filter( Boolean )
+			.join( '\n' );
+
+		return textResult( summary );
+	}
+);
diff --git a/tools/common/ai/slash-commands.ts b/tools/common/ai/slash-commands.ts
index 9af03e16b8..95fab3c313 100644
--- a/tools/common/ai/slash-commands.ts
+++ b/tools/common/ai/slash-commands.ts
@@ -6,6 +6,12 @@ export interface SkillSlashCommand {
 }
 
 export const AI_SKILL_COMMANDS: SkillSlashCommand[] = [
+	{
+		name: 'site-generator',
+		description: __(
+			'Generate a complete WordPress site — theme + companion plugin — from a description'
+		),
+	},
 	{ name: 'annotate', description: __( 'Annotate site elements visually in a browser' ) },
 	{ name: 'taxonomist', description: __( 'Optimize category taxonomy with AI' ) },
 	{ name: 'need-for-speed', description: __( 'Run a performance audit on a site' ) },