From 03291036e983c74e5889c0d0d2a7bb3006c311b5 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 11 Jun 2026 12:09:11 +0000
Subject: [PATCH] [docs] Document threat-detection max-ai-credits and
 add-wizard Copilot auth prompt

Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>
---
 .../content/docs/reference/cost-management.md |  7 ++++++
 .../docs/reference/threat-detection.md        | 22 +++++++++++++++++++
 docs/src/content/docs/setup/cli.md            |  2 ++
 3 files changed, 31 insertions(+)

diff --git a/docs/src/content/docs/reference/cost-management.md b/docs/src/content/docs/reference/cost-management.md
index f658ea97c31..ce3ab305cbe 100644
--- a/docs/src/content/docs/reference/cost-management.md
+++ b/docs/src/content/docs/reference/cost-management.md
@@ -269,6 +269,13 @@ When the budget is approached, gh-aw emits steering warnings before
 the run reaches the limit. Set a negative value only when budget
 enforcement must be disabled explicitly.
 
+> [!NOTE]
+> Threat-detection runs have their own AI Credits cap, separate
+> from the main agent budget. See
+> [Threat Detection → Detection Budget](/gh-aw/reference/threat-detection/#detection-budget)
+> for `safe-outputs.threat-detection.max-ai-credits` (defaults to
+> `400`, overridable via `GH_AW_DEFAULT_DETECTION_MAX_AI_CREDITS`).
+
 ### Cap Turns per Run
 
 Use the top-level `max-turns` frontmatter field to cap the number
diff --git a/docs/src/content/docs/reference/threat-detection.md b/docs/src/content/docs/reference/threat-detection.md
index b2a53cfc6ee..9e623905d76 100644
--- a/docs/src/content/docs/reference/threat-detection.md
+++ b/docs/src/content/docs/reference/threat-detection.md
@@ -95,6 +95,28 @@ safe-outputs:
 | `runs-on` | string/array/object | Runner for the detection job (default: inherits from workflow `runs-on`) |
 | `steps` | array | Additional GitHub Actions steps to run **before** AI analysis (pre-steps) |
 | `post-steps` | array | Additional GitHub Actions steps to run **after** AI analysis (post-steps) |
+| `max-ai-credits` | integer | AI Credits cap for the detection run, independent of the main agent budget. Defaults to `400` when unset, with runtime override via `vars.GH_AW_DEFAULT_DETECTION_MAX_AI_CREDITS`. Accepts plain integers; `-1` disables the detection budget. |
+
+## Detection Budget
+
+Threat-detection runs have their own AI Credits budget, separate from the main agent's `max-ai-credits`. Detection does **not** inherit the main agent's budget — both caps apply independently to their respective jobs.
+
+Set `safe-outputs.threat-detection.max-ai-credits` to override the per-run detection budget:
+
+```yaml wrap
+safe-outputs:
+  create-pull-request:
+  threat-detection:
+    max-ai-credits: 750
+```
+
+When unset, the compiler emits a runtime resolution that falls back to the built-in default of `400`:
+
+```yaml
+${{ vars.GH_AW_DEFAULT_DETECTION_MAX_AI_CREDITS || '400' }}
+```
+
+Set the org-wide default with the [`GH_AW_DEFAULT_DETECTION_MAX_AI_CREDITS`](/gh-aw/reference/compiler-enterprise-environment-controls/) GitHub Actions variable. A value of `-1` disables AWF budget steering for detection runs.
 
 ## AI-Based Detection (Default)
 
diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index a9ab59cf49e..7c66175fc37 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -161,6 +161,8 @@ gh aw add-wizard githubnext/agentics/ci-doctor --skip-secret  # Skip secret prom
 
 **Options:** `--skip-secret`, `--dir/-d`, `--engine/-e`, `--no-gitattributes`, `--no-stop-after`, `--stop-after`
 
+When the Copilot engine is selected, the wizard prompts the user to choose an authentication method: organization billing via [`permissions.copilot-requests: write`](/gh-aw/reference/auth/#copilot-requests-write-permission) (no PAT required), or a [`COPILOT_GITHUB_TOKEN`](/gh-aw/reference/auth/#copilot_github_token) personal access token. Selecting org billing injects the `copilot-requests: write` permission into the workflow frontmatter and skips the API key secret prompt.
+
 #### `add`
 
 Add workflows from The Agentics collection or other repositories to `.github/workflows`. For remote workflows, this command follows frontmatter [`redirect`](/gh-aw/reference/frontmatter/#redirect-redirect) declarations before installation.