docs: update documentation for features merged 2026-04-27 (#28697)

Author: github-actions[bot]

docs/src/content/docs/reference/playwright.md

@@ -105,36 +105,88 @@ Create an issue for each category of problems found.
 
 ### Visual Regression Testing
 
+Pin to a specific version and use `steps:` to start the application before the agent runs. This is the recommended pattern when testing a local dev server.
+
 ```aw wrap
 ---
 on:
   pull_request:
     types: [opened, synchronize]
+    paths:
+      - 'docs/src/**/*.css'
+      - 'docs/src/**/*.tsx'
+      - 'docs/src/**/*.astro'
+      - 'docs/astro.config.mjs'
+
+steps:
+  - name: Checkout repository
+    uses: actions/checkout@v6
+    with:
+      persist-credentials: false
+  - name: Install dependencies
+    working-directory: ./docs
+    run: npm ci
+  - name: Build documentation
+    working-directory: ./docs
+    run: npm run build
+  - name: Start dev server
+    working-directory: ./docs
+    run: npm run dev &
+  - name: Wait for dev server
+    run: |
+      for i in $(seq 1 30); do
+        if curl -sf http://localhost:4321/ > /dev/null 2>&1; then
+          echo "Dev server is ready"; exit 0
+        fi
+        sleep 1
+      done
+      exit 1
 
 tools:
   playwright:
+    version: "v1.52.0"
+  bash:
+    - "npm *"
+    - "curl http://localhost:*"
 
 network:
   allowed:
     - defaults
     - playwright
-    - github
+    - local
+    - node
 
 permissions:
   contents: read
 
 safe-outputs:
   add-comment:
     max: 1
+  noop:
 ---
 
 # Visual Regression Check
 
-Compare screenshots of the documentation site before and after this PR.
+The documentation site dev server is running at http://localhost:4321/.
+
+Check for visual regressions on these pages: home, getting-started, and reference.
+
+Test on multiple viewports:
+- Mobile: 375×812
+- Tablet: 768×1024
+- Desktop: 1440×900
 
-Test on multiple viewports (mobile, tablet, desktop) and report any visual differences.
+Take screenshots at each viewport and compare against baseline. Report any visual differences as a pull request comment, including screenshots. If there are no regressions, call noop.
 ```
 
+**Key patterns for dev server visual regression:**
+
+- **Path filter** — restricts the trigger to runs affecting frontend assets, avoiding noise on unrelated changes.
+- **`steps:`** — run before the agent. Use them to install dependencies, build, start the server, and poll until it is ready. The agent only starts after all steps succeed.
+- **Version pin** — pin Playwright to a specific version (`v1.52.0`) to prevent baseline drift from browser engine upgrades mid-test.
+- **`local` network identifier** — allows the Playwright container to reach `localhost`/`127.0.0.1` where the dev server runs. Required when testing local servers.
+- **`bash` allowlist** — restricts the `bash` tool to `npm *` and `curl http://localhost:*` only, keeping the tool surface minimal.
+
 ### End-to-End Testing
 
 ```aw wrap

docs/src/content/docs/reference/triggers.md

@@ -279,6 +279,97 @@ Workflows with `workflow_run` triggers include automatic security protections:
 
 See the [Security Architecture](/gh-aw/introduction/architecture/) for details.
 
+### Deployment Status Triggers (`deployment_status:`)
+
+Trigger workflows when a GitHub deployment status changes. [Full event reference](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#deployment_status).
+
+```yaml wrap
+on:
+  deployment_status:
+```
+
+#### State Filtering (`state:`)
+
+Use `state:` to restrict the trigger to specific deployment states. The compiler compiles this into a guarded `if:` condition so the workflow only runs for the matching states. Other combined triggers (such as `workflow_dispatch`) are not blocked by the guard.
+
+```yaml wrap
+on:
+  deployment_status:
+    state: failure            # Single state
+```
+
+```yaml wrap
+on:
+  deployment_status:
+    state: [error, failure]   # Multiple states
+  workflow_dispatch:           # Safely combined — guard ensures dispatch passes through
+```
+
+Valid `state` values: `error`, `failure`, `pending`, `success`, `inactive`, `in_progress`, `queued`, `waiting`.
+
+> [!NOTE]
+> The `state` field compiles into a GitHub Actions `if:` condition: `github.event_name != 'deployment_status' || (github.event.deployment_status.state == 'failure')`. This means the workflow still runs when triggered by other events in the same `on:` block.
+
+#### Required Permissions
+
+Workflows triggered by `deployment_status` need `deployments: read` to access the event payload:
+
+```yaml wrap
+permissions:
+  contents: read
+  deployments: read
+```
+
+#### Natural Language Shorthands
+
+```yaml wrap
+on: "deployment failed"             # deployment_status with state == 'failure'
+on: "deployment error"              # deployment_status with state == 'error'
+on: "deployment failed or error"    # deployment_status with state == 'failure' or 'error'
+```
+
+These shorthands also include `workflow_dispatch` automatically.
+
+#### Deployment Incident Monitor Example
+
+```aw wrap
+---
+on:
+  deployment_status:
+    state: [error, failure]
+  workflow_dispatch:
+permissions:
+  contents: read
+  actions: read
+  deployments: read
+tools:
+  github:
+    toolsets: [repos, actions]
+safe-outputs:
+  create-issue:
+    expires: 7d
+    title-prefix: "[Incident] "
+    labels: [incident, deployment-failure]
+    close-older-issues: true
+    skip-if-match: 'is:issue is:open label:incident label:deployment-failure'
+  noop:
+---
+
+# Deployment Incident Monitor
+
+A deployment to ${{ github.event.deployment.environment }} has failed with state: ${{ github.event.deployment_status.state }}.
+
+Investigate the root cause:
+1. Check the deployment workflow logs for the failing step
+2. Review recent commits to the deployed branch for potential causes
+3. Check if this environment has had recent failures (look for existing incident issues)
+
+If a new incident is found, create an issue summarising the failure, the likely root cause, and the recommended next step.
+If an incident issue for this deployment already exists, call noop.
+```
+
+See the [Natural Language Shorthands](#other-shorthands) section for additional shorthand formats.
+
 ### Command Triggers (`slash_command:`)
 
 The `slash_command:` trigger creates workflows that respond to `/command-name` mentions in issues, pull requests, and comments.
@@ -727,6 +818,9 @@ on: dependabot pull request         # PR from Dependabot (adds actor condition)
 on: security alert                  # Code scanning alert
 on: code scanning alert             # Alias for security alert (code scanning alert)
 on: api dispatch custom-event       # Repository dispatch with custom event type
+on: "deployment failed"             # deployment_status with state == 'failure' guard
+on: "deployment error"              # deployment_status with state == 'error' guard
+on: "deployment failed or error"    # deployment_status with state == 'failure' or 'error' guard
 ```
 
 ## Related Documentation