diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md
index 22b893e30a..6f571805ab 100644
--- a/docs/src/content/docs/reference/safe-outputs.md
+++ b/docs/src/content/docs/reference/safe-outputs.md
@@ -236,6 +236,8 @@ safe-outputs:
     allowed-reasons: [outdated]  # restrict hiding reasons (optional)
 ```
 
+The author of the parent issue, PR, or discussion receiving the comment is automatically preserved as an allowed mention. This means `@username` references to the issue/PR/discussion author are not neutralized when the workflow posts a reply.
+
 #### Hide Older Comments
 
 Set `hide-older-comments: true` to minimize previous comments from the same workflow (identified by `GITHUB_WORKFLOW`) before posting new ones. Useful for status updates. Allowed reasons: `spam`, `abuse`, `off_topic`, `outdated` (default), `resolved`.
@@ -835,6 +837,10 @@ safe-outputs:
 
 When `push-to-pull-request-branch` is configured, git commands (`checkout`, `branch`, `switch`, `add`, `rm`, `commit`, `merge`) are automatically enabled.
 
+#### Fail-Fast on Code Push Failure
+
+If `push-to-pull-request-branch` (or `create-pull-request`) fails, the safe-output pipeline cancels all remaining non-code-push outputs. Each cancelled output is marked with an explicit reason such as "Cancelled: code push operation failed". The failure details appear in the agent failure issue or comment generated by the conclusion job.
+
 ### Release Updates (`update-release:`)
 
 Updates GitHub release descriptions: replace (complete replacement), append (add to end), or prepend (add to start).
diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index a15e1a7520..791032a94e 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -330,6 +330,8 @@ gh aw audit 12345678 --parse                              # Parse logs to markdo
 
 Logs are saved to `logs/run-{id}/` with filenames indicating the extraction level (job logs, specific step, or first failing step).
 
+When a workflow fails before the agent executes (for example, due to lockdown validation failures, missing secrets, or binary install failures), the audit report surfaces the actual error from the workflow step log files. The `failure_analysis.error_summary` field reflects the specific failure message rather than reporting "No specific errors identified". Providing an invalid run ID returns a human-readable error instead of a raw exit code.
+
 #### `health`
 
 Display workflow health metrics and success rates.