Tighten reference docs for artifact compatibility, audit JSON contracts, and safe-output safeguards

docs/src/content/docs/reference/artifacts.md

@@ -11,9 +11,9 @@ GitHub Agentic Workflows upload several artifacts during workflow execution. Thi
 
 | Artifact Name | Constant | Type | Description |
 |---------------|----------|------|-------------|
-| `agent` | `constants.AgentArtifactName` | Multi-file | Unified agent job outputs (logs, safe outputs, token usage summary) |
+| `agent` | `constants.AgentArtifactName`<br/>Source: `pkg/constants/job_constants.go` | Multi-file | Unified agent job outputs (logs, safe outputs, token usage summary) |
 | `activation` | `constants.ActivationArtifactName` | Multi-file | Activation job output (`aw_info.json`, `prompt.txt`, rate limits) |
-| `firewall-audit-logs` | `constants.FirewallAuditArtifactName` | Multi-file | AWF firewall audit/observability logs (token usage, network policy, audit trail) |
+| `firewall-audit-logs` | `constants.FirewallAuditArtifactName`<br/>Source: `pkg/constants/constants.go` | Multi-file | AWF firewall audit/observability logs (token usage, network policy, audit trail) |
 | `detection` | `constants.DetectionArtifactName` | Single-file | Threat detection log (`detection.log`) |
 | `safe-output` | `constants.SafeOutputArtifactName` | Legacy/back-compat | Historical standalone safe output artifact (`safe_output.jsonl`); in current compiled workflows this content is included in the unified `agent` artifact instead |
 | `agent-output` | `constants.AgentOutputArtifactName` | Legacy/back-compat | Historical standalone agent output artifact (`agent_output.json`); in current compiled workflows this content is included in the unified `agent` artifact instead |
@@ -25,6 +25,15 @@ GitHub Agentic Workflows upload several artifacts during workflow execution. Thi
 | `safe-outputs-items` | `constants.SafeOutputItemsArtifactName` | Single-file | Safe output items manifest |
 | `code-scanning-sarif` | `constants.SarifArtifactName` | Single-file | SARIF file for code scanning results |
 
+> [!IMPORTANT]
+> Sync note: This table mirrors artifact-name constants in `pkg/constants/job_constants.go` and `pkg/constants/constants.go`. When those constant values change, update this page and the downstream artifact references in `docs/src/content/docs/reference/audit.md` and `docs/src/content/docs/reference/cost-management.md`.
+
+## Legacy artifact names
+
+:::caution[Deprecated]
+`safe-output` and `agent-output` became legacy in the gh-aw `v0.34.x` unified-agent-artifact rollout. New downstream consumers should migrate to the unified `agent` artifact now; `gh aw logs` and `gh aw audit` keep reading the legacy names only for back-compat with older runs. Removal is planned no earlier than gh-aw `v1.0`.
+:::
+
 ## Artifact Sets
 
 The `gh aw logs` and `gh aw audit` commands support `--artifacts` to download only specific artifact groups:

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

@@ -37,6 +37,8 @@ In single-run mode, a job URL without a step anchor extracts the first failing s
 | `--verbose` | off | Print detailed progress information |
 | `--format <fmt>` | `pretty` | Diff output format: `pretty` or `markdown` (multi-run only) |
 
+Top-level fields in `--json` output are stable; nested sub-fields may be extended but are not removed without deprecation. Add `--parse` to populate `behavior_fingerprint` and `agentic_assessments`.
+
 **Single-run examples:**
 
 ```bash
@@ -71,7 +73,7 @@ gh aw audit 12345 12346 --repo owner/repo      # Specify repository
 
 **Single-run 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.
 
-The Metrics section includes an `ambient_context` object when available. Ambient context captures the first LLM inference footprint for the run:
+The Metrics section includes an `ambient_context` object when available. Ambient context captures the first LLM inference footprint for the run. It is absent when token-usage data is unavailable for the run — for example, when neither `token-usage.jsonl` nor the fallback `agent_usage.json` can be found in the downloaded artifacts, which is common for older runs and runs without firewall/usage artifacts:
 - `ambient_context.input_tokens` — input tokens for the first invocation
 - `ambient_context.cached_tokens` — cache-read tokens reused by the first invocation
 - `ambient_context.effective_tokens` — legacy ET field (`input_tokens + cached_tokens`) retained for compatibility
@@ -99,9 +101,11 @@ This feature is built into the `gh aw logs` command via the `--format` flag.
 | `--stdin` | off | Read run IDs or URLs from stdin (one per line) instead of run-discovery; content filters still apply |
 | `--verbose` | off | Print detailed progress |
 
+Top-level fields in `--json` output are stable; nested sub-fields may be extended but are not removed without deprecation.
+
 The report output includes an executive summary, domain inventory, metrics trends, MCP server health, and per-run breakdown. It detects cross-run anomalies such as domain access spikes, elevated MCP error rates, and connection rate changes.
 
-For each run in detailed logs JSON output, an `ambient_context` object is included when token usage data is available. It reflects only the first LLM invocation in the run (`input_tokens`, `cached_tokens`, and legacy `effective_tokens`).
+For each run in detailed logs JSON output, an `ambient_context` object is included when token usage data is available. It reflects only the first LLM invocation in the run (`input_tokens`, `cached_tokens`, and legacy `effective_tokens`). It is absent when the downloaded artifacts do not contain usable `token-usage.jsonl` or fallback `agent_usage.json` data for that run.
 
 **`--stdin` mode:** Pass `--stdin` to supply an explicit list of run IDs or URLs instead of letting the command discover runs from the GitHub API. Date, count, and workflow-name filters are ignored; `--engine`, `--firewall`, `--safe-output`, and other content filters still apply. Blank lines and `#`-prefixed lines are ignored. Bare numeric IDs require `--repo owner/repo`.
 
