Content Guidelines: Add AI-powered generate/improve UI via Jetpack

[aagam-shah]

Summary

Adds AI-powered guideline generation to the WordPress Content Guidelines admin page via Jetpack. Supports both section-level (site, copy, images, additional) and block-level (per-block) guidelines with word-level diffs for review.

What it does

Section-level AI

• Onboarding banner: Jetpack-branded card with "Get started" CTA — shown (regardless of existing guidelines) until the user interacts with it once ("Get started" or dismiss); dismissal is remembered in localStorage. The header button stays hidden while the banner is visible.
• Header button: "Generate / Improve guidelines" with Jetpack logo — batch generation for all sections
• Per-section buttons: "Generate / Improve guidelines" in each accordion's button row
• Loading states: Green shimmer on textareas + spinner badges in accordion headers
• Suggestion preview: Word-level diff (green additions, red strikethrough) with Accept / Dismiss
• Height matching: Diff container matches textarea height, with fallback for collapsed accordions

Block-level AI

• Improve/Generate button in block edit modal action bar
• Shimmer loading on textarea (applied directly as background, not on label wrapper)
• Diff view replaces textarea, with click-to-accept
• Accept/Dismiss buttons on separate row above modal action bar

Plan gating

• Uses useAiFeature() hook from @automattic/jetpack-ai-client — checks hasFeature to gate to Jetpack AI / Complete plans only (no free tier access)
• useAICheckout() provides checkout URL for upgrade CTA
• Upgrade notice with "Upgrade" button shown when user lacks AI plan
• All generate/improve buttons disabled when !hasFeature

Automattician gate

• Feature gated to Automatticians during internal rollout
• Simple sites: wpcom_is_proxied_request() + is_automattician()
• Atomic sites: Visitor::is_automattician_feature_flags_only()

Shared components

• DiffView: Shared diff rendering component used by both sections and blocks
• setTextareaValue / acceptBlockSuggestion: Shared DOM helpers in lib/dom.js
• SCSS color tokens: $cg-green, $cg-green-light, $cg-diff-added, $cg-diff-removed

Tracking (Tracks events)

• jetpack_ai_guidelines_generate — section/block generate or improve (type, slug, action)
• jetpack_ai_guidelines_generate_all — global suggest all (action)
• jetpack_ai_guidelines_accept — accept a suggestion (type, slug)
• jetpack_ai_guidelines_dismiss — dismiss a suggestion (type, slug)
• jetpack_ai_upgrade_button — reuses existing event with placement: "content-guidelines"

API proxy

• PHP proxy endpoint at wpcom/v2/jetpack-ai/suggest-guidelines
• Passes categories object through to wpcom (sections as top-level keys, blocks under categories.blocks)
• 90-second timeout for AI generation

Architecture

Uses DOM injection — Jetpack enqueues a standalone JS+CSS bundle on settings_page_guidelines-wp-admin, uses MutationObserver to inject React components into Gutenberg's Content Guidelines page, and shares state via wp.data stores (jetpack/content-guidelines-ai for suggestions, wordpress-com/plans for plan detection).

Related

• Design P2: p9Jlb4-gT7-p2
• Prototype: Try: Content Guidelines with AI-powered suggestions WordPress/gutenberg#76680 (exploration B)
• Backend proxy: Jetpack AI: Add suggest-guidelines proxy endpoint (FORNO-186) #47479
• Backend wpcom: 206460-ghe-Automattic/wpcom

Testing instructions

1. Build: pnpm jetpack build plugins/jetpack
2. Enable Gutenberg content-guidelines experiment
3. Navigate to Settings > Guidelines

Testing on an Atomic site:

