From 7526b569f80114c36ab9284715a6ce83736170ac Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Wed, 25 Feb 2026 04:24:20 +0000
Subject: [PATCH] docs: document gh aw validate command and threat-detection
 import precedence

- Add `validate` command section to setup/cli.md (Building section, after
  compile). The command was added in #18191 but was missing from the main
  CLI reference page; only the compilation-process.md reference table had
  been updated.

- Add NOTE callout to reference/threat-detection.md clarifying that an
  explicit `threat-detection: false` in a workflow takes precedence over
  imported fragments, documenting the behaviour fixed in #18231.

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

diff --git a/docs/src/content/docs/reference/threat-detection.md b/docs/src/content/docs/reference/threat-detection.md
index abe565e5d7..f124c752df 100644
--- a/docs/src/content/docs/reference/threat-detection.md
+++ b/docs/src/content/docs/reference/threat-detection.md
@@ -64,6 +64,9 @@ safe-outputs:
   threat-detection: false  # Disable threat detection
 ```
 
+> [!NOTE]
+> When a workflow explicitly sets `threat-detection: false`, that setting takes precedence over any imported fragments. Imported shared workflows that configure safe outputs without a `threat-detection` key will not re-enable threat detection in the importing workflow.
+
 ### Advanced Configuration
 
 Use object syntax for fine-grained control:
diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index 6db6d778d7..4e5a8a1d31 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -231,6 +231,25 @@ gh aw compile --purge                      # Remove orphaned .lock.yml files
 
 **Shared Workflows:** Workflows without an `on` field are detected as shared components. Validated with relaxed schema and skip compilation. See [Imports reference](/gh-aw/reference/imports/).
 
+#### `validate`
+
+Validate agentic workflows by running the compiler with all linters enabled, without generating lock files. Equivalent to `gh aw compile --validate --no-emit --zizmor --actionlint --poutine`.
+
+```bash wrap
+gh aw validate                              # Validate all workflows
+gh aw validate my-workflow                  # Validate specific workflow
+gh aw validate my-workflow daily            # Validate multiple workflows
+gh aw validate --json                       # Output results in JSON format
+gh aw validate --strict                     # Enforce strict mode validation
+gh aw validate --fail-fast                  # Stop at the first error
+gh aw validate --dir custom/workflows       # Validate from custom directory
+gh aw validate --engine copilot             # Override AI engine
+```
+
+**Options:** `--engine/-e`, `--dir/-d`, `--strict`, `--json/-j`, `--fail-fast`, `--stats`, `--no-check-update`
+
+All linters (`zizmor`, `actionlint`, `poutine`), `--validate`, and `--no-emit` are always-on defaults and cannot be disabled. Accepts the same workflow ID format as `compile`.
+
 ### Testing
 
 #### `trial`