Knowledge: add a Knowledge and Guidelines experiment

[gziolo]

Background

In June, the Merge Proposal: Guidelines built on Knowledge asked to bring the wp_knowledge post type and the Guidelines page into WordPress 7.1. The feedback was mixed. Several people felt the design was not proven yet and asked for a full release cycle in a plugin first. On July 10 the proposal was declined for 7.1. The stated bar for core is real-world adoption with strong week-to-week growth.

This PR is a step toward that bar. Shipping the feature as an experiment in the AI plugin lets it reach sites that do not run the Gutenberg plugin, so it can gather real usage and feedback before another proposal.

What?

Adds a new Knowledge and Guidelines experiment. When it is enabled, the AI plugin stores site guidelines in the wp_knowledge post type and adds a Settings → Guidelines page to manage them.

Both parts are ported from the Gutenberg plugin: lib/experimental/knowledge and routes/guidelines. The port stays as close to the upstream code as possible, so future Gutenberg changes are easy to bring over.

Why?

Site guidelines give AI features useful context about the site's purpose, voice, and style. Since #988, the AI plugin reads them from wp_knowledge. But it had no way to create or edit them. That only worked when the Gutenberg plugin was installed with its gutenberg-guidelines experiment turned on.

With this PR, the AI plugin can provide the storage and the settings page on its own.

How?

One feature, two plugins: the first to declare it wins

Gutenberg ships the same feature. Both plugins share one contract: the wp_knowledge post type, the /wp/v2/knowledge REST routes, and a small set of shared wp_* helper functions. So only one plugin may provide it at a time.

This PR follows the same rules Gutenberg already uses, so neither side needs to know about the other:

• Shared helper functions are wrapped in function_exists() guards.
• Classes have distinct names, so there is never a redeclare error.
• The post type is registered only when it does not exist yet. The experiment remembers whether it did the registration.

The scopes REST route and the Settings page are registered only when this plugin owns the feature. So there is never a duplicate page or a duplicate route.

Gutenberg registers on init at priority 10. This experiment runs at priority 15. As a result, Gutenberg wins whenever its flag is on. The AI plugin takes over when the flag is off or Gutenberg is not installed. The page URL is the same in both cases: options-general.php?page=guidelines-wp-admin.

Owning versus extending

Other plugins do not need to own the feature to add to it. To add a scope or a knowledge type, use the wp_guideline_scopes and wp_knowledge_types filters. They work no matter which plugin owns the base implementation, and the Settings page grows a new section automatically. docs/experiments/knowledge.md has an example.

What changed in the port

The PHP moved into namespaced classes under includes/Experiments/Knowledge/ and plugs into the plugin's experiment framework. The UI is a wp-build route under routes/guidelines/.

Two things had to be adapted rather than copied:

• Gutenberg's route uses a private API from @wordpress/blocks to decide which blocks can carry guidelines. A plugin cannot unlock it, so the route reimplements the same check with public APIs.
• The route inherits a few experimental @wordpress/components imports (VStack, HStack, Heading, ConfirmDialog). @wordpress/ui does not cover all of them yet. To keep the port close to upstream, the lint rule for these imports is turned off for routes/guidelines/ only. Happy to swap them out instead if reviewers prefer.

Smaller adjustments: the ai text domain was added, the stricter TypeScript settings of this repo were satisfied, and SCSS variables were replaced with plain values because @wordpress/base-styles is not a dependency here.

docs/experiments/knowledge.md describes the feature, the ownership rule, the capabilities model, and how to extend it.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Reading the Gutenberg source, writing the port and the adaptation work, and drafting the tests and docs. All of it was reviewed and adjusted by me.

Testing Instructions

Without Gutenberg

