Add core/read-content ability

[jorgefilipecosta]

Summary

Part of: #40

Adds the read-only core/read-content ability to the plugin, mirroring the companion WordPress Core implementation so the two stay in sync. It overrides any core-provided copy.

The ability has explicit modes:

• single post by id, with optional post_type guard, returns the post directly
• single post by post_type and slug returns the post directly
• query mode returns { posts, total, total_pages } and supports status, author, parent, include, fields, page, and per_page

Defaults are lean: id, post_type, status, date, slug, and title_rendered. Heavier fields are opt-in via fields; raw fields require edit access, while rendered fields can be requested for readable posts.

Companion Core PR: WordPress/wordpress-develop#12195

Security

Uses a coarse capability gate plus per-post read/edit checks. Missing, unreadable, mismatched, and unexposed posts return the same not-found response.

Tests

PHPUnit integration tests cover permissions, fields, single-post modes, query mode, and include. The E2E spec tests/e2e/specs/abilities/core-read-content.spec.js exercises the client-side ability modes and include.

Manual testing

Paste this in the browser console on an editor/admin page after enabling AI. It creates two published posts and one draft, then exercises query mode, draft query mode, query include, single-post by id, and single-post by post_type + slug. Each ability call logs { input, output }.

const { ready } = await import( '@wordpress/core-abilities' );
if ( ready ) {
	await ready;
}

const { executeAbility } = await import( '@wordpress/abilities' );
const apiFetch =
	window.wp?.apiFetch || ( await import( '@wordpress/api-fetch' ) ).default;

const run = async ( input ) => {
	try {
		const output = await executeAbility( 'core/read-content', input );
		console.log( { input, output } );
		return output;
	} catch ( error ) {
		const output = {
			error: {
				code: error?.code,
				message: error?.message,
			},
		};
		console.log( { input, output } );
		return output;
	}
};

const suffix = Date.now();
const seededPosts = await Promise.all(
	[ 'one', 'two' ].map( ( label ) =>
		apiFetch( {
			path: '/wp/v2/posts',
			method: 'POST',
			data: {
				title: `core/read-content manual test ${ label }`,
				slug: `core-read-content-manual-${ suffix }-${ label }`,
				status: 'publish',
				content: `<!-- wp:paragraph --><p>Manual test ${ label } content.</p><!-- /wp:paragraph -->`,
			},
		} )
	)
);

const draftPost = await apiFetch( {
	path: '/wp/v2/posts',
	method: 'POST',
	data: {
		title: 'core/read-content manual test draft',
		slug: `core-read-content-manual-${ suffix }-draft`,
		status: 'draft',
		content: '<!-- wp:paragraph --><p>Manual test draft content.</p><!-- /wp:paragraph -->',
	},
} );

console.log( {
	input: { seed_posts: true },
	output: { published: seededPosts, draft: draftPost },
} );

// Query mode: readable posts with the default lean fields.
await run( { post_type: 'post' } );

// Query mode with include: specific posts, rendered content, and raw content.
await run( {
	post_type: 'post',
	include: seededPosts.map( ( post ) => post.id ),
	fields: [
		'id',
		'post_type',
		'status',
		'date',
		'slug',
		'title_rendered',
		'content_rendered',
		'content_raw',
	],
} );

// Query mode with drafts: requires a user that can edit/read drafts.
await run( {
	post_type: 'post',
	status: [ 'draft' ],
	include: [ draftPost.id ],
	fields: [
		'id',
		'post_type',
		'status',
		'date',
		'slug',
		'title_rendered',
		'content_rendered',
		'content_raw',
	],
} );

// Single-post mode: lookup by ID, with an optional post_type guard.
await run( {
	id: seededPosts[ 0 ].id,
	post_type: 'post',
	fields: [
		'id',
		'post_type',
		'slug',
		'title_rendered',
		'content_rendered',
		'content_raw',
	],
} );

// Single-post mode: lookup by post_type + slug.
await run( {
	post_type: 'post',
	slug: seededPosts[ 1 ].slug,
	fields: [
		'id',
		'post_type',
		'slug',
		'title_rendered',
		'content_rendered',
		'content_raw',
	],
} );

