docs(workflow): add examples to actions that lacked them

src/content/docs/workflow.mdx

@@ -1,30 +1,84 @@
 ---
 title: Workflow Automation
-description: An overview of Mergify Workflow Automation and its capabilities to automate your pull request process.
+description: Automate the routine work on your pull requests with rules that react to a pull request's state to label, comment, assign, rebase, merge, and more.
+hubAccent: true
 ---
 
-Mergify Workflow Automation is a rule-based system that automates pull request
-tasks using `pull_request_rules` in your Mergify configuration file.
+import Docset from '~/components/DocsetGrid/Docset.astro';
+import DocsetGrid from '~/components/DocsetGrid/DocsetGrid.astro';
 
-## How It Works
+Workflow Automation handles the routine work on your pull requests. You write
+rules in your Mergify configuration file, and Mergify carries them out: labeling,
+commenting, assigning, rebasing, merging, and more. Your team spends less time on
+pull request housekeeping.
 
-Mergify evaluates the state of a pull request rather than individual events.
-This means it checks the current status of a pull request and acts based on
-defined conditions. This behavior is known as "edge triggering."
+## Anatomy of a Rule
 
-An action will only be re-triggered for a pull request if the state flips back
-from being unmatched to matched.
+Every rule lives under `pull_request_rules` and pairs a set of **conditions**
+with the **actions** to run when a pull request matches them:
+
+```yaml
+pull_request_rules:
+  - name: add "WIP" label when the title contains "WIP"
+    conditions:
+      - title ~= WIP
+    actions:
+      label:
+        toggle:
+          - WIP
+```
+
+Here, any pull request whose title contains `WIP` gets the `WIP` label. Once the
+title no longer matches, Mergify removes it.
+
+## How Rules Are Evaluated
+
+Mergify evaluates the *state* of a pull request rather than individual events. It
+checks the current status of a pull request and acts based on the conditions you
+defined. This behavior is known as "edge triggering": an action only re-runs for
+a pull request when its state flips back from unmatched to matched.
 
 :::note
   Mergify never evaluates rules for pull request drafts it creates while
   processing the [merge queue](/merge-queue).
 :::
 
-## Reference
+## Building Blocks
 
-- [Rule Syntax](/workflow/rule-syntax) for the `pull_request_rules` format
+<DocsetGrid>
+  <Docset title="Rule Syntax" path="/workflow/rule-syntax" icon="lucide:badge-question-mark">
+    The `pull_request_rules` format and how to structure a rule.
+  </Docset>
+  <Docset title="Conditions" path="/configuration/conditions" icon="lucide:list-checks">
+    Match pull requests on title, labels, CI status, files, authorship, and more.
+  </Docset>
+  <Docset title="Actions" path="/workflow/actions" icon="lucide:rocket">
+    The full catalog of tasks Mergify can run when a rule matches.
+  </Docset>
+  <Docset title="Configuration File" path="/configuration/file-format" icon="lucide:braces">
+    Where rules live and how the overall config file is structured.
+  </Docset>
+</DocsetGrid>
 
-- [Actions](/workflow/actions) for the full list of available actions
+## Popular Actions
 
-- [Configuration File](/configuration/file-format) for the overall config
-  structure
+<DocsetGrid>
+  <Docset title="Merge" path="/workflow/actions/merge" icon="octicon:git-merge-16">
+    Automate the merging of your pull requests.
+  </Docset>
+  <Docset title="Queue" path="/workflow/actions/queue" icon="mergify:merge-queue">
+    Add the pull request to the merge queue.
+  </Docset>
+  <Docset title="Label" path="/workflow/actions/label" icon="lucide:badge-check">
+    Add, remove, or toggle labels on a pull request.
+  </Docset>
+  <Docset title="Comment" path="/workflow/actions/comment" icon="lucide:message-square">
+    Post a comment on a pull request.
+  </Docset>
+  <Docset title="Backport" path="/workflow/actions/backport" icon="lucide:git-branch">
+    Copy a pull request to another branch once it is merged.
+  </Docset>
+  <Docset title="Rebase" path="/workflow/actions/rebase" icon="lucide:git-branch">
+    Rebase the pull request on top of its base branch.
+  </Docset>
+</DocsetGrid>

src/content/docs/workflow/actions.mdx

@@ -28,25 +28,25 @@ management.
     Close a pull request.
   </Docset>
   <Docset title="Copy" path="copy" icon="lucide:share-2">
-    Copy a pull request.
+    Copy a pull request to another branch.
   </Docset>
   <Docset title="Comment" path="comment" icon="lucide:message-square">
-    Comment a pull request.
+    Post a comment on a pull request.
   </Docset>
   <Docset title="Delete Head Branch (Deprecated)" path="delete_head_branch" icon="lucide:scissors">
     Deprecated — use GitHub's built-in "Automatically delete head branches" setting instead.
   </Docset>
   <Docset title="Dismiss Reviews" path="dismiss_reviews" icon="lucide:message-square-x">
     Dismiss previous reviews on a pull request.
   </Docset>
