Abilities API: Improve inline documentation

[gziolo]

This PR updates the Abilities API docblocks so they match how the code works. It changes documentation only. The code is not changed.

What changed

• Permissions. Explains how required_capabilities and permission_callback work together. List the capabilities needed for every execution in required_capabilities. Check anything that depends on the input in permission_callback. The examples now follow this rule.
• Examples. Removes required from the input and output schemas, because it has no effect there. Adds a note that a custom category must be registered before an ability can use it. The wp_get_abilities() sorting example now keeps the array keys.
• Schemas and callbacks. Explains when an input schema is required, when the default value is used, and what arguments the callbacks receive. Notes that exceptions thrown by callbacks are converted to WP_Error.
• Execution lifecycle. Adds a short list of the hooks that WP_Ability::execute() runs, in order.
• wp_get_abilities(). Clarifies which abilities reach the wp_get_abilities_item_include filter, how meta matching works, and what has_required_capabilities does and does not check.
• Naming. Ability names need exactly one slash. Category slugs cannot start or end with a dash.

Trac ticket: TBD

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: Checking the docblocks against the code and editing the wording. I reviewed all changes.

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

🤖 Generated with Claude Code

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.