diff --git a/docs/src/content/docs/experimental/trial-ops.md b/docs/src/content/docs/experimental/trial-ops.md
index 3d8c2a1d871..55d6c642fd4 100644
--- a/docs/src/content/docs/experimental/trial-ops.md
+++ b/docs/src/content/docs/experimental/trial-ops.md
@@ -107,6 +107,8 @@ Results are saved in `trials/*.json` with workflow runs, issues, PRs, and commen
 {
   "workflow_name": "weekly-research",
   "run_id": "12345678",
+  "success": true,
+  "safe_output_errors": [],
   "safe_outputs": {
     "issues_created": [{
       "number": 5,
@@ -121,7 +123,9 @@ Results are saved in `trials/*.json` with workflow runs, issues, PRs, and commen
 }
 ```
 
-**Success indicators:** Green checkmark, expected outputs created, no errors in logs.
+`success` provides an explicit pass/fail signal for each workflow result. When safe-output processing rejects one or more requested actions, `safe_output_errors` contains the rejected-message errors and `gh aw trial` exits non-zero instead of reporting unconditional success.
+
+**Success indicators:** Green checkmark, expected outputs created, no safe-output errors in logs or JSON results.
 
 **Common issues:**
 
diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
index d2a5adde6ec..c53cb66e7ba 100644
--- a/docs/src/content/docs/reference/frontmatter.md
+++ b/docs/src/content/docs/reference/frontmatter.md
@@ -278,6 +278,17 @@ Enables defining custom MCP tools inline using JavaScript or shell scripts. See
 
 Enables automatic issue creation, comment posting, and other safe outputs. See [Safe Outputs Processing](/gh-aw/reference/safe-outputs/).
 
+`safe-outputs:` also accepts workflow-level control fields that apply to safe-output processing as a whole, not just individual handlers. For example, `report-failed-jobs: false` disables the automatic failed-job reporting issue created by the framework:
+
+```yaml wrap
+safe-outputs:
+  create-issue:
+    max: 1
+  report-failed-jobs: false
+```
+
+When omitted, `report-failed-jobs` defaults to `true`.
+
 ### Run Configuration (`run-name:`, `runs-on:`, `runs-on-slim:`, `timeout-minutes:`)
 
 Standard GitHub Actions properties: