Extend information about HTTP methods used when executing ability with REST API

Author: gziolo

docs/5.rest-api.md

@@ -143,25 +143,42 @@ curl https://example.com/wp-json/wp/v2/abilities/my-plugin/get-site-info
 
 ## Execute an Ability
 
+Abilities are executed via the `/run` endpoint. The required HTTP method depends on the ability's `readonly` annotation:
+
+- **Read-only abilities** (`readonly: true`) must use **GET**
+- **Regular abilities** (default) must use **POST**
+
+This distinction ensures read-only operations use safe HTTP methods that can be cached and don't modify server state.
+
 ### Definition
 
-`POST /wp/v2/abilities/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)/run`
+`GET|POST /wp/v2/abilities/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)/run`
 
 ### Arguments
 
 - `namespace` _(string)_: The namespace part of the ability name.
 - `ability` _(string)_: The ability name part.
 - `input` _(integer|number|boolean|string|array|object|null)_: Optional input data for the ability as defined by its input schema.
+  - For **GET requests**: pass as `input` query parameter (URL-encoded JSON)
+  - For **POST requests**: pass in JSON body
 
-### Example Request (No Input)
+### Example Request (Read-only, GET)
 
 ```bash
-curl -X POST https://example.com/wp-json/wp/v2/abilities/my-plugin/get-site-info/run
+# No input
+curl https://example.com/wp-json/wp/v2/abilities/my-plugin/get-site-info/run
+
+# With input (URL-encoded)
+curl "https://example.com/wp-json/wp/v2/abilities/my-plugin/get-user-info/run?input=%7B%22user_id%22%3A1%7D"
 ```
 
-### Example Request (With Input)
+### Example Request (Regular, POST)
 
 ```bash
+# No input
+curl -X POST https://example.com/wp-json/wp/v2/abilities/my-plugin/create-draft/run
+
+# With input
 curl -X POST \
   -H "Content-Type: application/json" \
   -d '{"input":{"option_name":"blogname","option_value":"New Site Name"}}' \
@@ -214,5 +231,5 @@ The API returns standard WordPress REST API error responses with these common co
 - `ability_invalid_output` - output validation failed according to the ability's schema.
 - `ability_invalid_execute_callback` - the ability's execute callback is not callable.
 - `rest_ability_not_found` - the requested ability is not registered.
-- `rest_ability_invalid_method` - the requested HTTP method is not allowed for executing the selected ability.
+- `rest_ability_invalid_method` - the requested HTTP method is not allowed for executing the selected ability (e.g., using POST on a read-only ability or GET on a regular ability).
 - `rest_ability_cannot_execute` - the ability cannot be executed due to insufficient permissions.