Out of the box this won't work on Atomic during the internal rollout: the wpcom endpoint's development gate requires an Automattician user, but the proxy authenticates with a blog token (no user attached) — so generation fails with 401 rest_forbidden even on a site with an AI plan (#47959 (comment)). The UI's Automattician gate also only passes when browsing through the proxy. Apply the patch below to test.

🩹 Patch for testing on Atomic (click to expand)

What it does:

• Re-adds the ?enable_ai_generation=true query-param bypass for the Automattician UI gate (removed from the shipped code in fc8d4b7).
• Switches the proxy call from wpcom_json_api_request_as_blog to wpcom_json_api_request_as_user, so the request is authenticated as your connected WordPress.com user and passes the wpcom-side Automattician gate. Your a11n WordPress.com account must be connected to Jetpack on the site for this to work.

SSH into the site and run this from the plugin directory (jetpack-dev when installed via Jetpack Beta, jetpack otherwise):

cd ~/htdocs/wp-content/plugins/jetpack-dev

patch -p1 -l << 'PATCH'
diff -ru a/_inc/content-guidelines-ai.php b/_inc/content-guidelines-ai.php
--- a/_inc/content-guidelines-ai.php	2026-06-12 12:14:27
+++ b/_inc/content-guidelines-ai.php	2026-06-12 12:14:47
@@ -25,6 +25,12 @@
  * @return bool
  */
 function jetpack_content_guidelines_ai_is_automattician() {
+	// TESTING ONLY: allow access via query parameter.
+	// phpcs:ignore WordPress.Security.NonceVerification.Recommended
+	if ( isset( $_GET['enable_ai_generation'] ) && 'true' === $_GET['enable_ai_generation'] ) {
+		return true;
+	}
+
 	// Simple sites.
 	if ( function_exists( 'wpcom_is_proxied_request' )
 		&& wpcom_is_proxied_request()
diff -ru a/_inc/lib/core-api/wpcom-endpoints/class-wpcom-rest-api-v2-endpoint-agent-guidelines-ai.php b/_inc/lib/core-api/wpcom-endpoints/class-wpcom-rest-api-v2-endpoint-agent-guidelines-ai.php
--- a/_inc/lib/core-api/wpcom-endpoints/class-wpcom-rest-api-v2-endpoint-agent-guidelines-ai.php	2026-06-12 12:14:27
+++ b/_inc/lib/core-api/wpcom-endpoints/class-wpcom-rest-api-v2-endpoint-agent-guidelines-ai.php	2026-06-12 12:14:47
@@ -97,7 +97,10 @@
 			'categories' => $request->get_param( 'categories' ),
 		);
 
-		$response = Client::wpcom_json_api_request_as_blog(
+		// TESTING ONLY: request as the connected user so the wpcom-side
+		// Automattician development gate passes (a blog token carries no
+		// user and is rejected with 401 rest_forbidden).
+		$response = Client::wpcom_json_api_request_as_user(
 			sprintf( '/sites/%d/jetpack-ai/suggest-guidelines', $blog_id ) . '?force=wpcom',
 			'2',
 			array(
PATCH

Then open Settings → Guidelines with the query param appended:

/wp-admin/options-general.php?page=guidelines-wp-admin&enable_ai_generation=true

To undo, re-run the same patch command with -R added.

Section-level:
4. Verify the onboarding banner with "Get started" button (shown on first visit until dismissed or used once; clear the jetpack_content_guidelines_banner_dismissed localStorage key to see it again)
5. Click "Get started" — shimmer on textareas, spinners in headers
6. After generation: diff view with Accept / Dismiss
7. Accept — content moves to textarea. Dismiss — suggestion removed.
8. Navigate to history and back — injections re-appear

Block-level:
9. Open Blocks section, click Edit on a block
10. Click "Improve guidelines" in modal — shimmer on textarea
11. Diff appears, Accept/Dismiss below. Click-to-accept on diff works.

Plan gating:
12. On a site without Jetpack AI plan: upgrade notice shown, buttons disabled
13. On a site with Jetpack AI/Complete: full access

Does this pull request change what data or activity we track or use?

Yes. This PR adds Tracks events for guideline generation, acceptance, dismissal, and upgrade clicks (see Tracking section above). It also calls the Jetpack AI suggest-guidelines endpoint when users explicitly click generate/improve buttons.

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the add/content-guidelines-plugin-extensibility branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack add/content-guidelines-plugin-extensibility

bin/jetpack-downloader test jetpack-mu-wpcom-plugin add/content-guidelines-plugin-extensibility

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[jp-launch-control]

Code Coverage Summary

Coverage changed in 1 file.

File	Coverage	Δ%	Δ Uncovered
projects/plugins/jetpack/load-jetpack.php	0/49 (0.00%)	0.00%	2 ❤️‍🩹

2 files are newly checked for coverage.

File	Coverage
projects/plugins/jetpack/_inc/content-guidelines-ai.php	0/27 (0.00%) 💔
projects/plugins/jetpack/_inc/lib/core-api/wpcom-endpoints/class-wpcom-rest-api-v2-endpoint-agent-guidelines-ai.php	0/58 (0.00%) 💔

Full summary · PHP report · JS report

_{If appropriate, add one of these labels to override the failing coverage check: Covered by non-unit tests Use to ignore the Code coverage requirement check when E2Es or other non-unit tests cover the code Coverage tests to be added later Use to ignore the Code coverage requirement check when tests will be added in a follow-up PR I don't care about code coverage for this PR Use this label to ignore the check for insufficient code coveage.}

[fditrapani]

Thanks for getting this started @aagam-shah. Here are a few comments based on what I see right now:

1. Badges
It looks like we're using custom badges. Can we use these instead: https://wordpress.github.io/gutenberg/?path=/docs/components-badge--docs

2. Suggestions

The suggestions are presented in what appears like a disabled field:

The container should look and behave like a regular input (but have a green border). We need to match the height of the input (and visa versa) to prevent layout shift. We also can accept a suggestion if someone clicks on the suggestion to start editing it. When the section is open, we don't need to show the suggestion badge any longer since the input + buttons communicate the suggestion.

This is what I had in the design:

3. Banner behaviour

The main banner dismisses if you generate a suggestion from within a section. The causes the layout to shift and feels jarring. The banner should only dismiss if the user dismisses it or the main call to action is used to generate guidelines for all the sections.

4. Block suggestions

I'm not seeing any block suggestions being added. Are you planning on adding those separately? We should have suggestions for the block section as well as the blocks themselves.

[aagam-shah]

Thanks for the detailed feedback @fditrapani! Here's where we're at on each point:

1. Badges
I have am using Jetpack's Badge component because using the Gutenberg Badge from @wordpress/ui would require adding a new dependency to the Jetpack plugin just for this. Happy to revisit if you feel strongly about using the Gutenberg one — it would need @wordpress/ui added to package.json.

2. Suggestions
Addressed — the suggestion container now matches the Gutenberg textarea styling (same padding, border-radius, 1px green border, dynamic height to prevent layout shift). Clicking anywhere on the diff accepts the suggestion. The badge also hides when the accordion is expanded since the Accept/Dismiss buttons already communicate the state.

3. Banner behaviour
Fixed — the banner now only dismisses when the user explicitly clicks "Get started" or "Close" / X. Per-section generation no longer affects it. Dismiss state is persisted via localStorage so it survives page reloads.

4. Block suggestions
Not included in this PR — planning to add those as a follow-up. The backend already supports the 4 main sections (site, copy, images, additional) but block-level generation will need additional work on both the API and UI side.

[fditrapani]

Thanks for the updates @aagam-shah!

I have am using Jetpack's Badge component because using the Gutenberg Badge from @wordpress/ui would require adding a new dependency to the Jetpack plugin just for this. Happy to revisit if you feel strongly about using the Gutenberg one — it would need @wordpress/ui added to package.json.

Sounds good to me if this is the badge we're already using. I understand we're updating components but hopefully this will get updates along with the others when that happens.

Addressed — the suggestion container now matches the Gutenberg textarea styling (same padding, border-radius, 1px green border, dynamic height to prevent layout shift). Clicking anywhere on the diff accepts the suggestion. The badge also hides when the accordion is expanded since the Accept/Dismiss buttons already communicate the state.

Thanks for the updates. This is looking better. We still have some shifting happening if the text area isn't the default size:

Screen.Recording.2026-04-08.at.12.51.15.PM.mov

Fixed — the banner now only dismisses when the user explicitly clicks "Get started" or "Close" / X. Per-section generation no longer affects it. Dismiss state is persisted via localStorage so it survives page reloads.

Nice! looking better here too. I noticed a bug where the banner unexpectedly goes away if you accept a suggestion.

Screen.Recording.2026-04-08.at.12.53.02.PM.mov

Jetpack logo

I got some feedback from Devin that the logo should be reversed instead of the regular colour. (p1775665181650579/1775564866.152469-slack-C08NFD7RA58)

Can we update the logo to look like this:

[aagam-shah]

Thanks @fditrapani! Here's an update on the latest changes:

1. Suggestions UX — Updated:

• Diff container now matches the Gutenberg textarea styling (1px green border, same padding/border-radius, white background)
• Clicking anywhere on the diff accepts the suggestion
• Badge hides when accordion is expanded
• Height captured from textarea before hiding to prevent layout shift
• Diff container is also resizable

2. Banner behaviour — Fixed:

• Banner only dismisses on "Get started", "Close", or X button click
• Per-section generation no longer hides the banner
• Dismiss state persisted via wp.data store + localStorage
• Header button hidden while banner is visible

3. Block suggestions — Still planned as a follow-up.

4. Upgrade notice — Added a persistent warning Notice (instead of snackbar) with a "View plans" button when AI is unavailable. Matches the standard WordPress notice pattern.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

[aagam-shah]

Hey @fditrapani 👋 - quick design question on the Content Guidelines AI banner (the "Generate your guidelines in seconds" card).

What's the expected behavior:

1. Show until dismissed — appears at least once even if some guidelines already have content; stays until the user clicks Get started / Close / X. Header button takes over after that.
2. Only when all empty — hides as soon as any section has content.

I built it as 1 (persisted so it doesn't come back once dismissed), but want to confirm that's what you intended.

Also, how should "dismissed" be scoped?

• Per-browser (current) — dismiss only sticks on that browser/device.
• Per-user — remembered for that user across their devices.
• Per-site — once any admin dismisses it, no one on the site sees it again.

[fditrapani]

Thanks for the ping @aagam-shah. #1 is exactly how I envisioned it to work. Glad that you went in that direction. I think the per-user approach makes most sense. Once you understand how it works, there's no need to see it again.

[aagam-shah]

Sure, @fditrapani - I’ll handle the per-user part in a separate PR, since this one is already fairly large.

[t-wright]

Just a reminder that we should probably remove this