@@ -267,4 +271,4 @@ permissions:
 4. Update `/tmp/gh-aw/cache-memory/audit-trends.json` with rolling averages (cost, tokens, error count, deny rate), keeping only the last 30 days.
 ```
 
-Top-level fields (`key_findings`, `recommendations`, `metrics`, `firewall_analysis`, `mcp_tool_usage`) are stable; nested sub-fields may be extended but are not removed without deprecation. Add `--parse` to populate `behavior_fingerprint` and `agentic_assessments`. Cross-run JSON can be large — extract only the slices your model needs.
+Cross-run JSON can be large — extract only the slices your model needs.

docs/src/content/docs/reference/billing.md

@@ -25,14 +25,16 @@ There are two billing paths for the Copilot engine (`engine: copilot`, the defau
 
 1. The organization has centralized billing enabled for Copilot requests in its Copilot policies. Enable it under **Organization → Settings → Copilot → Policies → Copilot CLI → "Allow use of Copilot CLI billed to the organization"**. See also [Authentication](/gh-aw/reference/auth/#copilot-requests-write-permission).
 
-2. The workflow declares `copilot_requests: write` under `permissions`:
+2. The workflow declares `copilot-requests: write` under `permissions`:
 
        permissions:
          contents: read
          copilot-requests: write
 
 3. The workflow has been compiled (`gh aw compile`) and the updated `.lock.yml` committed to the repository.
 
+`gh aw compile` does **not** auto-inject `copilot-requests: write` into arbitrary workflow source. The permission must be declared in the workflow frontmatter. Some authoring flows such as `gh aw add` can insert it when the author explicitly chooses Copilot org billing, but the compiler otherwise only emits an informational tip.
+
 **Individual/seat billing** — If the above conditions are not met, the workflow must be configured with a user-supplied [`COPILOT_GITHUB_TOKEN`](/gh-aw/reference/auth/#copilot_github_token). In this case inference is attributed to (and limited by) the PAT owner's Copilot entitlements rather than being billed centrally through the organization.
 
 See [Engines](/gh-aw/reference/engines/) for a full list of engines and their authentication requirements, and [Authentication](/gh-aw/reference/auth/) for configuration details. For Copilot model pricing and AIC rates, see [GitHub Copilot models and pricing](https://docs.github.com/copilot/reference/copilot-billing/models-and-pricing).
@@ -51,4 +53,17 @@ When using [`engine: gemini`](/gh-aw/reference/engines/) or passing `GEMINI_API_
 
 ## Estimating and Monitoring Costs
 
-Use `gh aw logs` to view per-run AI Credits (AIC) and duration, and `gh aw audit <run-id>` for a detailed breakdown of token usage and inference spend. See [Cost Management](/gh-aw/reference/cost-management/) for monitoring strategies, cost controls, and techniques for reducing spend.
+Before dispatching a workflow, establish a budget using a recent comparable run or the published model tables. For an existing workflow, inspect recent AIC and duration first, then treat the highest recent run as a conservative pre-run cap:
+
+```bash
+gh aw logs my-workflow --last 5 --json \
+  | jq '.per_run_breakdown[] | {run_id, aic, action_minutes}'
+```
+
+For a new or materially changed workflow, compile first so the checked-in workflow and declared engine/model are final, then compare that configuration against the published pricing tables before enabling broad rollout:
+
+```bash
+gh aw compile .github/workflows/my-workflow.md
+```
+
+Use `gh aw audit <run-id>` after a representative run to validate the estimate against actual token usage and inference spend. See [Cost Management](/gh-aw/reference/cost-management/) for monitoring strategies, budget guardrails, and techniques for reducing spend, and [Model Tables](/gh-aw/reference/model-tables/) for current model pricing inputs.

docs/src/content/docs/reference/cross-repository.md

