From 722927ea80b9c2e6c3ec7913e8e9a77b14e4dde9 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 29 May 2026 11:50:39 +0000
Subject: [PATCH] docs: fill audit Options gaps and correct safe-output
 add_comment example

- cli.md: complete the audit run-id and diff Options lists with the
  --artifacts, --experiment, --variant, --output/-o, and --format
  flags that are already implemented (closes the audit portion of the
  CLI consistency gap tracked in #35223).
- tools.md: update the safeoutputs add_comment CLI example to use
  --item_number (the parameter name actually accepted by the safe-
  output schema). The previous --issue_number form is silently
  stripped, per the hardening done in #35584.
---
 docs/src/content/docs/reference/tools.md | 4 +++-
 docs/src/content/docs/setup/cli.md       | 6 ++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/src/content/docs/reference/tools.md b/docs/src/content/docs/reference/tools.md
index e05512b37a3..6d269eaed63 100644
--- a/docs/src/content/docs/reference/tools.md
+++ b/docs/src/content/docs/reference/tools.md
@@ -138,10 +138,12 @@ tools:
 With CLI mounting enabled, MCP servers accessible to the workflow (such as `safeoutputs` and `mcpscripts`) are wrapped as executable commands. For example:
 
 ```bash
-safeoutputs add_comment --issue_number 42 --body "Analysis complete"
+safeoutputs add_comment --item_number 42 --body "Analysis complete"
 mcpscripts mcpscripts-gh --args "issue list --limit 5"
 ```
 
+The safe-output `add_comment` tool uses `--item_number` (not `--issue_number`) to target the issue or pull request — passing `--issue_number` is silently stripped by schema validation.
+
 The MCP gateway configuration is unchanged — servers still start as normal. Only the agent's view changes: servers registered for CLI mounting are removed from the MCP tool list and accessed via shell instead.
 
 This reduces token consumption from large MCP tool schemas and can simplify workflow prompts when shell-style invocation is preferred.
diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index 560f791be0e..6e62fd26b95 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -487,10 +487,12 @@ echo -e "1234567890\n9876543210" | gh aw audit --stdin   # diff mode: first is b
 cat run-ids.txt | gh aw audit --stdin --repo owner/repo
 ```
 
-**Options:** `--parse`, `--json`, `--repo/-r`, `--stdin`
+**Options:** `--artifacts`, `--experiment`, `--format`, `--json/-j`, `--output/-o`, `--parse`, `--repo/-r`, `--stdin`, `--variant`
 
 The `--repo` flag accepts `owner/repo` format and is required when passing a bare numeric run ID without a full URL, allowing the command to locate the correct repository.
 
+The `--artifacts` flag selects which artifact sets to download (default: all). Valid sets include `activation`, `agent`, `detection`, `firewall`, `github-api`, and `mcp`. The `--experiment` flag filters to runs that include the named experiment; `--variant` further restricts to a specific variant value and requires `--experiment` to be set. The `--output/-o` flag overrides the output directory.
+
 Logs are saved to `logs/run-{id}/` with filenames indicating the extraction level. Pre-agent failures (integrity filtering, missing secrets, binary install) surface the actual error in `failure_analysis.error_summary`. Invalid run IDs return a human-readable error.
 
 **Report sections:**
@@ -523,7 +525,7 @@ gh aw audit 12345 12346 --repo owner/repo   # Specify repository
 
 The diff output shows: new or removed network domains, status changes (allowed ↔ denied), volume changes (>100% threshold), MCP tool invocation changes, run metric comparisons (token usage, duration, turns), tokens-per-turn changes, and per-tool and per-bash-command call breakdowns.
 
-**Options:** `--format` (pretty, markdown; default: pretty), `--json`, `--repo/-r`
+**Options:** `--artifacts`, `--format` (pretty, markdown; default: pretty), `--json/-j`, `--output/-o`, `--repo/-r`
 
 :::note[Cross-run security reports (`audit report` removed in v0.66.1)]
 Cross-run security and performance reports are now generated by `gh aw logs --format`. Use `--count` or `--last` to control the number of runs analyzed.