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 <jorgefilipecosta@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: peterwilsoncc <peterwilsoncc@git.wordpress.org>
Co-authored-by: galatanovidiu <ovidiu-galatan@git.wordpress.org>
Co-authored-by: justlevine <justlevine@git.wordpress.org>
Co-authored-by: jasonbahl <jasonbahl@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.

[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 AI@1.1.0

< 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 94.76268% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.07%. Comparing base (9db55ee) to head (a4468b7).
⚠️ Report is 11 commits behind head on develop.

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

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #739      +/-   ##
=============================================
+ Coverage      75.50%   77.07%   +1.57%     
- Complexity      2086     2281     +195     
=============================================
  Files             99      100       +1     
  Lines           8626     9240     +614     
=============================================
+ Hits            6513     7122     +609     
- Misses          2113     2118       +5     

Flag	Coverage Δ
unit	77.07% <94.76%> (+1.57%)	⬆️

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.

[jeffpaul]

@jorgefilipecosta please re-request reviews when you're updates are ready here, thanks!

[jorgefilipecosta]

@jorgefilipecosta please re-request reviews when you're updates are ready here, thanks!

Done it is ready for another pass, everything was addressed.

[jorgefilipecosta]

After discussing with @gziolo I added some documentation specifying the contract a post type to be usable in abilities needs to be registered before abilities are registered (otherwise its schema may have already been passed/stored by some ability consumer/adapter).