-  <Docset title="Edit" path="edit" icon="lucide:type">
-    Edit pull request body, title or draft state.
+  <Docset title="Edit" path="edit" icon="octicon:git-pull-request-draft-16">
+    Convert a pull request to or from a draft.
   </Docset>
   <Docset title="GitHub Actions" path="github_actions" icon="simple-icons:githubactions">
     Dispatch an existing GitHub workflow in the repository.
   </Docset>
   <Docset title="Label" path="label" icon="lucide:badge-check">
-    Add, remove or toggle label on a pull request.
+    Add, remove, or toggle labels on a pull request.
   </Docset>
   <Docset title="Merge" path="merge" icon="octicon:git-merge-16">
     Automate the merging of your pull requests.

src/content/docs/workflow/actions/comment.mdx

@@ -1,6 +1,6 @@
 ---
 title: Comment
-description: Comment a pull request.
+description: Post a comment on a pull request.
 ---
 
 import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable';
@@ -15,7 +15,7 @@ your contributors.
 
 ## Parameters
 
-<ActionOptionsTable def='CommentActionModel'/>
+<ActionOptionsTable def="CommentActionModel" />
 
 ## Examples
 

src/content/docs/workflow/actions/dismiss_reviews.mdx

@@ -13,3 +13,21 @@ reviews in your pull request workflow.
 ## Parameters
 
 <ActionOptionsTable def="DismissReviewsActionModel" />
+
+## Examples
+
+### Dismiss Approvals When New Commits Are Pushed
+
+Keep approvals fresh by removing them whenever new commits are pushed, while
+leaving change requests in place.
+
+```yaml
+pull_request_rules:
+  - name: dismiss stale approvals
+    conditions:
+      - base = main
+    actions:
+      dismiss_reviews:
+        approved: true
+        changes_requested: false
+```

src/content/docs/workflow/actions/edit.mdx

@@ -1,13 +1,13 @@
 ---
 title: Edit
-description: Edit pull request attributes.
+description: Convert a pull request to or from a draft.
 ---
 
 import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable';
 
-The `edit` action allows Mergify to edit the body of a pull request. This can
-be helpful in situations where you want to automatically edit attributes
-of the pull request.
+The `edit` action lets Mergify change a pull request's draft state. This is
+helpful when you want to automatically convert a pull request to or from a draft
+based on its conditions.
 
 ## Parameters
 

src/content/docs/workflow/actions/label.mdx

@@ -1,6 +1,6 @@
 ---
 title: Label
-description: Add, remove and toggle labels on a pull request.
+description: Add, remove, or toggle labels on a pull request.
 ---
 
 import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable';

src/content/docs/workflow/actions/queue.mdx

@@ -1,6 +1,6 @@
 ---
 title: Queue
-description: Put your pull request into the merge queue.
+description: Add the pull request to the merge queue.
 ---
 
 import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable';

src/content/docs/workflow/actions/rebase.mdx

@@ -11,7 +11,7 @@ up-to-date with the latest changes from the base branch.
 
 :::note
   You do not need to use this action if you use the [merge
-  queue](/merge-queue). The merge queue automatically update the pull requests
+  queue](/merge-queue). The merge queue automatically updates the pull requests
   it processes as necessary, making sure they are tested with up-to-date code
   before being merged.
 :::
@@ -25,4 +25,21 @@ up-to-date with the latest changes from the base branch.
 
 ## Parameters
 
-<ActionOptionsTable def='RebaseActionModel'/>
+<ActionOptionsTable def="RebaseActionModel" />
+
+## Examples
+
+### Autosquash Fixup Commits
+
+Rebase a pull request and fold in any `fixup!`, `squash!`, or `amend!` commits
+once it is ready to merge.
+
+```yaml
+pull_request_rules:
+  - name: autosquash fixup commits
+    conditions:
+      - label = ready-to-merge
+    actions:
+      rebase:
+        autosquash: true
+```

src/content/docs/workflow/actions/request_reviews.mdx

@@ -16,3 +16,21 @@ certain pull requests.
 ## Parameters
 
 <ActionOptionsTable def="RequestReviewsActionModel" />
+
+## Examples
+
+### Request a Review for Sensitive Files
+
+Ask the security team to review whenever a pull request changes files under
+`security/`.
+
+```yaml
+pull_request_rules:
+  - name: request a security review
+    conditions:
+      - files ~= ^security/
+    actions:
+      request_reviews:
+        teams:
+          - security
+```

src/content/docs/workflow/rule-syntax.mdx

@@ -1,13 +1,103 @@
 ---
 title: Rule Syntax
-description: Overview of the syntax used in Mergify rules for Workflow Automation and Merge Queue.
+description: How to write a Mergify workflow rule, from the structure of pull_request_rules to its conditions and actions.
 ---
 
-This page is a placeholder stub to consolidate references to configuration file
-format, conditions, data types, and sharing configuration.
+import OptionsTable from '~/components/Tables/OptionsTable';
 
