[docs] Update documentation for features from 2026-03-10

[github-actions]

Documentation Updates - 2026-03-10

This PR updates the documentation based on features merged in the last 24 hours.

Features Documented

• New CLI flags for run, audit, new, and list commands (from Add missing flags to run, audit, new, and list commands for CLI consistency #20272)
• New report-failure-as-issue safe-outputs option (from Improve failure issue actionability with generic debug prompt and report-failure-as-issue option #20266)

Changes Made

• Updated docs/src/content/docs/setup/cli.md:
  • gh aw run --json / -j: documents new JSON output flag that emits a JSON array of triggered workflow results to stdout
  • gh aw audit --repo / -r: documents new flag for specifying owner/repo when passing a bare numeric run ID
  • gh aw new --engine / -e: documents new flag to inject engine: into the generated frontmatter template
  • gh aw list --dir / -d: documents new flag for overriding the local workflow directory (consistent with validate, fix, add)
• Updated docs/src/content/docs/reference/safe-outputs.md:
  • Added new Failure Issue Reporting (report-failure-as-issue:) section under Global Configuration Options
  • Documents report-failure-as-issue: false to suppress automatic failure issue creation per workflow (defaults to true)

Merged PRs Referenced

• Add missing flags to run, audit, new, and list commands for CLI consistency #20272 - Add missing flags to run, audit, new, and list commands for CLI consistency
• Improve failure issue actionability with generic debug prompt and report-failure-as-issue option #20266 - Improve failure issue actionability with generic debug prompt and report-failure-as-issue option

Not Requiring Documentation

• refactor: split safe_outputs_generation.go (1549 lines) into focused modules #20296 - Pure internal refactor (safe_outputs_generation.go split), no user-facing changes
• fix(step-names): standardize "Install dev dependencies" → "Install development dependencies" and "Install uv" → "Setup uv" #20295 - Internal step name standardization, no user-facing changes
• fix(audit): gracefully skip non-zip artifacts instead of crashing #20294 - Bug fix for non-zip artifact handling, no new features
• Fix schema/validation mismatch: add "public" to repos enum in guard-policies #20281 - Schema fix for repos: public — already documented in github-tools.md
• Add concurrency.job-discriminator to prevent fan-out cancellations in job-level concurrency groups #20190 - concurrency.job-discriminator — already documented in reference/concurrency.md and reference/frontmatter-full.md
• fix: move permission computation to dedicated safe_outputs_permissions.go #20270, fix(safe-outputs): treat pull_request_target as valid PR context in create_pull_request_review_comment #20268, [log] Add debug logging to artifact manager, update command, and MCP config utils #20261 - Internal fixes and logging changes
• docs: add dedicated staged mode documentation page for safe outputs #20269 - Docs PR (already merged as dedicated staged mode page)
• Other PRs - Bug fixes, internal refactors, or already-documented changes

Generated by Daily Documentation Updater · ◷

• expires on Mar 11, 2026, 4:22 AM UTC

[Copilot]

Pull request overview

Updates user-facing documentation to reflect newly merged CLI flags and a new safe-outputs configuration option.

Changes:

• Documents gh aw new --engine/-e and shows how it injects engine: into generated frontmatter.
• Documents gh aw run --json/-j, gh aw list --dir/-d, and gh aw audit --repo/-r.
• Adds safe-outputs.report-failure-as-issue documentation under global safe-outputs configuration options.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/src/content/docs/setup/cli.md	Adds/extends CLI command examples and option notes for new flags (run --json, audit --repo, new --engine, list --dir).
docs/src/content/docs/reference/safe-outputs.md	Documents new global safe-outputs option report-failure-as-issue and its intended behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

This section references the noop.report-as-issue pattern, but the earlier “No-Op Logging (noop:)” section doesn’t document report-as-issue, so readers won’t know what that comparison means. Either add a short explanation/link to the noop option, or rephrase without relying on an undocumented setting.

[Copilot]

In this frontmatter example, the closing line uses ..., which is a YAML document end marker but not the standard Markdown frontmatter delimiter. For consistency with other workflow examples (which use --- to close frontmatter), consider replacing ... with --- or using a comment (e.g., # ...) to indicate omitted fields so readers don't copy an invalid frontmatter block.

[Copilot]

The list command supports remote listing via --repo/-r and --path (see pkg/cli/list_workflows_command.go:41-76), but this section’s options list omits those flags while the text references --repo. Consider adding --repo/-r (and --path) to the documented options/examples so readers can actually use --dir vs --path correctly for local vs remote repos.

[Copilot]

This paragraph says --repo is required when passing a bare numeric run ID, but audit can resolve {owner}/{repo} from the current repo context when owner/repo aren’t provided (see fetchWorkflowRunMetadata in pkg/cli/audit.go:614-620). Suggest rewording to clarify that --repo is only needed when auditing a run outside the current repository context (or when the run ID alone is ambiguous).