Merge 4f8c7fd into 401aa5b

Author: gazconroy

specs/search/paths/rules/common/schemas.yml

@@ -102,11 +102,13 @@ consequence:
       type: boolean
       default: false
       description: |
-        Whether promoted records must match an active filter for the consequence to be applied.
+        Determines whether promoted records must also match active filters for the consequence to apply.
 
-        This ensures that user actions (filtering the search) are given a higher precendence.
-        For example, if you promote a record with the `color: red` attribute, and the user filters the search for `color: blue`,
+        This ensures user-applied filters take priority and irrelevant matches aren't shown.
+        For example, if you promote a record with `color: red` but the user filters for `color: blue`,
         the "red" record won't be shown.
+
+        > In the Algolia dashboard, when you use the **Pin an item** consequence, `filterPromotes` appears as the checkbox: **Pinned items must match active filters to be displayed.** For examples, see [Promote results with rules](https://www.algolia.com/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/promote-hits/#promote-results-matching-active-filters).
     hide:
       type: array
       maxItems: 50