Knowledge: Rename the Guidelines CPT storage primitive to Knowledge

[gziolo]

What?

This PR is an illustration for the consolidation proposal in #77230 (comment) — it implements the proposed rename of the Guidelines CPT to a Knowledge storage primitive, plus the type consolidation, so the expected end state can be reviewed as working code rather than prose. The direction is still gathering feedback on the issue; this branch exists to make that conversation concrete.

Renames, per the proposal:

• CPT slug: wp_guideline → wp_knowledge
• Taxonomy: wp_guideline_type → wp_knowledge_type
• Types registry + filter: wp_guideline_types → wp_knowledge_types
• Capability namespace: *_guidelines → *_knowledge
• Generic REST route: /wp/v2/guidelines → /wp/v2/knowledge (following the attachment → /wp/v2/media precedent)
• Built-in types: content → guideline (the type the site-wide guidelines singleton carries), artifact → note (private freeform working text; the save-time fallback term), memory stays.

The storage primitive tracks the WordPress core counterpart opened at WordPress/wordpress-develop#12201, and has been refreshed to match the refinements made there: the built-in type settled on guideline (not instruction), the capability filter is the public wp_maybe_grant_knowledge_caps() hooked at priority 1 (matching the wp_maybe_grant_* family), wp_knowledge disables autosave (headless storage with no editor session; revisions retained), and the wp_knowledge_type taxonomy is headless (show_ui => false).

Why?

"Knowledge" is the namespace for the storage primitive, API, capabilities, and type registry, while individual rows are referred to by their concrete type (a guideline, a memory, a note). The reasoning, prior feedback, and the full type model are in the proposal comment.

Renaming now is cheap: the feature is an experiment with no backward-compatibility guarantee, and the same rename would be much harder after a core merge.

How?

• lib/experimental/guidelines/ → lib/experimental/knowledge/, with the primitive classes renamed (Gutenberg_Knowledge_Post_Type, Gutenberg_Knowledge_REST_Controller).
• Capabilities: registered as capability_type => array( 'knowledge_item', 'knowledge' ). "Knowledge" is a mass noun, so the singular base must differ from the plural: with both set to knowledge, the generated per-post meta caps (edit_knowledge_item) would collide with the primitives (edit_knowledge), making current_user_can( 'edit_knowledge' ) ambiguous. The *_knowledge_item forms are never granted and never typed in checks — map_meta_cap() resolves them — so the visible capability surface is *_knowledge throughout. A dedicated test (test_post_type_meta_caps_do_not_collide_with_primitives) locks this in.
• Intentionally unchanged: the Settings → Guidelines page and its client app (routes/guidelines/, zero JS changes), the /wp/v2/content-guidelines singleton route (it now resolves the site-wide post by the guideline term instead of content), all user-facing Guidelines labels, the gutenberg-guidelines experiment id (persisted in site options), and the _guideline_* post meta keys (storage shape is orthogonal to the proposal).
• Data migration: a one-time migration in lib/upgrade.php moves existing wp_guideline rows and wp_guideline_type terms to the new identifiers and re-slugs the built-in type terms (content → guideline, artifact → note), preserving user-customized term labels. It runs even when the experiment is currently disabled, so integrations already building on the CPT are not orphaned.

Out of scope, as follow-ups per the proposal: the skill type, the knowledge-management ability (Abilities API), pinning the singleton by ID instead of by term, and any evolution of the singleton storage shape.

Testing Instructions

1. Enable the Guidelines experiment under Gutenberg → Experiments.
2. Visit Settings → Guidelines, save some guidelines, and confirm the page works unchanged (round-trips through /wp/v2/content-guidelines).
3. As an admin, GET /wp/v2/knowledge returns the collection (including the singleton row, typed guideline); POST /wp/v2/knowledge without a type creates a private row with the note fallback term.
4. On a site with pre-rename data: after updating, confirm wp_guideline rows reappear as wp_knowledge with re-slugged type terms (run _gutenberg_migrate_guidelines_to_knowledge() fires once via the version bump in lib/upgrade.php).
5. npm run test:unit:php:base -- --group knowledge,guidelines — 161 tests covering the full feature.

🤖 Generated with Claude Code

[github-actions]

Size Change: 0 B

Total Size: 8.6 MB

_{compressed-size-action}

[github-actions]

Flaky tests detected in 9a4a5c7.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27753842623
📝 Reported issues:

• [Flaky Test] Should save the changes #78689 in /test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js

[gziolo]

After opening PR against WordPress core trunk, this PR needs to get refreshed to adjust based on my findings there:

• Knowledge: Introduce the wp_knowledge custom post type wordpress-develop#12201

I'll keep this PR in the draft stage also because we need to sort out the story of how we end up storing the content that users save on the Guidelines settings page, which is being explored in:

• Knowledge: Dissolve the Guidelines singleton into per-scope rows #79263

Both Gutenberg PRs must land in the same Gutenberg plugin release. As part of that, we will most likely also promote Guidelines to a regular feature that is no longer behind and an experiment.

[gziolo]

Pushed a follow-up commit (1f20bdf) that syncs the review fixes made to the WordPress core counterpart (WordPress/wordpress-develop#12201) after the initial primitive sync, so the two stay aligned:

• Capability bases — capability_type is now array( 'knowledge_item', 'knowledge_items' ), so the primitives use the standard plural form (edit_knowledge_items) while the per-post meta caps keep the singular form (edit_knowledge_item) — the same primitive/meta split WordPress uses for edit_posts vs edit_post. The synthesized primitives, the read remap, and the wp_knowledge_type term capabilities were renamed to match.
• Trashed-row ownership — wp_maybe_grant_knowledge_caps() resolves the pre-trash status from _wp_trash_meta_status before the per-post grant, so an author can still delete/restore their own row after trashing it (with a regression test).
• Naming & signature — dropped the underscore prefix from the private wp_knowledge_ensure_default_type_term() / wp_knowledge_maybe_map_term_label() functions and removed the type hints from wp_maybe_grant_knowledge_caps() to match the sibling user_has_cap callbacks.
• Error code — the collection read returns rest_cannot_read instead of rest_forbidden, matching the font-families/global-styles/comments controllers in core.
• Taxonomy — dropped the no-op show_admin_column from wp_knowledge_type (the post type is show_ui => false, so it rendered nothing).
• Tests — assert the revisions routes are registered while the autosaves routes are not.

phpcbf/phpcs are clean. The contributor create/update/delete REST coverage that core added in the same round was already present here, so no duplicate tests were introduced.

One intentional scope note: the Gutenberg-only Content Guidelines singleton controller still returns rest_forbidden for its read check. That controller is the consumer-side piece the core PR explicitly leaves out of scope, so I kept it as-is — happy to align it to rest_cannot_read too if we'd prefer consistency.

[gziolo]

We could also decide not to pursue this step, as the feature is still in the experimental phase.