-Use the existing reference pages for full details:
-- [Configuration File Format](/configuration/file-format)
-- [Conditions](/configuration/conditions)
-- [Data Types](/configuration/data-types)
-- [Sharing Configuration](/configuration/sharing)
+Workflow Automation rules live under the `pull_request_rules` key in your
+[configuration file](/configuration/file-format), where each rule pairs a set of
+conditions with the actions Mergify runs when a pull request matches them. For a
+gentle introduction, see the [Workflow Automation overview](/workflow). This
+page is the field-by-field reference.
+
+## Fields
+
+`pull_request_rules` is a list, and each entry is a single rule: a YAML
+dictionary where `name`, `conditions`, and `actions` are required, while
+`description` and `disabled` are optional.
+
+<OptionsTable def="PullRequestRuleModel" />
+
+## Conditions
+
+`conditions` is a list of expressions describing which pull requests the rule
+applies to. A pull request must satisfy **every** condition in the list for the
+rule to match:
+
+```yaml
+conditions:
+  - base = main
+  - label = ready-to-merge
+```
+
+Each condition is built from an attribute (such as `base`, `label`, or
+`#approved-reviews-by`), an operator (such as `=`, `>=`, or `~=`), and usually a
+value. See the [attributes list](/configuration/conditions#attributes-list) and
+[operators list](/configuration/conditions#operators-list) for the full set.
+
+To express "any of" or "none of" instead of "all of", group conditions with the
+[`and`, `or`, and `not` operators](/configuration/conditions#combining-conditions-using-logical-operators).
+The same condition syntax also powers [Merge Queue](/merge-queue) and
+[Merge Protections](/merge-protections), so what you learn here carries over.
+
+## Actions
+
+`actions` is a dictionary that maps an action name to its parameters. A single
+rule can run several actions, and Mergify runs them all when the conditions
+match:
+
+```yaml
+pull_request_rules:
+  - name: warn and label pull requests in conflict
+    conditions:
+      - conflict
+    actions:
+      comment:
+        message: "@{{author}} this pull request is now in conflict 😩"
+      label:
+        toggle:
+          - conflict
+```
+
+The `{{author}}` placeholder is a [template](/configuration/data-types#template)
+that Mergify fills in with the pull request's data. Browse every available
+action and its parameters in the [Actions catalog](/workflow/actions).
+
+## Combining Rules
+
+Rules are evaluated independently: Mergify checks each one against the pull
+request, and every rule whose conditions match runs its actions. Order the rules
+however reads best, since matching does not stop at the first hit. For when an
+action re-runs versus stays put, see
+[how rules are evaluated](/workflow#how-rules-are-evaluated).
+
+## Disabling a Rule
+
+Set `disabled` with a `reason` to keep a rule in the file but stop it from
+running. The reason is shown in the configuration check so others know why:
+
+```yaml
+pull_request_rules:
+  - name: automatic merge
+    disabled:
+      reason: paused during the release freeze
+    conditions:
+      - "#approved-reviews-by >= 1"
+    actions:
+      merge: # merge with default options
+```
+
+## Validating Your Rules
+
+Mergify validates your configuration on every push and reports problems in the
+"Checks" tab of your pull request. To catch mistakes earlier, validate and
+simulate rules locally with the [Mergify CLI](/cli/config):
+
+```bash
+mergify config validate
+mergify config simulate https://github.com/owner/repo/pull/142
+```
+
+See [Validation and Troubleshooting](/configuration/file-format#validation-and-troubleshooting)
+for the full workflow.

src/content/navItems.tsx

@@ -233,7 +233,7 @@ const navItems: NavItem[] = [
     icon: 'lucide:zap',
     path: '/workflow',
     children: [
-      { title: 'Workflow Automation', path: '/workflow/', icon: 'lucide:zap' },
+      { title: 'Overview', path: '/workflow', icon: 'lucide:lightbulb' },
       { title: 'Rule Syntax', path: '/workflow/rule-syntax', icon: 'lucide:badge-question-mark' },
       {
         title: 'Actions',
@@ -244,7 +244,7 @@ const navItems: NavItem[] = [
           { title: 'Backport', path: '/workflow/actions/backport', icon: 'lucide:git-branch' },
           { title: 'Close', path: '/workflow/actions/close', icon: 'lucide:circle-x' },
           { title: 'Copy', path: '/workflow/actions/copy', icon: 'lucide:share-2' },
-          { title: 'Comment', path: '/workflow/actions/comment', icon: 'lucide:list' },
+          { title: 'Comment', path: '/workflow/actions/comment', icon: 'lucide:message-square' },
           {
             title: 'Delete Head Branch (Deprecated)',
             path: '/workflow/actions/delete_head_branch',
@@ -255,7 +255,11 @@ const navItems: NavItem[] = [
             path: '/workflow/actions/dismiss_reviews',
             icon: 'lucide:message-square-x',
           },
-          { title: 'Edit', path: '/workflow/actions/edit', icon: 'lucide:type' },
+          {
+            title: 'Edit',
+            path: '/workflow/actions/edit',
+            icon: 'octicon:git-pull-request-draft-16',
+          },
           {
             title: 'GitHub Actions',
             path: '/workflow/actions/github_actions',