docs: add guide for consuming audit reports with an agent

[Mossaka]

Parent Epic

Part of #22735

Summary

The audit commands produce rich structured output (JSON, markdown) that can be consumed programmatically by agents for automated analysis, optimization, and incident response. There is no guide showing users how to do this.

What to Create

File: docs/src/content/docs/guides/audit-with-agents.md

A task-oriented guide showing how to feed audit output into agentic workflows for automated analysis.

Sections

1. Why use an agent to consume audit data?

   • Automated triage of findings across many runs
   • Pattern recognition across audit reports
   • Automated remediation suggestions (firewall rule updates, cost optimization)

2. Getting structured audit data

   • gh aw audit <run-id> --json — full JSON output to stdout
   • Key fields for agent consumption: key_findings, recommendations, firewall_analysis, mcp_tool_usage, metrics
   • Using jq to extract specific sections

3. Feeding audit data into a workflow agent

   • Example: scheduled workflow that runs gh aw audit report --json, passes output as context to an agent, and has the agent post a summary discussion
   • Example: PR-triggered workflow that runs gh aw audit <run-id> --json post-agent, feeds findings to a second agent for automated review comments
   • Example: using audit diff --json to detect regressions and auto-file issues

4. Building an audit monitoring agent

   • Full workflow example: cron-triggered agent that:
     1. Runs gh aw audit report --workflow <name> --last 10 --json
     2. Analyzes trends (cost spikes, new blocked domains, MCP error rate increases)
     3. Posts a discussion or issue with findings
     4. Alerts on critical anomalies

5. Tips

   • JSON schema stability expectations
   • Combining with --parse for raw log analysis
   • Using audit diff for before/after comparison in optimization workflows

Source Files to Reference

• pkg/cli/audit_report.go — AuditData struct (the JSON schema)
• pkg/cli/audit_cross_run.go — CrossRunAuditReport struct
• pkg/cli/audit_diff.go — AuditDiff struct
• .github/workflows/audit-workflows.md — existing audit agent workflow example