[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

[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: jorgefilipecosta <[email protected]>
Co-authored-by: gziolo <[email protected]>
Co-authored-by: peterwilsoncc <[email protected]>
Co-authored-by: galatanovidiu <[email protected]>
Co-authored-by: justlevine <[email protected]>
Co-authored-by: jasonbahl <[email protected]>
Co-authored-by: jeffpaul <[email protected]>

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

[gziolo]

Nice work so far! A few things to iron out:

• It looks like some files from the core/settings work (Add a core/settings ability #691) slipped into this branch: Settings.php, SettingsTest.php, the core-settings.spec.js e2e, and the e2e-sample-settings plugin. Since this PR is meant to stand on its own, those should come out (worth double-checking the .gitignore additions too).
• Input schema needs more thought. The options are really mutually exclusive, but the schema doesn't say so. If you pass id, none of the other params (status, author, parent, page, per_page) fit at all — they're just silently ignored. Same story with slug. The one combination that does make sense is slug together with post_type. So this should be modeled as distinct modes rather than a single flat object where anything goes.
• I see there is ai/get-post-details in the repo doing basically a subset of this. This work should supersede it, so let's plan to drop the old one rather than ship two overlapping "read a post" abilities.

[gziolo]

For reference, I'm sharing WP CLI commands related to read-only operations on posts:

• wp post get – post can be found only by post ID, all fields are returned by default, it's possible to filter fields with --fields or --field
  • wp post url-to-id – utility to convert URL to post ID
• wp post list – fields returned by default (ID, post_title, post_name, post_date, post_status), it's possible to filter fields with --fields or --field, --<field>=<value> allows to pass filter results with one or more args supported by WP_Query.

[jeffpaul]

@jorgefilipecosta looks like some code review feedback and merge conflicts to clean up to help move this along towards merge and inclusion in the next AI plugin release (to help get some usage testing & feedback before a parallel PR is landed for core in 7.1)

[justlevine]

(to help get some usage testing & feedback before a parallel PR is landed for core in 7.1)

This is an unrealistic and IMO unwanted end-goal. I think we need to accept that no new core abilities will ship in 7.1, even if they make it into [email protected]

< 3 weeks is not enough time to get actual API design feedback for core. It's not even a full AI Plugin release cycle.

By all means if we can get this cleaned up in time for the next plugin release, great, but considering that they're not even behind an Experiment toggle, I wouldn't want y'all rushing it in before you or @dkotter think its viable because of a desire to squeeze it into beta1.

cc @gziolo @jmarx

[codecov]

Codecov Report

❌ Patch coverage is 95.26316% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.80%. Comparing base (9db55ee) to head (b0827ef).

Files with missing lines	Patch %	Lines
includes/Abilities/Content/Content.php	95.10%	27 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #739      +/-   ##
=============================================
+ Coverage      75.50%   76.80%   +1.30%     
- Complexity      2086     2261     +175     
=============================================
  Files             99      100       +1     
  Lines           8626     9196     +570     
=============================================
+ Hits            6513     7063     +550     
- Misses          2113     2133      +20     

Flag	Coverage Δ
unit	76.80% <95.26%> (+1.30%)	⬆️

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.

[jorgefilipecosta]

Hi @gziolo, your feedback was applied.
Regarding "I see there is ai/get-post-details in the repo doing basically a subset of this. This work should supersede it, so let's plan to drop the old one rather than ship two overlapping "read a post" abilities." I plan to do that as a follow up in order to keep the scope of this PR smaller.

[peterwilsoncc]

I've added a few notes inline.

To avoid burying the lead: I think the key question I have is why you don't include the rendered content so bots can be set up with a read-only account?

[gziolo]

After a closer inspection, I want to echo the point that @peterwilsoncc raised regarding the data formatting. We need to decide whether we return raw data or rendered/filtered data. This is what I see now:

• Dates are in GMT format.
• Title is currently filtered.
• Content is in raw format.

What is needed will largely depend on the consumer. If they only want to present the data, then the preferred option would be using dates in the site's timezone, title, and content as rendered HTML. If they want to edit content, then maybe fetching raw data would make more sense. There are two ways to go about it:

• Make room for both values as suggested in review.
• Add a high-level flag that controls whether fields contain raw or post-processed fields.

@justlevine, thank you for the reminder about the timeline for the WP 7.1 release. Let's see how much work is left to iron out all the feedback raised so far. Either way, we want to get some early testing through the AI plugin. All the feedback is appreciated and will help shape this essential ability.

[galatanovidiu]

If we return both content_raw and content_rendered, this will fill up the context window with duplicated content.
Suggestion: have a scope input field(similar to REST API)

• edit will return the raw content that an agent can modify and update on a new request
• read it will return the "content_rendered". Probably best if we can strip html tags also (or transformed to MD :D [nice to have]) (I have no strong opinion on this one but with stripped tags we will be nice with the context window)

[peterwilsoncc]

• read it will return the "content_rendered". Probably best if we can strip html tags also (or transformed to MD :D [nice to have]) (I have no strong opinion on this one but with stripped tags we will be nice with the context window)

Warning

Opinionated 😸

I'd be reluctant to add the required code to core given it would add quite a bit of work to each request.

Dries Buytaert wrote up his experience of providing a markdown version of his content for LLMs and finding that the agents simply crawled both versions, so I think it's pretty safe to assume that they're happy with HTML.

[justlevine]

IMO that article has little to do with Markdown vs HTML and is rather about sources of truth/context rot (LLMs.txt is ineffective) and misunderstandings about how agentic discovery works (nothings going to visit your MD endpoints if you don't explicitly encourage it to).

That aside , there are other implications with exposing raw vs rendered content, including security and end-user case. As abilities are meant to be a primitive and not a MCP-specific transport, I think the way to address that in MCP (or upstream in Abilities) is an arg to filter the output.

If in the short term this is a concern, then I'd say keep content_rendered without content_raw, since even if LLMs do prefer markdown to HTML, they'd want the markdown version of the rendered html, not the one fill with custom block markup or unprocessed synced patterns etc. But longer term, IMO the solution belongs in a different layer.

[justlevine]

That aside , there are other implications with exposing raw vs rendered content,

@jasonbahl any chance you have a few minutes to share your thoughts from on over in WPGraphQL-land? With how much influence we took in design language, it would make sense for the output ergonomics to wind up being similar, just maybe a bit flatter. Same considerations, at least 🤔

[gziolo]

In my earlier #739 (comment), I referenced WP CLI as a good example of where good defaults solve the issue you discuss. It could be replicated here by returning the same set: ID, post_title, post_name, post_date, and post_status. All other fields remain accessible, but the consumer needs to explicitly list them in the input using the fields array.

[jasonbahl]

👋 @justlevine I left some notes here addressing the raw/rendered concerns along with some broader concerns: #739 (review)

[galatanovidiu]

I think the whole discussion missed my point. It's not about HTML vs Markdown, that was just a side note.

The real point: we need both content_raw and content_rendered, but never both at once.

• editing → agent needs content_raw (block markup, shortcodes) so it can change it and write it back. Rendered HTML is useless here.
• reading → agent needs content_rendered (what a human sees). Raw markup is just noise.

Any single call is one job or the other. So the field it doesn't need is always 100% redundant, the full post body duplicated on every call.

So I'd go with one content field that returns one or the other based on context: raw when editing is needed, rendered when it's read-only. If we want a default, probably raw only.

@jasonbahl this is basically what ?context=edit (REST) and format: RAW (WPGraphQL) already do, force the caller to declare intent. Same idea, just collapsed into a single field instead of two you opt into separately.

One more thing: if we go this way, the ability description needs updating too, so the agent knows when to pick each one (raw when it intends to edit, rendered when it just needs to read).

[justlevine]

The real point: we need both content_raw and content_rendered, but never both at once.

This is not true. Putting aside yet again that abilities aren't meant to serve agents they're meant to be a underlying primitive to serve all last-mile APIs, an agent

• doing migrations,
• building patterns that match existing site designs,
• or frontend generative ui work,

are all cases that would benefit from having both the preprocessed _raw and the full-fat _rendered data beyond the well-established non-AI ones like page builders and headless previews.

But also, worse than that, this would pollute the API with state: you need to know the context in order to be able to accomodate for the data. I've got PostObject.content but no idea whether or not it needs parsing or rendering or data sanitization anymore.

[jorgefilipecosta]

Yah I agree with @justlevine point I can think some cases where having rendered and non rendered content may be useful for an agent. Currently we don't return content by default, but we can request rendered or raw, or both, same for any other field.

[jorgefilipecosta]

Thank you all for the discussions and insights. It feels like the remaining discussion point is when to return rendered, raw, or both.

By default the fields we return are very lean: id, post_type, status, date, slug, title_rendered (if title is supported).
Then we have the following optional fields that are returned when requested (can always be requested): date_gmt, modified, modified_gmt, and link.
And the following fields that may be requested but may or may not be returned, depending on what the post type supports and what permissions the user has: excerpt_rendered, excerpt_protected, excerpt_raw, content_rendered, content_protected, content_raw, author, parent, title_raw.

This allows us to keep responses lean while still giving agents access to either rendered versions (e.g., a summarization agent), raw versions (e.g., an edit agent), or both (e.g., some migration or SEO/GEO analysis agent).

It is very flexible and agents can decide exactly what they need, but it also makes the code more complex, and forces agent workflows to "think" about the fields needed instead of just asking for edit fields or display fields.

I'm not opposed to the introduction of a format like @gziolo said at #739 (comment), format being display, raw and I guess full when the agent wants both?. Format would essentially pre-select a group of fields.
What happens when format is display but in the fields we include content_raw? I guess format takes precedence and fields can only select fields from that group (correct me if I'm wrong).
Another question I have is if format changes the return eg: if I set raw format do I automatically include the content_raw? In that case for consistency should not display format also include content_rendered?
Would format with 4 possible values address this: "default" - the lean format, "display" fields useful for display content_rendered etc, "raw": raw fields, "full": all fields possible. Fields would be available on display, edit or both, and fields array would extent or reduce the default set from the format. But If I am on display I can not request edit fields even if fields array passes it.

Another option could also be to make fields support the current array structure but also allow fields to be a string (display, raw, full); when it is a string, it essentially maps to a fixed array, e.g., display is equal to id, post_type, status, date, slug, title_rendered. And would avoid the format concept.

I guess we have three options we need to decide on:

• the current, a lean return and anything above it is requested using explicit fields array (be it renderd, raw, or both).
• A format flag that controls the set of available fields (display, raw, full), plus fields array to control what fields appear format takes precedence.
• Make fields an array or a string the string being an alias for a set of fields.

[galatanovidiu]

Did another pass on the read/query paths. Direction is good and the mode split reads well now. A cluster of things need work before this is solid, most of them in format_post() / execute_get_content() and the date helpers. Leaving the detail inline, short version here:

• Query total can disagree with posts. A fields subset that empties every row gets those rows dropped from posts, but total is read before the drop, so you can get total: 16 with posts: [].
• date_gmt / modified_gmt are wrong on any non-UTC site. Both the normal path and the draft fallback mislabel the offset or the instant. Detail inline on format_gmt_date().
• excerpt_rendered hides the real excerpt from editors on password-protected posts, even though content_rendered correctly shows them the content. Inconsistent, and it contradicts the field's own schema description.
• A post whose slug is literally "0" can't be fetched by slug — ! empty() trap, it falls through to query mode.
• content_not_found is dead code on every transport, because check_permission() already resolves the object and denies first. Worth a decision: keep the defense-in-depth and drop the unreachable 404, or move per-object checks into execute() so agents get a real 404 vs 403.
• total / total_pages descriptions claim X-WP-Total headers that I don't see on /run. Question inline, might be the pagination meta not being honored.

A few non-blocking nits also inline (openWorldHint, nullable GMT types, sibling ai/get-post-details overlap, a missing test).