Agentic UI: Show "What's New"

apps/studio/src/constants.ts

@@ -66,8 +66,6 @@ export const IPC_VOID_HANDLERS = [
 	'authenticate',
 ] as const;
 
-// What's New
-// Flip to `true` when shipping new modal content so users who haven't seen the
-// current app version get the modal once. Keep at `false` otherwise — the modal
-// will only auto-show for first-time users of Studio.
-export const FORCE_SHOW_WHATS_NEW = false;
+// What's New. Defined in @studio/common so the agentic UI reads the same switch;
+// re-exported here so existing imports keep working.
+export { FORCE_SHOW_WHATS_NEW } from '@studio/common/lib/whats-new';

apps/studio/src/ipc-handlers.ts

@@ -167,6 +167,7 @@ import { isStudioCliInstalled } from 'src/modules/cli/lib/ipc-handlers';
 import { STABLE_BIN_DIR_PATH } from 'src/modules/cli/lib/windows-installation-manager';
 import { supportedEditorConfig, SupportedEditor } from 'src/modules/user-settings/lib/editor';
 import {
+	recordAgenticUiMigration,
 	getUserEditor,
 	getUserTerminal,
 	getDefaultSiteDirectory,
@@ -240,6 +241,7 @@ export {
 	getColorScheme,
 	getGlobalAgentInstructions,
 	getInstalledAppsAndTerminals,
+	getOnboardingHints,
 	getQuitSitesBehavior,
 	getUserEditor,
 	getUserLocale,
@@ -250,6 +252,7 @@ export {
 	saveAnalyticsEnabled,
 	saveColorScheme,
 	saveGlobalAgentInstructions,
+	saveOnboardingHints,
 	saveQuitSitesBehavior,
 	saveUserEditor,
 	saveUserLocale,
@@ -1531,6 +1534,10 @@ export async function getBetaFeatures( _event: IpcMainInvokeEvent ): Promise< Be
 export async function enableAgenticUi( _event: IpcMainInvokeEvent ): Promise< void > {
 	await updateBetaFeatureInLib( 'enableAgenticUi', true );
 	setAgenticUiEnabled( true );
+	// Opting in from classic Studio is the sole way an existing user reaches the
+	// agentic workbench, so record it here for the orientation guide's migrating
+	// copy. Must land before the renderer reloads below so the guide sees it.
+	await recordAgenticUiMigration();
 	const mainWindow = await getMainWindow();
 	if ( mainWindow && ! mainWindow.isDestroyed() ) {
 		await loadMainWindowRenderer( mainWindow );

apps/studio/src/ipc-utils.ts

@@ -46,6 +46,7 @@ export interface IpcEvents {
 	'snapshot-key-value': [ { operationId: crypto.UUID; data: SnapshotKeyValueEventData } ];
 	'snapshot-success': [ { operationId: crypto.UUID } ];
 	'show-whats-new': [ void ];
+	'show-getting-started': [ void ];
 	'sync-connect-site': [
 		{
 			remoteSiteId: number;

apps/studio/src/menu.ts

@@ -424,6 +424,13 @@ async function getAppMenu(
 					},
 					enabled: ! needsOnboarding,
 				},
+				{
+					label: __( 'Getting Started' ),
+					click: async () => {
+						void sendIpcEventToRenderer( 'show-getting-started' );
+					},
+					enabled: ! needsOnboarding,
+				},
 				{ type: 'separator' },
 				...( process.platform === 'win32'
 					? [

apps/studio/src/modules/user-settings/lib/ipc-handlers.ts

@@ -13,6 +13,7 @@ import { SUPPORTED_EDITORS, SupportedEditor } from 'src/modules/user-settings/li
 import { SupportedTerminal } from 'src/modules/user-settings/lib/terminal';
 import { UserSettingsTabName } from 'src/modules/user-settings/user-settings-types';
 import { defaultSitePath, ensureWritableDirectory } from 'src/storage/paths';
+import { OnboardingHintsState } from 'src/storage/storage-types';
 import {
 	loadUserData,
 	lockAppdata,
@@ -195,6 +196,42 @@ export async function getWapuuScore(): Promise< number | undefined > {
 	return userData.wapuuScore;
 }
 
+// Agentic UI onboarding state (orientation guide seen-state, migration marker).
+// The blob is opaque to the desktop; the renderer owns its meaning.
+export async function getOnboardingHints(): Promise< OnboardingHintsState > {
+	const userData = await loadUserData();
+	return userData.onboardingHints ?? {};
+}
+
+async function persistOnboardingHints( partial: Partial< OnboardingHintsState > ): Promise< void > {
+	if ( ! partial || typeof partial !== 'object' ) {
+		return;
+	}
+	await lockAppdata();
+	try {
+		const userData = await loadUserData();
+		const merged: OnboardingHintsState = { ...( userData.onboardingHints ?? {} ), ...partial };
+		await saveUserData( { ...userData, onboardingHints: merged } );
+	} finally {
+		await unlockAppdata();
+	}
+}
+
+export async function saveOnboardingHints(
+	_event: IpcMainInvokeEvent,
+	partial: Partial< OnboardingHintsState >
+): Promise< void > {
+	await persistOnboardingHints( partial );
+}
+
+// Marks that the user reached the agentic workbench by opting in from classic
+// Studio, so the orientation guide can greet them as a migrating user. Fresh
+// installs get the agentic UI seeded on by default (migration 09) and never
+// hit this path, so they stay "new".
+export async function recordAgenticUiMigration(): Promise< void > {
+	await persistOnboardingHints( { migratedFromClassic: true } );
+}
+
 export async function getGlobalAgentInstructions(): Promise< string > {
 	return ( await readGlobalInstructionsFile() ) ?? '';
 }

apps/studio/src/modules/whats-new/components/whats-new-modal.tsx

@@ -1,15 +1,15 @@
 import interpolateComponents from '@automattic/interpolate-components';
+import cliIllustration from '@studio/common/assets/whats-new/cli.svg';
+import darkModeIllustration from '@studio/common/assets/whats-new/dark-mode.svg';
+import nativePhpIllustration from '@studio/common/assets/whats-new/native-php.svg';
+import phpMyAdminIllustration from '@studio/common/assets/whats-new/phpmyadmin.svg';
+import studioCodeIllustration from '@studio/common/assets/whats-new/studio-code.svg';
 import { Guide } from '@wordpress/components';
 import { __, sprintf } from '@wordpress/i18n';
 import { ReactNode } from 'react';
 import { cx } from 'src/lib/cx';
 import { getIpcApi } from 'src/lib/get-ipc-api';
 import { getLocalizedLink } from 'src/lib/get-localized-link';
-import cliIllustration from 'src/modules/whats-new/assets/cli-illustration.svg';
-import darkModeIllustration from 'src/modules/whats-new/assets/dark-mode-illustration.svg';
-import nativePhpIllustration from 'src/modules/whats-new/assets/native-php-illustration.svg';
-import phpMyAdminIllustration from 'src/modules/whats-new/assets/phpmyadmin-illustration.svg';
-import studioCodeIllustration from 'src/modules/whats-new/assets/studio-code-illustration.svg';
 import { useI18nLocale } from 'src/stores';
 
 interface WhatsNewPage {

apps/studio/src/preload.ts

@@ -179,6 +179,8 @@ const api: IpcApi = {
 	getAgenticFeaturesEnabled: () => ipcRendererInvoke( 'getAgenticFeaturesEnabled' ),
 	saveWapuuScore: ( score ) => ipcRendererInvoke( 'saveWapuuScore', score ),
 	getWapuuScore: () => ipcRendererInvoke( 'getWapuuScore' ),
+	getOnboardingHints: () => ipcRendererInvoke( 'getOnboardingHints' ),
+	saveOnboardingHints: ( partial ) => ipcRendererInvoke( 'saveOnboardingHints', partial ),
 	getUserEditor: () => ipcRendererInvoke( 'getUserEditor' ),
 	saveUserEditor: ( editor ) => ipcRendererInvoke( 'saveUserEditor', editor ),
 	comparePaths: ( path1, path2 ) => ipcRendererInvoke( 'comparePaths', path1, path2 ),

apps/studio/src/storage/storage-types.ts

@@ -57,6 +57,8 @@ export interface UserData {
 	// Whether chat/agent features are offered inside the new UI. Distinct from
 	// `betaFeatures.enableAgenticUi`, which picks the renderer (new vs classic).
 	agenticFeaturesEnabled?: boolean;
+	/** Agentic UI onboarding state (orientation tour, getting-started checklist). Opaque blob owned by the renderer. */
+	onboardingHints?: OnboardingHintsState;
 }
 
 export interface PromptWindowsSpeedUpResult {
@@ -65,6 +67,15 @@ export interface PromptWindowsSpeedUpResult {
 	dontAskAgain: boolean;
 }
 
+// Mirror of the renderer's OnboardingHintsState (apps/ui/src/data/core/types.ts).
+// Persisted verbatim; the desktop never inspects it, so a structural shape keeps
+// the two sides decoupled.
+export interface OnboardingHintsState {
+	tourCompletedVersion?: number;
+	tourDismissedVersion?: number;
+	migratedFromClassic?: boolean;
+}
+
 export const EMPTY_USER_DATA: UserData = {
 	version: 1,
 	siteMetadata: {},

apps/studio/src/storage/user-data.ts

@@ -83,6 +83,7 @@ type UserDataSafeKeys =
 	| 'cliAutoInstalled'
 	| 'cliUserUninstalled'
 	| 'wapuuScore'
+	| 'onboardingHints'
 	| 'lastNightlyUpdateCheck'
 	| 'nightlyPromptResult'
 	| 'agenticUiBannerDismissed'

apps/ui/src/app/app-providers.tsx

@@ -4,6 +4,7 @@ import { I18nProvider } from '@wordpress/react-i18n';
 import { privateApis } from '@wordpress/theme';
 import { Tooltip } from '@wordpress/ui';
 import { useEffect } from 'react';
+import { OnboardingGuideProvider } from '@/components/onboarding-guide/use-onboarding-guide';
 import { ConnectorProvider, queryClient } from '@/data/core';
 import { AgentRunProvider } from '@/data/queries/use-agent-run';
 import { useSyncAppUpdateStatus } from '@/data/queries/use-app-update';
@@ -42,7 +43,9 @@ function ThemedApp( { children }: PropsWithChildren ) {
 	}, [ colorScheme ] );
 	return (
 		<ThemeProvider isRoot color={ themeColor } density="compact">
-			<Tooltip.Provider>{ children }</Tooltip.Provider>
+			<Tooltip.Provider>
+				<OnboardingGuideProvider>{ children }</OnboardingGuideProvider>
+			</Tooltip.Provider>
 		</ThemeProvider>
 	);
 }

apps/ui/src/components/onboarding-guide/illustrations.tsx

@@ -0,0 +1,40 @@
+import cliIllustration from '@studio/common/assets/whats-new/cli.svg';
+import darkModeIllustration from '@studio/common/assets/whats-new/dark-mode.svg';
+import nativePhpIllustration from '@studio/common/assets/whats-new/native-php.svg';
+import phpMyAdminIllustration from '@studio/common/assets/whats-new/phpmyadmin.svg';
+import studioCodeIllustration from '@studio/common/assets/whats-new/studio-code.svg';
+import { __, sprintf } from '@wordpress/i18n';
+import styles from './style.module.css';
+import type { GuideIllustrationId } from '@/data/onboarding/guide';
+
+// Shared with the classic renderer's What's New modal. The orientation ids have
+// no art yet and fall through to the tinted placeholder slot below.
+const ILLUSTRATIONS: Partial< Record< GuideIllustrationId, string > > = {
+	'studio-code': studioCodeIllustration,
+	'native-php': nativePhpIllustration,
+	'dark-mode': darkModeIllustration,
+	phpmyadmin: phpMyAdminIllustration,
+	cli: cliIllustration,
+};
+
+export function hasIllustration( id: GuideIllustrationId ): boolean {
+	return Boolean( ILLUSTRATIONS[ id ] );
+}
+
+export function GuideIllustration( { id, title }: { id: GuideIllustrationId; title: string } ) {
+	const source = ILLUSTRATIONS[ id ];
+	if ( ! source ) {
+		return <div className={ styles.illustration } data-illustration={ id } />;
+	}
+	return (
+		<img
+			className={ styles.illustration }
+			src={ source }
+			alt={ sprintf(
+				/* translators: %s is the title of the guide page the illustration belongs to. */
+				__( 'Illustration for %s' ),
+				title
+			) }
+		/>
+	);
+}

apps/ui/src/components/onboarding-guide/index.tsx

@@ -0,0 +1,128 @@
+import { __ } from '@wordpress/i18n';
+import { Button, Dialog, Text, VisuallyHidden } from '@wordpress/ui';
+import { clsx } from 'clsx';
+import { useRef, useState } from 'react';
+import { LearnMoreLink } from '@/components/learn-more';
+import { GuideIllustration, hasIllustration } from './illustrations';
+import styles from './style.module.css';
+import type { GuideDefinition } from '@/data/onboarding/guide';
+
+interface OnboardingGuideProps {
+	guide: GuideDefinition;
+	onComplete: () => void;
+	onDismiss: () => void;
+}
+
+// A focused, paged orientation modal in the spirit of Gutenberg's Guide:
+// full-bleed illustration on top, copy in the middle, a dot pager and
+// Back/Next at the bottom. It demands attention — a backdrop, no click-outside
+// dismissal — so the welcome isn't lost with a stray click.
+export function OnboardingGuide( { guide, onComplete, onDismiss }: OnboardingGuideProps ) {
+	const [ pageIndex, setPageIndex ] = useState( 0 );
+	const page = guide.pages[ pageIndex ];
+	const isFirst = pageIndex === 0;
+	const isLast = pageIndex === guide.pages.length - 1;
+	// Reserve the link row for the whole guide, not per page, so paging through a
+	// guide where only some pages link out doesn't resize the modal.
+	const reservesLearnMore = guide.pages.some( ( { learnMore } ) => learnMore );
+	// Without this the dialog focuses the first tabbable child, which on a page
+	// that links out is the "Learn more" link — so Enter would open the docs
+	// instead of advancing.
+	const advanceRef = useRef< HTMLButtonElement >( null );
+
+	const goNext = () => {
+		if ( isLast ) {
+			onComplete();
+		} else {
+			setPageIndex( ( index ) => index + 1 );
+		}
+	};
+	const goBack = () => setPageIndex( ( index ) => Math.max( 0, index - 1 ) );
+
+	return (
+		<Dialog.Root
+			open
+			modal
+			// No dismissal by clicking the backdrop — only the close button, Esc,
+			// or finishing the guide.
+			disablePointerDismissal
+			onOpenChange={ ( open, details ) => {
+				if ( open ) {
+					return;
+				}
+				if ( details.reason === 'escape-key' || details.reason === 'close-press' ) {
+					onDismiss();
+				}
+			} }
+		>
+			<Dialog.Popup
+				size="small"
+				className={ styles.popup }
+				initialFocus={ advanceRef }
+				data-orientation-guide
+			>
+				<GuideIllustration id={ page.illustration } title={ page.title() } />
+				<Dialog.CloseIcon
+					label={ __( 'Skip' ) }
+					className={ clsx(
+						styles.close,
+						hasIllustration( page.illustration ) && styles.closeOverArt
+					) }
+				/>
+				<Dialog.Content className={ styles.content }>
+					{ /* The dialog's accessible name and description follow the active page.
+					     The visible copy is rendered separately below so that every page can
+					     share one grid cell. */ }
+					<VisuallyHidden render={ <Dialog.Title /> }>{ page.title() }</VisuallyHidden>
+					<VisuallyHidden render={ <Dialog.Description /> }>{ page.description() }</VisuallyHidden>
+					{ /* All pages occupy the same grid cell, so the box is as tall as the
+					     longest one and advancing never resizes the modal. Rendering them
+					     identically — rather than measuring the active page — is what keeps
+					     the height honest once translations change the copy. */ }
+					{ guide.pages.map( ( guidePage, index ) => (
+						<div
+							key={ index }
+							className={ clsx( styles.page, index !== pageIndex && styles.pageHidden ) }
+						>
+							<Text variant="heading-xl" className={ styles.title }>
+								{ guidePage.title() }
+							</Text>
+							<Text variant="body-md" className={ styles.description }>
+								{ guidePage.description() }
+							</Text>
+							{ reservesLearnMore ? (
+								<div className={ styles.learnMoreRow }>
+									{ guidePage.learnMore ? (
+										<LearnMoreLink docsLinksKey={ guidePage.learnMore } />
+									) : null }
+								</div>
+							) : null }
+						</div>
+					) ) }
+				</Dialog.Content>
+				<Dialog.Footer className={ styles.footer }>
+					<div className={ styles.footerStart }>
+						{ ! isFirst ? (
+							<Button variant="minimal" tone="neutral" onClick={ goBack }>
+								{ __( 'Back' ) }
+							</Button>
+						) : null }
+					</div>
+					<div className={ styles.pager } aria-hidden="true">
+						{ guide.pages.map( ( _, index ) => (
+							<span
+								key={ index }
+								className={ clsx( styles.dot, index === pageIndex && styles.dotActive ) }
+							/>
+						) ) }
+					</div>
+					<div className={ styles.footerEnd }>
+						<Button ref={ advanceRef } variant="solid" tone="brand" onClick={ goNext }>
+							{ page.action() }
+						</Button>
+					</div>
+				</Dialog.Footer>
+			</Dialog.Popup>
+		</Dialog.Root>
+	);
+}