1. Enable the Knowledge and Guidelines experiment under Settings → AI.
2. Go to Settings → Guidelines. Sections for Site, Copy, Images, Blocks, and Additional should be there.
3. Save some text into Site and Copy, then reload. The text should still be there.
4. Open the Blocks section, choose Add, pick a block, and save. It should appear in the list.
5. Use Export to download the JSON, clear a guideline, then Import the file back.
6. Confirm the guidelines reach a prompt. Enable Title Generation, generate a title, and check the request in AI Request Logs for a <guidelines> block.

With Gutenberg, gutenberg-guidelines on

7. Turn on the Gutenberg experiment and reload wp-admin. There should be exactly one Settings → Guidelines item, served by Gutenberg, at the same URL as before.
8. Confirm the AI plugin still reads those guidelines into prompts, as in step 6.

With Gutenberg, gutenberg-guidelines off

9. Turn the Gutenberg experiment off. The AI plugin should take over the page again, with the data intact.

Automated

npm run build
npm run typecheck
npm run lint:js
npm run lint:php
npm run lint:php:stan
npm run test:php
npm run test:e2e

All pass. New PHP tests cover the experiment, including that it stands down when the post type already exists. The e2e spec is a port of Gutenberg's Guidelines spec. It covers the Settings menu link, saving and clearing guidelines, block guidelines, export and import, focus handling, and a plugin that filters the scopes registry. The E2E Testing helper plugin gained a small REST toggle for that last scenario.

Screenshots or screencast

Before	After

Changelog Entry

Added - New Experiment: Knowledge and Guidelines; stores site guidelines in the shared wp_knowledge post type and adds a Settings → Guidelines page. It stands down when another plugin, such as Gutenberg, already provides the same feature.

🤖 Generated with Claude Code

[github-actions]

✅ WordPress Plugin Check Report

✅ Status: Passed

📊 Report

All checks passed! No errors or warnings found.

---

🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

[codecov]

Codecov Report

❌ Patch coverage is 72.55370% with 115 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.31%. Comparing base (813c81d) to head (eb3cec8).
⚠️ Report is 6 commits behind head on develop.

Files with missing lines	Patch %	Lines
includes/Experiments/Knowledge/Admin_Page.php	0.00%	45 Missing ⚠️
...udes/Experiments/Knowledge/knowledge-functions.php	74.35%	40 Missing ⚠️
...xperiments/Knowledge/Knowledge_REST_Controller.php	3.33%	29 Missing ⚠️
includes/Experiments/Knowledge/Knowledge.php	95.23%	1 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #949      +/-   ##
=============================================
- Coverage      75.37%   75.31%   -0.07%     
- Complexity      3357     3405      +48     
=============================================
  Files            138      144       +6     
  Lines          12976    13395     +419     
=============================================
+ Hits            9781    10088     +307     
- Misses          3195     3307     +112     

Flag	Coverage Δ
unit	75.31% <72.55%> (-0.07%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dkotter]

@gziolo This part:

It also fixes the Guidelines service, which had quietly stopped working

I think is fairly important. Wondering if we should extract that piece out to it's own PR so we can get that merged and fixed sooner.

[gziolo]

@dkotter, extracted the fix for Guidelines into #988.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[jeffpaul]

@gziolo I'm not sure it makes sense / that I agree on pulling Knowledge/Guidelines fully into the AI plugin. I'm fine with an AI experiment relying on Gutenberg being installed (and a Gutenberg experiment being enabled) as this is similar to trying to have folks help test the new media editor (via a forthcoming AI experiment on smart focal cropping). In my mind, this helps drive folks to trying out Gutenberg experiments (and perhaps trying out more than one) and as such don't know that its better to try and duplicate things here in the AI plugin.

[gziolo]

@jeffpaul My reading of the merge proposal feedback was that moving testing into the AI plugin was the expected next step, to demonstrate deeper integration with AI features and gather broader feedback. That was the motivation behind this PR.

Given your feedback and the limited interest in pursuing this direction, I’m inclined to close this PR and continue iterating on the experiment in Gutenberg.