Docs: Expand information about new annotations property

Author: gziolo

docs/3.registering-abilities.md

@@ -28,6 +28,11 @@ The `$args` array accepts the following keys:
   - The callback should return a boolean (`true` if the user has permission, `false` otherwise), or a `WP_Error` object on failure.
   - 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.
+  - `annotations` (`array`, **Optional**): An associative array of annotations providing hints about the ability's behavior characteristics. Supports the following keys:
+    - `instructions` (`string`, **Optional**): Custom instructions or guidance for using the ability (default: `''`).
+    - `readonly` (`boolean`, **Optional**): Whether the ability only reads data without modifying its environment (default: `false`).
+    - `destructive` (`boolean`, **Optional**): Whether the ability may perform destructive updates to its environment. If `true`, the ability may perform any type of modification, including deletions or other destructive changes. If `false`, the ability performs only additive updates (default: `true`).
+    - `idempotent` (`boolean`, **Optional**): Whether calling the ability repeatedly with the same arguments will have no additional effect on its environment (default: `false`).
   - `show_in_rest` (`boolean`, **Optional**): Whether to expose this ability via the REST API. Default: `false`.
     - When `true`, the ability will be listed in REST API responses and can be executed via REST endpoints.
     - When `false`, the ability will be hidden from REST API listings and cannot be executed via REST endpoints, but remains available for internal PHP usage.
@@ -80,7 +85,13 @@ function my_plugin_register_site_info_ability() {
                 'url' => home_url()
             );
         },
-        'permission_callback' => '__return_true'
+        'permission_callback' => '__return_true',
+        'meta' => array(
+            'annotations' => array(
+                'readonly' => true,
+                'destructive' => false
+            ),
+        ),
     ));
 }
 ```
@@ -134,7 +145,13 @@ function my_plugin_register_update_option_ability() {
         },
         'permission_callback' => function() {
             return current_user_can( 'manage_options' );
-        }
+        },
+        'meta' => array(
+            'annotations' => array(
+                'destructive' => false,
+                'idempotent' => true
+            ),
+        ),
     ));
 }
 ```

docs/5.rest-api.md

@@ -42,7 +42,14 @@ Abilities are represented in JSON with the following structure:
       }
     }
   },
-  "meta": {}
+  "meta": {
+    "annotations": {
+      "instructions": "",
+      "readonly": true,
+      "destructive": false,
+      "idempotent": false
+    }
+  }
 }
 ```
 
@@ -85,7 +92,14 @@ curl https://example.com/wp-json/wp/v2/abilities
         }
       }
     },
-    "meta": {}
+    "meta": {
+      "annotations": {
+        "instructions": "",
+        "readonly": false,
+        "destructive": true,
+        "idempotent": false
+      }
+    }
   }
 ]
 ```
@@ -128,31 +142,55 @@ curl https://example.com/wp-json/wp/v2/abilities/my-plugin/get-site-info
       }
     }
   },
-  "meta": {}
+  "meta": {
+    "annotations": {
+      "instructions": "",
+      "readonly": true,
+      "destructive": false,
+      "idempotent": false
+    }
+  }
 }
 ```
 
 ## 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"}}' \
@@ -205,5 +243,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 GET on a read-only ability, or POST on a regular ability).
 - `rest_ability_cannot_execute` - the ability cannot be executed due to insufficient permissions.

tests/unit/abilities-api/wpAbility.php

@@ -199,23 +199,6 @@ public function test_show_in_rest_can_be_set_to_false() {
 		);
 	}
 
-	/**
-	 * Tests that `show_in_rest` can be set to false.
-	 */
-	public function test_show_in_rest_can_be_set_to_false() {
-		$args = array_merge(
-			self::$test_ability_properties,
-			array(
-				'meta' => array(
-					'show_in_rest' => false,
-				),
-			)
-		);
-		$ability = new WP_Ability( self::$test_ability_name, $args );
-
-		$this->assertFalse( $ability->get_meta_item( 'show_in_rest' ), '`show_in_rest` metadata should be false.' );
-	}
-
 	/**
 	 * Tests that invalid `show_in_rest` value throws an exception.
 	 */