Add Filtering Capabilities for Registered Abilities using collections (POC)

docs/4.using-abilities.md

@@ -35,27 +35,70 @@ if ( $site_info_ability ) {
 
 ## Getting All Registered Abilities (`wp_get_abilities`)
 
-To get an array of all registered abilities:
+`wp_get_abilities()` returns a `WP_Abilities_Collection` instance, which provides a fluent, chainable API for filtering and sorting:
 
 ```php
 /**
- * Retrieves all registered abilities using Abilities API.
+ * Retrieves a collection of registered abilities.
  *
- * @return WP_Ability[] The array of registered abilities.
+ * Returns a WP_Abilities_Collection instance that provides a fluent, chainable
+ * API for filtering, sorting, and manipulating abilities.
+ *
+ * @since n.e.x.t Returns WP_Abilities_Collection instead of array.
+ * @return WP_Abilities_Collection Collection of WP_Ability instances.
  */
-function wp_get_abilities(): array
+function wp_get_abilities(): WP_Abilities_Collection
 
 // Example: Get all registered abilities
-$all_abilities = wp_get_abilities();
+$abilities = wp_get_abilities();
 
-foreach ( $all_abilities as $name => $ability ) {
+// Iterate over the collection
+foreach ( $abilities as $ability ) {
     echo 'Ability Name: ' . esc_html( $ability->get_name() ) . "\n";
     echo 'Label: ' . esc_html( $ability->get_label() ) . "\n";
     echo 'Description: ' . esc_html( $ability->get_description() ) . "\n";
     echo "---\n";
 }
+
+// Or convert to array if needed
+$abilities_array = $abilities->to_array();
 ```
 
+### Filtering Abilities
+
+The collection returned by `wp_get_abilities()` provides chainable methods for filtering and sorting. For detailed filtering documentation, see [Advanced Filtering and Sorting](8.advanced-filtering-and-sorting.md).
+
+Quick examples:
+
+```php
+// Filter by category
+$abilities = wp_get_abilities()->where_category( 'data-retrieval' );
+
+// Search for abilities
+$abilities = wp_get_abilities()->search( 'email' );
+
+// Filter by namespace and meta
+$abilities = wp_get_abilities()
+    ->where_namespace( 'my-plugin' )
+    ->where( 'meta.show_in_rest', true );
+
+// Chain multiple filters
+$abilities = wp_get_abilities()
+    ->where_category( array( 'communication', 'data-retrieval' ) )
+    ->where_namespace( 'my-plugin' )
+    ->where( 'meta.show_in_rest', true )
+    ->search( 'email' )
+    ->sort_by( 'label' )
+    ->all(); // Convert to array
+
+// Get count without converting to array
+$count = wp_get_abilities()
+    ->where_category( 'math' )
+    ->count();
+```
+
+See [Advanced Filtering and Sorting](8.advanced-filtering-and-sorting.md) for complete filtering documentation, including nested meta filters, comparison operators, and custom callbacks.
+
 ## Executing an Ability (`$ability->execute()`)
 
 Once you have a `WP_Ability` object (usually from `wp_get_ability`), you execute it using the `execute()` method.