Docs/semantic headings

docs/1.intro.md

@@ -1,12 +1,12 @@
 # 1. Introduction & Overview
 
-**What is the Abilities API?**
+## What is the Abilities API?
 
 The WordPress Abilities API provides a standardized way to register and discover distinct units of functionality within a WordPress site. These units, called "Abilities", represent specific actions or capabilities that components can perform, with clearly defined inputs, outputs, and permissions.
 
 It acts as a central registry, making it easier for different parts of WordPress, third-party plugins, themes, and external systems (like AI agents) to understand and interact with the capabilities available on a specific site.
 
-**Core Concepts**
+## Core Concepts
 
 - **Ability:** A distinct piece of functionality with a unique name following the `namespace/ability-name` pattern. Each ability has a human-readable name and description, input/output definitions (using JSON Schema), optional permissions, and an associated callback function for execution. Each registered Ability is an instance of the `WP_Ability` class.
 - **Registry:** A central, singleton object (`WP_Abilities_Registry`) that holds all registered abilities. It provides methods for registering, unregistering, finding, and querying abilities.
@@ -15,7 +15,7 @@ It acts as a central registry, making it easier for different parts of WordPress
 - **Permission Callback:** An optional function that determines if the current user can execute a specific ability. 
 - **Namespace:** The first part of an ability name (before the slash), typically matching the plugin or component name that registers the ability.
 
-**Goals and Benefits**
+## Goals and Benefits
 
 - **Standardization:** Provides a single, consistent way to expose site capabilities.
 - **Discoverability:** Makes functionality easily discoverable by AI systems and automation tools.
@@ -24,15 +24,15 @@ It acts as a central registry, making it easier for different parts of WordPress
 - **Extensibility:** Simple registration pattern allows any plugin or theme to expose their capabilities.
 - **AI-Friendly:** Machine-readable format enables intelligent automation and AI agent interactions.
 
-**Use Cases**
+## Use Cases
 
 - **AI Integration:** Allow AI agents to discover and interact with site capabilities.
 - **Plugin Interoperability:** Enable plugins to discover and use each other's functionality.
 - **Automation Tools:** Provide programmatic access to site features.
 - **API Documentation:** Self-documenting capabilities with schema validation.
 - **Developer Tools:** Standardized way to expose plugin functionality.
 
-**Registration Example**
+## Registration Example
 
 ```php
 add_action( 'abilities_api_init', 'my_plugin_register_ability');

docs/3.registering-abilities.md

@@ -1,8 +1,8 @@
-### 3. Registering Abilities (`wp_register_ability`)
+# 3. Registering Abilities (`wp_register_ability`)
 
 The primary way to add functionality to the Abilities API is by using the `wp_register_ability()` function, typically hooked into the `abilities_api_init` action.
 
-**Function Signature**
+## Function Signature
 
 ```php
 wp_register_ability( string $id, array $args ): ?\WP_Ability
@@ -12,7 +12,7 @@ wp_register_ability( string $id, array $args ): ?\WP_Ability
 - `$args` (`array`): An array of arguments defining the ability configuration.
 - **Return:** (`?\WP_Ability`) An instance of the registered ability if it was successfully registered, `null` on failure (e.g., invalid arguments, duplicate ID).
 
-**Parameters Explained**
+## Parameters Explained
 
 The `$args` array accepts the following keys:
 
@@ -29,17 +29,17 @@ The `$args` array accepts the following keys:
   - If the input does not validate against the input schema, the permission callback will not be called, and a `WP_Error` will be returned instead.
 - `meta` (`array`, **Optional**): An associative array for storing arbitrary additional metadata about the ability.
 
-**Ability ID Convention**
+## Ability ID Convention
 
 The `$id` parameter must follow the pattern `namespace/ability-name`:
 
 - **Format:** Must contain only lowercase alphanumeric characters (`a-z`, `0-9`), hyphens (`-`), and one forward slash (`/`) for namespacing.
 - **Convention:** Use your plugin slug as the namespace, like `my-plugin/ability-name`.
 - **Examples:** `my-plugin/update-settings`, `woocommerce/get-product`, `contact-form/send-message`, `analytics/track-event`
 
-**Code Examples**
+## Code Examples
 
-**1. Registering a Simple Data Retrieval Ability**
+### Registering a Simple Data Retrieval Ability
 
 ```php
 add_action( 'abilities_api_init', 'my_plugin_register_site_info_ability' );
@@ -82,7 +82,7 @@ function my_plugin_register_site_info_ability() {
 }
 ```
 
-**2. Registering an Ability with Input Parameters**
+### Registering an Ability with Input Parameters
 
 ```php
 add_action( 'abilities_api_init', 'my_plugin_register_update_option_ability' );
@@ -136,7 +136,7 @@ function my_plugin_register_update_option_ability() {
 }
 ```
 
-**3. Registering an Ability with Plugin Dependencies**
+### Registering an Ability with Plugin Dependencies
 
 ```php
 add_action( 'abilities_api_init', 'my_plugin_register_woo_stats_ability' );
@@ -194,7 +194,7 @@ function my_plugin_register_woo_stats_ability() {
 }
 ```
 
-**4. Registering an Ability That May Fail**
+### Registering an Ability That May Fail
 
 ```php
 add_action( 'abilities_api_init', 'my_plugin_register_send_email_ability' );

docs/4.using-abilities.md

@@ -1,8 +1,8 @@
-### 4. Using Abilities (`wp_get_ability`, `wp_get_abilities`)
+# 4. Using Abilities (`wp_get_ability`, `wp_get_abilities`)
 
 Once abilities are registered, they can be retrieved and executed using global functions from the Abilities API.
 
-**Getting a Specific Ability (`wp_get_ability`)**
+## Getting a Specific Ability (`wp_get_ability`)
 
 To get a single ability object by its name (namespace/ability-name):
 
@@ -33,7 +33,7 @@ if ( $site_info_ability ) {
 }
 ```
 
-**Getting All Registered Abilities (`wp_get_abilities`)**
+## Getting All Registered Abilities (`wp_get_abilities`)
 
 To get an array of all registered abilities:
 
@@ -56,7 +56,7 @@ foreach ( $all_abilities as $name => $ability ) {
 }
 ```
 
-**Executing an Ability (`$ability->execute()`)**
+## Executing an Ability (`$ability->execute()`)
 
 Once you have a `WP_Ability` object (usually from `wp_get_ability`), you execute it using the `execute()` method.
 
@@ -124,7 +124,7 @@ if ( $ability ) {
 }
 ```
 
-**Checking Permissions (`$ability->check_permission()`)**
+## Checking Permissions (`$ability->check_permission()`)
 
 Before executing an ability, you can check if the current user has permission. The `check_permission()` method returns either `true`, `false`, or a `WP_Error` object, so you must use `is_wp_error()` to handle errors properly:
 
@@ -166,7 +166,7 @@ if ( $ability ) {
 }
 ```
 
-**Inspecting Ability Properties**
+## Inspecting Ability Properties
 
 The `WP_Ability` class provides several getter methods to inspect ability properties:
 
@@ -193,7 +193,7 @@ if ( $ability ) {
 }
 ```
 
-**Error Handling Patterns**
+## Error Handling Patterns
 
 The Abilities API uses several error handling mechanisms: