README references to archived abilities api project

[zoopster]

The README continues to reference the need for the abilities api however the abilities api was merged into core?

[mathetos]

README.md was mostly updated in #165 and #204. Remaining drift in readme.txt and the getting-started guides is covered in #223. Suggest closing when that PR merges, or now if maintainers prefer to track doc cleanup only on the PR.

After more review I submitted #223 to address this as well as some other stray items. But per @justlevine 's guidance I'm taking a more wholistic look.

[mathetos]

@justlevine I wanted to expand on what this issue implies, since the install/core-Abilities-API drift is only part of the picture.

My PR (#223) started with just the narrow slice (readme.txt and getting-started still read like you need a separate Abilities API install, Composer-first in places README already fixed in #165/#204).

After reviewing the docs in more detail, I see the broader gap that you're highlighting and how it's more of a strategic issue, not just inconsistent examples. The conversation we had on June 24 in Core AI reemphasized that new core/site abilities belong in the AI plugin (and the Abilities API in core), not on the MCP adapter as the primary registration target. A lot of our docs still teach the older model: register arbitrary abilities, set mcp.public, treat the default server as general-purpose AI integration. That lines up with friction in issues like #213 and #183, and with copy-paste examples that omit category or mcp.public and generate support noise (#135).

The architectural context I think we need to make explicit is that WordPress deliberately adopted an adapter pattern for MCP, not explicit flat tooling. On the default server, MCP clients see a thin surface (the meta-tools) and reach everything else through discover → inspect → execute. Abilities live in WordPress first; MCP is one consumer via the adapter, not the place where site capabilities should be defined or primarily documented. Custom servers are the supported path when an integrator wants explicit tooling with a fixed tool list upfront. That framing is why most abilities belong in core or the AI plugin, and only rarely need any direct MCP exposure at all.

When an ability does belong in MCP, I think docs should teach a narrow decision path (most registrations should stop before this): register in the Abilities layer with a clear owner and permissions first; only then ask whether an external MCP client must discover and invoke it. If yes, prefer a custom server when the integration is a small, stable, curated set; use mcp.public on the default server's discovery index only when a general-purpose agent should find it at runtime and the site owner intends that exposure. The adapter's own meta-abilities are the exception: they are MCP-protocol affordances, not site CRUD. Everything else should be rare and deliberate, not the hello-world path.

So I see what you mean, and my PR needs to be updated if it's going to close #150, but only once we align on the comprehensive doc fix for Abilities in core and the AI plugin.

Here is a quick proposal for what that might look like:

• Put the adapter pattern front and center in README.md. Explain adapter-vs-explicit-tooling before features or install steps, then spell out who registers what: core and the AI plugin for site abilities, this plugin for MCP protocol adaptation (meta-tools and transports), and custom servers when integrators want explicit tool lists. Include the short "when does an ability belong in MCP?" decision path above so mcp.public reads as rare publishing to the adapter, not as how you AI-enable a site.
• Document the two MCP modes in docs/guides/default-server.md and docs/architecture/overview.md (or a small docs/guides/adapter-pattern.md). The default server implements layered discovery; custom servers opt into explicit tooling. Tie that design choice to why abilities are not native MCP tools by default.
• Reframe docs/guides/creating-abilities.md around registration first, MCP second. Walk through Abilities API registration and ownership, then when (rarely) to publish to MCP via mcp.public or a custom server list, with anti-patterns called out explicitly.
• Retarget onboarding to MCP meta-tools first in getting-started docs (docs/getting-started/README.md, installation.md, basic-examples.md). Point readers to the AI plugin for site abilities instead of create-post-on-default-server as the primary path, and use registration examples with category and the correct hooks so copy-paste does not reproduce wp_register_ability returns NULL when called from plugin during wp_abilities_api_init #135-style failures.
• Tie registration troubleshooting to the ownership model in docs/troubleshooting/common-issues.md. Add a short section on common mistakes, such as a missing category, an ability that never shows up on the default server, or registering "for MCP" before the ability belongs anywhere in WordPress.
• Reinforce the direction for contributors and agents in AGENTS.md and docs/README.md. Add a doc map and audience order, link to a small docs/contributing/documentation.md or CONTRIBUTING subsection (Diataxis-style conventions, WP doc style guide), and keep those files focused on navigation and guardrails rather than the strategic story.

Happy to expand #223 along these lines once we have consensus on the direction above.

[galatanovidiu]

Thanks @mathetos, this is really useful.

The original issue here is narrow: the docs told people to install the standalone Abilities API, which is now in core (6.9+). That part is already fixed on trunk by #165 and #204, and #223 cleans up the last stale lines in readme.txt and the getting-started guides. So I'd say #150 is resolved once #223 merges.

Your bigger proposal (adapter pattern front and center, abilities-in-core first, mcp.public as the rare case) is a different, larger piece of work. I don't want it to get buried under a doc bug from March. Can you open a separate issue for it? Your 6-bullet outline above is a great starting point. That way it gets its own scope and we can track it properly.

@justlevine does that split make sense to you?