[docs] Self-healing documentation fixes from issue analysis - 2026-03-27

[github-actions]

Self-Healing Documentation Fixes

This PR was automatically created by the Daily Documentation Healer workflow.

Gaps Fixed

• gh aw audit diff — not documented in cli.md. This subcommand compares behavioral drift between two workflow runs (new/removed domains, MCP tool changes, metrics).
• gh aw audit report — not documented in cli.md. Added in feat: gh aw audit report — cross-run security audit reports #23047 (merged 2026-03-26), this subcommand generates cross-run security audit reports by aggregating firewall data across multiple runs.

The audit section was restructured from a flat command into h5 subsections (audit <run-id>, audit diff, audit report) following the same pattern used by the secrets command.

Root Cause

audit report was merged at 23:06 UTC on 2026-03-26 (#23047), after DDUw's daily 6am UTC run. DDUw therefore had no opportunity to document it before this healer run. audit diff predated the 7-day window but was never documented.

The systemic pattern: late-day merges (after DDUw's 6am window) are not picked up until the next daily run. If the doc-healer runs before DDUw the next day, it can catch these gaps.

💡 DDUw Improvement Suggestions

DDUw Improvement Suggestions

Pattern: Features merged after DDUw's 6am UTC run create a ~24-hour documentation lag. The doc-healer can bridge this gap but only if it runs after the merge and before the next DDUw run.

Suggested fix: DDUw could optionally run a second lightweight scan at ~22:00 UTC to catch late-day merges, or the doc-healer could be scheduled closer to midnight UTC so it catches same-day late merges before they become stale.

Second pattern: The audit command has subcommands (diff, report) but the docs treated it as a single command. DDUw's commit-scanning heuristic should flag new cmd.AddCommand(...) calls in audit.go as triggering a documentation review of the parent command's section.

Related Issues

Closed issues analyzed:

• 🔍 Multi-Device Docs Testing Report - 2026-03-25 #22890, [cli-consistency] CLI Consistency Issues - 2026-03-24 #22702, [cli-consistency] CLI Consistency Issues - 2026-03-23 #22435, 🔍 Multi-Device Docs Testing Report - 2026-03-23 #22363, 🔍 Multi-Device Docs Testing Report - 2026-03-22 #22226, 🔍 Multi-Device Docs Testing Report - 2026-03-21 #22074, [cli-consistency] CLI Consistency Issues - 2026-03-20 #21967, 🔍 Multi-Device Docs Testing Report - 2026-03-20 #21896, [cli-consistency] CLI Consistency Issues - 2026-03-19 #21808, 🔍 Multi-Device Docs Testing Report - 2026-03-19 #21714, [cli-consistency] CLI Consistency Issues - 2026-03-18 #21599 — reviewed; documentation file gaps were already addressed by prior PRs ([docs] Self-healing documentation fixes from issue analysis - 2026-03-26 #23124 and others)

References:

• §23648136065

Generated by Daily Documentation Healer · ◷

• expires on Mar 30, 2026, 1:32 PM UTC

[Copilot]

Pull request overview

Updates the CLI reference documentation to cover missing gh aw audit subcommands and restructure the audit section to match the subcommand pattern used elsewhere.

Changes:

• Restructures audit docs into subsections for single-run audit, audit diff, and audit report
• Documents gh aw audit diff usage, behavior summary, and flags
• Documents gh aw audit report usage, behavior summary, and flags

Comments suppressed due to low confidence (4)

docs/src/content/docs/setup/cli.md:435

• For audit diff, the docs imply run metric comparisons are always included. In the CLI help/implementation this section is only available when cached data is available. Please qualify this in the docs (e.g., “when cached data is available”) to avoid overpromising.

The diff output shows: new or removed network domains, status changes (allowed ↔ denied), volume changes (>100% threshold), MCP tool invocation changes, and run metric comparisons (token usage, duration, turns).

docs/src/content/docs/setup/cli.md:437

• audit diff supports --output/-o (it downloads/caches artifacts under the output directory), but the options list here omits it. Please add --output/-o to the documented options (and optionally include an example showing a custom output directory).

**Options:** `--format` (pretty, markdown, json; default: pretty), `--json`, `--repo/-r`

docs/src/content/docs/setup/cli.md:453

• audit report also supports --output/-o (used as the destination for downloaded artifacts/cache), but it’s not listed in the options here. Please include --output/-o so readers can control where the run data is stored.

**Options:** `--workflow/-w` (filter by workflow name or filename), `--last` (number of recent runs to analyze; default: 20, max: 50), `--format` (markdown, pretty, json; default: markdown), `--json`, `--repo/-r`

docs/src/content/docs/setup/cli.md:394

• This audit section doesn’t mention the --output/-o flag even though the command supports it, and later it states logs are saved under logs/run-{id}/ even though the default output dir is .github/aw/logs (so .github/aw/logs/run-{id}/ by default). Please document --output/-o here and make the saved-path wording accurate (ideally relative to --output).

Analyze a single run with a rich multi-section report. Accepts run IDs, workflow run URLs, job URLs, and step-level URLs. Auto-detects Copilot coding agent runs for specialized parsing. Job URLs automatically extract specific job logs; step URLs extract specific steps; without step, extracts first failing step.

```bash wrap
gh aw audit 12345678                                      # By run ID

---

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

[Copilot]

The subsection header audit <run-id> is inconsistent with the actual CLI usage and the paragraph immediately below it (which says URLs are accepted). The audit command’s Use string is audit <run-id-or-url>, so the docs header should reflect that to avoid implying only numeric IDs are supported.

This issue also appears in the following locations of the same file:

• line 390
• line 435
• line 437
• line 453

Suggested change

	##### `audit <run-id>`
	##### `audit <run-id-or-url>`