[docs] Update documentation for features from 2026-06-18

docs/src/content/docs/reference/cost-management.md

@@ -137,21 +137,21 @@ for the emitted fields.
 
 The primary cost lever for most workflows is how often they run. Some events are inherently high-frequency:
 
-#### High Risk
+### High Risk
 
 - **`push`** — Every commit to any matching branch fires the workflow
 - **`check_run`**, **`check_suite`** — Can fire many times per push in busy repositories
 
-#### Medium–High Risk
+### Medium–High Risk
 
 - **`pull_request`** — Fires on open, sync, re-open, label, and other subtypes
 - **`issues`** — Fires on open, close, label, edit, and other subtypes
 
-#### Medium Risk
+### Medium Risk
 
 - **`issue_comment`**, **`pull_request_review_comment`** — Scales with comment activity
 
-#### Low / Predictable Risk
+### Low / Predictable Risk
 
 - **`schedule`** — Fires at a fixed cadence; easy to budget
 - **`workflow_dispatch`** — Human-initiated; naturally rate-limited
@@ -545,25 +545,25 @@ The [githubnext/agentic-ops](https://github.com/githubnext/agentic-ops) reposito
 
 These are rough estimates to help with budgeting. Actual costs vary by prompt size, tool usage, model, and provider pricing.
 
-#### Weekly digest (schedule, 1 repo)
+### Weekly digest (schedule, 1 repo)
 
 - **Frequency:** 4×/month
 - **Actions minutes/month:** ~1 min
 - **Inference/month:** Varies by model and prompt size
 
-#### Issue triage (issues opened, 20/month)
+### Issue triage (issues opened, 20/month)
 
 - **Frequency:** 20×/month
 - **Actions minutes/month:** ~10 min
 - **Inference/month:** Varies by model and prompt size
 
-#### PR review on every push (busy repo, 100 pushes/month)
+### PR review on every push (busy repo, 100 pushes/month)
 
 - **Frequency:** 100×/month
 - **Actions minutes/month:** ~100 min
 - **Inference/month:** Varies by model and prompt size
 
-#### On-demand via slash command
+### On-demand via slash command
 
 - **Frequency:** User-controlled
 - **Actions minutes/month:** Varies

docs/src/content/docs/reference/safe-outputs-pull-requests.md

@@ -10,6 +10,7 @@ This page is the primary reference for pull-request-focused safe outputs:
 - [`create-pull-request`](#pull-request-creation-create-pull-request)
 - [`update-pull-request`](#pull-request-updates-update-pull-request)
 - [`close-pull-request`](#close-pull-request-close-pull-request)
+- [`merge-pull-request`](#merge-pull-request-merge-pull-request) (experimental)
 - [`create-pull-request-review-comment`](#pr-review-comments-create-pull-request-review-comment)
 - [`submit-pull-request-review`](#submit-pr-review-submit-pull-request-review)
 - [`reply-to-pull-request-review-comment`](#reply-to-pr-review-comment-reply-to-pull-request-review-comment)
@@ -146,6 +147,38 @@ safe-outputs:
     github-token: ${{ secrets.SOME_CUSTOM_TOKEN }} # optional custom token for permissions
 ```
 
+## Merge Pull Request (`merge-pull-request:`)
+
+:::caution[Experimental]
+`merge-pull-request` is an experimental safe output. `gh aw compile` emits an experimental feature warning when a workflow uses it. The merge is blocked unless every configured policy gate passes; merges to the repository default branch are always refused.
+:::
+
+Merges a pull request only after configured policy gates pass — status checks, review decision, unresolved review threads, label and branch constraints, and GitHub mergeability.
+
+```yaml wrap
+safe-outputs:
+  merge-pull-request:
+    max: 1                            # max merges per run (default: 1, range: 1-10)
+    required-labels: [ready-to-merge] # ALL listed labels must be present on the PR
+    required-title-prefix: "[bot] "   # only merge PRs whose title starts with this prefix
+    allowed-branches: ["feature/*"]   # glob patterns for the PR's source branch
+    target: "triggering"              # "triggering" (default, current PR) or "*" (any PR with pull_request_number)
+    target-repo: "owner/repo"         # cross-repository target
+    allowed-repos: ["org/other-repo"] # additional repositories the agent can merge into
+    staged: false                     # if true, evaluate gates and emit preview results without performing the merge
+    github-token: ${{ secrets.SOME_CUSTOM_TOKEN }} # optional custom token for permissions
+```
+
+**Target**: `"triggering"` (requires a PR event) or `"*"` (the agent supplies `pull_request_number` in the tool call). When `target: "*"` is used with cross-repository configuration, the agent may also supply `repo` (in `owner/repo` format); the value must match `target-repo` or appear in `allowed-repos`.
+
+**Merge method**: The agent selects `merge`, `squash`, or `rebase` per tool call. The base branch is taken from the pull request; merges to the repository default branch are refused by this safe output type.
+
+**Gate semantics**: The handler validates mergeability (not draft, no conflicts), required status checks, the GitHub review decision, unresolved review thread gating, `required-labels`, `required-title-prefix`, and `allowed-branches`. If any gate fails, the merge is skipped and the reason is reported. Idempotent: already-merged PRs return success.
+
+**Staged mode**: Setting `staged: true` runs all gate checks and emits a preview result without calling the GitHub merge API. Use this to validate policy in dry-run scenarios.
+
+See [Cross-Repository Operations](/gh-aw/reference/cross-repository/) for `target-repo`, `allowed-repos`, and authentication configuration. See the [Safe Outputs Specification](/gh-aw/specs/safe-outputs-specification/#type-merge_pull_request) for the complete schema and operational semantics.
+
 ## PR Review Comments (`create-pull-request-review-comment:`)
 
 Creates review comments on specific code lines in PRs. Supports single-line and multi-line comments.

docs/src/content/docs/reference/safe-outputs.md

@@ -41,6 +41,7 @@ The agent requests issue creation; a separate job with `issues: write` creates i
 | [Create PR](/gh-aw/reference/safe-outputs-pull-requests/#pull-request-creation-create-pull-request) | `create-pull-request` | Create pull requests with code changes (default max: 1, configurable) |
 | [Update PR](/gh-aw/reference/safe-outputs-pull-requests/#pull-request-updates-update-pull-request) | `update-pull-request` | Update PR title or body (max: 1) |
 | [Close PR](/gh-aw/reference/safe-outputs-pull-requests/#close-pull-request-close-pull-request) | `close-pull-request` | Close pull requests without merging (max: 10) |
+| [Merge PR](/gh-aw/reference/safe-outputs-pull-requests/#merge-pull-request-merge-pull-request) | `merge-pull-request` | Merge pull requests after policy gates pass (max: 1, experimental) |
 | [PR Review Comments](/gh-aw/reference/safe-outputs-pull-requests/#pr-review-comments-create-pull-request-review-comment) | `create-pull-request-review-comment` | Create review comments on code lines (max: 10) |
 | [Reply to PR Review Comment](/gh-aw/reference/safe-outputs-pull-requests/#reply-to-pr-review-comment-reply-to-pull-request-review-comment) | `reply-to-pull-request-review-comment` | Reply to existing review comments (max: 10) |
 | [Resolve PR Review Thread](/gh-aw/reference/safe-outputs-pull-requests/#resolve-pr-review-thread-resolve-pull-request-review-thread) | `resolve-pull-request-review-thread` | Resolve review threads after addressing feedback (max: 10) |