@@ -276,5 +276,6 @@ updates to each PR branch.
 - [MultiRepoOps — Central Control Plane](/gh-aw/patterns/central-repo-ops/#using-a-central-control-repository) — Central control plane pattern
 - [GitHub Tools Reference](/gh-aw/reference/github-tools/) - Complete GitHub Tools configuration
 - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe output configuration
+- [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/) - `target-repo`, `head-repo`, and fork-branch PR flows
 - [Authentication Reference](/gh-aw/reference/auth/) - PAT and GitHub App setup
 - [Multi-Repository Examples](/gh-aw/examples/multi-repo/) - Complete working examples

docs/src/content/docs/reference/gh-aw-as-mcp-server.md

@@ -40,6 +40,12 @@ gh aw mcp-server --validate-actor
 
 When enabled, the logs and audit tools require write/maintain/admin repository access. The server reads `GITHUB_ACTOR` and `GITHUB_REPOSITORY` env vars and caches permission check results for 1 hour. Without validation (default), all tools are available without checks.
 
+> [!WARNING]
+> With `--validate-actor`, the server does **not** fall back to open access when `GITHUB_ACTOR` is unset. The privileged tools stay mounted, but `logs`, `audit`, and `audit-diff` return permission-denied errors until `GITHUB_ACTOR` is provided.
+
+> [!NOTE]
+> The permission cache is in-memory only. Cached entries expire after 1 hour, and restarting `gh aw mcp-server` clears them immediately. There is currently no manual cache-flush command, so permission or repository-role changes are picked up either after TTL expiry or after a server restart.
+
 ## Configuring with GitHub Copilot Agent
 
 Configure GitHub Copilot Agent to use gh-aw MCP server:

docs/src/content/docs/reference/safe-outputs-pull-requests.md

@@ -124,7 +124,7 @@ An older **patch transport** (`git format-patch` / `git am --3way`) is used when
 The `safe_outputs` job always mirrors the agent job's checkout layout. When a `checkout:` entry places a repository in a subdirectory (a `path:` is set), `safe_outputs` checks out **every** repository to the same location the agent used — the workflow repository at the workspace root plus each cross-repo checkout at its `path:` — regardless of whether `target-repo` names a specific repository or the wildcard `"*"`. This lets a specific `target-repo` (and the two-or-more cross-repo case) operate against an identical layout. When the target repository is checked out at the workspace root (no `path:`), it is checked out there in both jobs.
 :::
 
-When `head-repo` is set, the preferred model is an ephemeral upstream-based branch: the safe output job resolves the upstream base SHA from `target-repo`, creates or refreshes a temporary branch in `head-repo` from that SHA, pushes the agent's commits there, and opens the PR back to the upstream base. Supported synchronization is limited to that configured upstream/head pairing; arbitrary reuse of unrelated fork branches is not supported.
+When `head-repo` is set, the preferred model is an ephemeral upstream-based branch: the safe output job resolves the upstream base SHA from `target-repo`, creates or refreshes a temporary branch in `head-repo` from that SHA, pushes the agent's commits there, and opens the PR back to the upstream base. Supported synchronization is limited to that configured upstream/head pairing; arbitrary reuse of unrelated fork branches is not supported. See [Cross-Repository Operations](/gh-aw/reference/cross-repository/) for the matching checkout, allowlist, and fork-credential rules.
 
 ## Pull Request Updates (`update-pull-request:`)
 
@@ -176,6 +176,9 @@ safe-outputs:
 `merge-pull-request` is an experimental safe output. `gh aw compile` emits an experimental feature warning when a workflow uses it. The merge is blocked unless every configured policy gate passes; merges to the repository default branch are always refused.
 :::
 
+> [!NOTE]
+> Graduation to stable requires all of the following: end-to-end test coverage for same-repository and cross-repository merge paths, staged-mode and live-merge parity across all documented policy gates, resolution of known false-positive/false-negative mergeability cases, and at least one release cycle without schema or behavior changes to the tool-call contract.
+
 Merges a pull request only after configured policy gates pass — status checks, review decision, unresolved review threads, label and branch constraints, and GitHub mergeability.
 
 ```yaml wrap
@@ -672,3 +675,9 @@ Protection covers three categories:
 
 > [!NOTE]
 > Runtime manifests and governance files (`CODEOWNERS`, `DESIGN.md`) are matched by **basename only** (the filename without its directory path), so they are protected regardless of where they appear in the repository. Path-prefix rules (`.github/`, `.agents/`, `.githooks/`, `.husky/`, `.claude/`, `.codex/`) match the full relative path from the repository root.
+
+## Related Documentation
+
+- [Cross-Repository Operations](/gh-aw/reference/cross-repository/) - Checkout, target-repo, allowed-repos, and fork-authentication rules
+- [Safe Outputs](/gh-aw/reference/safe-outputs/) - Complete safe output reference
+- [Triggering CI](/gh-aw/reference/triggering-ci/) - How PR-safe-outputs can request follow-up CI