Parent Epic

Part of #22735

Summary

The audit epic shipped ~13K LOC with 3 CLI commands (gh aw audit, gh aw audit diff, gh aw audit report), but there are zero dedicated documentation pages in the docs site. This issue tracks creating the primary reference page.

What to Create

File: docs/src/content/docs/reference/audit.md

An exhaustive command reference covering all three audit subcommands:

gh aw audit <run-id-or-url>

• All accepted input formats (run ID, run URL, job URL, step URL, GHES URLs)
• Flags table: --output, --json, --parse, --repo, --verbose
• All 25+ report sections documented (from AuditData struct in pkg/cli/audit_report.go): Overview, Comparison, TaskDomain, BehaviorFingerprint, AgenticAssessments, Metrics, KeyFindings, Recommendations, ObservabilityInsights, PerformanceMetrics, EngineConfig, PromptAnalysis, SessionAnalysis, SafeOutputSummary, MCPServerHealth, Jobs, DownloadedFiles, MissingTools, MissingData, Noops, MCPFailures, FirewallAnalysis, PolicyAnalysis, RedactedDomainsAnalysis, Errors, Warnings, ToolUsage, MCPToolUsage, CreatedItems
• Output formats: console (stderr), JSON (stdout), markdown (--parse)
• Caching behavior
• GHES auto-detection

gh aw audit diff <run1> <run2>

• What it compares: firewall domains, MCP tool invocations, run metrics
• Flags: --format (pretty, markdown), --json, --repo
• Diff output structure: NewDomains, RemovedDomains, StatusChanges, VolumeChanges, MCPToolsDiff, RunMetricsDiff
• Anomaly detection rules

gh aw audit report

• What it aggregates across runs
• Flags: --workflow, --last, --format, --json, --repo
• Report structure: Executive Summary, Domain Inventory, Metrics Trends, MCP Health, Error Trends
• Cross-run thresholds (spike detection, MCP error rate, connection rate)

Also Include

• JSON schema documentation for AuditData, AuditDiff, and CrossRunAuditReport for programmatic consumers
• Exit codes section

Source Files to Reference

• pkg/cli/audit.go — command definition, flags, URL parsing
• pkg/cli/audit_report.go — AuditData struct
• pkg/cli/audit_diff_command.go — diff command flags
• pkg/cli/audit_report_cross_run_command.go — report command flags
• pkg/cli/audit_report_render.go — output format details