diff --git a/.github/aw/github-agentic-workflows.md b/.github/aw/github-agentic-workflows.md
index ff7c346bfa5..62e96f4ee82 100644
--- a/.github/aw/github-agentic-workflows.md
+++ b/.github/aw/github-agentic-workflows.md
@@ -740,6 +740,20 @@ The YAML frontmatter supports these fields:
     ```
 
     Operation types: `append` (default), `prepend`, `replace`.
+  - `merge-pull-request:` - Merge pull requests under configured policy gates (experimental)
+
+    ```yaml
+    safe-outputs:
+      merge-pull-request:
+        required-labels: [approved]         # Optional: all listed labels must be present
+        allowed-labels: [ready-to-merge]    # Optional: at least one PR label must match
+        allowed-branches: ["feature/*"]     # Optional: glob patterns for source branch names
+        max: 1                              # Optional: max merges (default: 1)
+    ```
+
+    **⚠️ Experimental**: Compilation emits a warning when this feature is used. The merge is blocked unless all configured gates pass.
+
+    When using `safe-outputs.merge-pull-request`, the main job does **not** need `pull-requests: write` permission since merging is handled by a separate job with appropriate permissions.
   - `close-pull-request:` - Safe pull request closing with filtering
 
     ```yaml
@@ -1445,6 +1459,9 @@ The YAML frontmatter supports these fields:
   - `concurrency-group:` - Concurrency group for the safe-outputs job (string)
     - When set, the safe-outputs job uses this concurrency group with `cancel-in-progress: false`
     - Supports GitHub Actions expressions, e.g., `"safe-outputs-${{ github.repository }}"`
+  - `needs:` - Additional custom workflow jobs the safe-outputs job depends on (array)
+    - Example: `needs: [secrets_fetcher]`
+    - Use when the safe-outputs job requires outputs from a custom job defined in `jobs:`
   - `environment:` - Override the GitHub deployment environment for the safe-outputs job (string)
     - Defaults to the top-level `environment:` field when not specified
     - Use when the main job and safe-outputs job need different deployment environments for protection rules