From d7433c0e1725be11af4793bd1949a8c1583e128a Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sat, 4 Apr 2026 20:31:17 +0000
Subject: [PATCH] docs: update audit diff and lock file header documentation

- Update gh aw audit diff signature to reflect multi-run support:
  accepts one base run and one or more comparison runs (from #24544)
- Document token usage diff breakdown (input/output/cache tokens,
  API requests, cache efficiency) added in #24544
- Document JSON array output and divider behavior for multiple diffs
- Add lock file header section to workflow-structure.md documenting
  the gh-aw-metadata first-line placement and the Secrets/Custom
  actions manifest sections added in #24495

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/src/content/docs/reference/audit.md      | 17 ++++++++++++----
 .../docs/reference/workflow-structure.md      | 20 +++++++++++++++++++
 2 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/docs/src/content/docs/reference/audit.md b/docs/src/content/docs/reference/audit.md
index 5bc8a7b7f75..222af046ab7 100644
--- a/docs/src/content/docs/reference/audit.md
+++ b/docs/src/content/docs/reference/audit.md
@@ -51,16 +51,19 @@ gh aw audit 1234567890 --repo owner/repo
 
 **Report sections** (rendered in Markdown or JSON): Overview, Comparison, Task/Domain, Behavior Fingerprint, Agentic Assessments, Metrics, Key Findings, Recommendations, Observability Insights, Performance Metrics, Engine Config, Prompt Analysis, Session Analysis, Safe Output Summary, MCP Server Health, Jobs, Downloaded Files, Missing Tools, Missing Data, Noops, MCP Failures, Firewall Analysis, Policy Analysis, Redacted Domains, Errors, Warnings, Tool Usage, MCP Tool Usage, Created Items.
 
-## `gh aw audit diff <run-id-1> <run-id-2>`
+## `gh aw audit diff <base-run-id> <comparison-run-id> [<comparison-run-id>...]`
 
-Compare behavior between two workflow runs. Detects policy regressions, new unauthorized domains, behavioral drift, and changes in MCP tool usage or run metrics.
+Compare behavior between workflow runs. Detects policy regressions, new unauthorized domains, behavioral drift, and changes in MCP tool usage or run metrics.
 
 **Arguments:**
 
 | Argument | Description |
 |----------|-------------|
-| `<run-id-1>` | Numeric run ID for the baseline run |
-| `<run-id-2>` | Numeric run ID for the comparison run |
+| `<base-run-id>` | Numeric run ID for the baseline run |
+| `<comparison-run-id>` | Numeric run ID for the comparison run |
+| `[<comparison-run-id>...]` | Additional run IDs to compare against the same base |
+
+The base run is downloaded once and reused when multiple comparison runs are provided. Self-comparisons and duplicate run IDs are rejected.
 
 **Flags:**
 
@@ -79,11 +82,17 @@ The diff output includes:
 - Anomaly flags (new denied domains, previously-denied domains now allowed)
 - MCP tool invocation changes (new/removed tools, call count and error count diffs)
 - Run metrics comparison (token usage, duration, turns)
+- Token usage breakdown: input tokens, output tokens, cache read/write tokens, effective tokens, total API requests, and cache efficiency per run
+
+**Output behavior with multiple comparisons:**
+- `--json` outputs a single object for one comparison, or an array for multiple
+- `--format pretty` and `--format markdown` separate multiple diffs with dividers
 
 **Examples:**
 
 ```bash
 gh aw audit diff 12345 12346
+gh aw audit diff 12345 12346 12347 12348
 gh aw audit diff 12345 12346 --format markdown
 gh aw audit diff 12345 12346 --json
 gh aw audit diff 12345 12346 --repo owner/repo
diff --git a/docs/src/content/docs/reference/workflow-structure.md b/docs/src/content/docs/reference/workflow-structure.md
index 2986cc484cb..442458790f0 100644
--- a/docs/src/content/docs/reference/workflow-structure.md
+++ b/docs/src/content/docs/reference/workflow-structure.md
@@ -46,6 +46,26 @@ When you run the `compile` command you generate the lock file.
 gh aw compile
 ```
 
+### Lock File Header
+
+Each compiled lock file begins with a machine-readable metadata line followed by a human-readable manifest of its external dependencies:
+
+```yaml
+# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"...","strict":true,"agent_id":"copilot"}
+#    ___  ...ASCII logo...
+# This file was automatically generated by gh-aw. DO NOT EDIT.
+# ...
+# Secrets used:
+#   - COPILOT_GITHUB_TOKEN
+#   - GITHUB_TOKEN
+#
+# Custom actions used:
+#   - actions/checkout@de0fac2e... # v6.0.2
+#   - actions/upload-artifact@bbbca2... # v4
+```
+
+The `gh-aw-metadata` line is always first, enabling reliable machine parsing. The `Secrets used` and `Custom actions used` sections list all `secrets.*` references and external `uses:` dependencies (excluding local `./` refs) found in the compiled workflow, sorted and deduplicated.
+
 ## Editing Workflows
 
 The **markdown body** is loaded at runtime and can be edited directly on GitHub.com without recompilation. Only **frontmatter changes** require recompilation.