diff --git a/docs/src/content/docs/guides/security.md b/docs/src/content/docs/guides/security.md
index b44a0db70b..cdc4e661bf 100644
--- a/docs/src/content/docs/guides/security.md
+++ b/docs/src/content/docs/guides/security.md
@@ -178,9 +178,18 @@ network:
 
 Or via CLI: `gh aw compile --strict`
 
-**Enforces**: write permissions blocked (use `safe-outputs`), explicit network configuration required, no network wildcards, MCP network configuration required.
+**Enforcement Areas:**
 
-**Benefits**: Minimizes attack surface, ensures compliance, improves auditability. CLI flag takes precedence over frontmatter. See [Frontmatter Reference](/gh-aw/reference/frontmatter/#strict-mode-strict).
+Strict mode enforces the following security constraints:
+
+1. **Write Permissions**: Blocks `contents:write`, `issues:write`, and `pull-requests:write`. Use `safe-outputs` instead.
+2. **Network Configuration**: Requires explicit network configuration (no implicit defaults).
+3. **Network Wildcards**: Refuses wildcard `*` in `network.allowed` domains.
+4. **MCP Network**: Requires network configuration for custom MCP servers with containers.
+5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs.
+6. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.
+
+**Benefits**: Minimizes attack surface, ensures compliance, improves auditability. CLI flag takes precedence over frontmatter and applies to all workflows. See [Frontmatter Reference](/gh-aw/reference/frontmatter/#strict-mode-strict) and [CLI Commands](/gh-aw/setup/cli/#compile) for complete documentation.
 
 #### Limit workflow longevity by `stop-after:`
 
diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
index 1891113c76..7dad820b71 100644
--- a/docs/src/content/docs/reference/frontmatter.md
+++ b/docs/src/content/docs/reference/frontmatter.md
@@ -183,9 +183,32 @@ Enables enhanced validation for production workflows, enforcing security constra
 strict: true  # Enable (default: false)
 ```
 
-Strict mode enforces: (1) no write permissions for `contents`, `issues`, or `pull-requests` (use `safe-outputs` instead), (2) explicit network configuration required, (3) no wildcard `*` in `network.allowed`, (4) network configuration for custom MCP servers with containers.
+**Enforcement Areas:**
 
-Enable with `strict: true` in frontmatter or `gh aw compile --strict` (CLI flag applies to all workflows and takes precedence). Use for production workflows requiring enhanced security validation or security policy compliance.
+Strict mode enforces the following security constraints:
+
+1. **Write Permissions**: Refuses `contents:write`, `issues:write`, and `pull-requests:write` permissions. Use [safe-outputs](/gh-aw/reference/safe-outputs/) instead for GitHub API write operations.
+
+2. **Network Configuration**: Requires explicit network configuration. No implicit defaults allowed. See [Network Permissions](/gh-aw/reference/network/).
+
+3. **Network Wildcards**: Refuses wildcard `*` in `network.allowed` domains. Specify explicit domains or use ecosystem identifiers.
+
+4. **MCP Network**: Requires network configuration for custom MCP servers with containers.
+
+5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs instead of tags or branches.
+
+6. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.
+
+**Enabling Strict Mode:**
+
+Strict mode can be enabled in two ways:
+
+- **Frontmatter field**: `strict: true` (per-workflow control)
+- **CLI flag**: `gh aw compile --strict` (applies to all workflows, takes precedence)
+
+The CLI flag enables strict mode for all workflows being compiled and cannot be overridden by individual workflow frontmatter. The frontmatter field allows per-workflow strict mode but cannot disable strict mode when the CLI flag is set.
+
+See [CLI Commands](/gh-aw/setup/cli/#compile) for detailed `--strict` flag documentation and [Security Guide](/gh-aw/guides/security/#strict-mode-validation) for security best practices.
 
 ### Feature Flags (`features:`)
 
diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index 6b5384be84..44276630a0 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -141,13 +141,47 @@ Remote imports are automatically cached in `.github/aw/imports/` for offline com
 | Option | Description |
 |--------|-------------|
 | `--validate` | Schema validation and container checks |
-| `--strict` | Requires timeouts, explicit network config, blocks write permissions |
+| `--strict` | Enable strict mode validation for all workflows |
 | `--zizmor` | Security scanning with [zizmor](https://github.com/woodruffw/zizmor) |
 | `--dependabot` | Generate npm/pip/Go manifests and update dependabot.yml |
 | `--json` | Output validation results in machine-readable JSON format |
 | `--watch` | Auto-recompile on file changes |
 | `--purge` | Remove orphaned `.lock.yml` files |
 
+**Strict Mode (`--strict`):**
+
+The `--strict` flag enables enhanced security validation for all workflows during compilation. This flag is recommended for production workflows that require strict security compliance.
+
+When enabled, strict mode enforces:
+
+1. **No Write Permissions**: Blocks `contents:write`, `issues:write`, and `pull-requests:write` permissions. Use [safe-outputs](/gh-aw/reference/safe-outputs/) instead.
+
+2. **Explicit Network Configuration**: Requires explicit `network` configuration. No implicit defaults allowed.
+
+3. **No Network Wildcards**: Refuses wildcard `*` in `network.allowed` domains. Use explicit domains or ecosystem identifiers.
+
+4. **MCP Server Network**: Requires network configuration for custom MCP servers with containers.
+
+5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs.
+
+6. **No Deprecated Fields**: Refuses deprecated frontmatter fields.
+
+**Precedence:** The `--strict` CLI flag applies to all workflows being compiled and takes precedence over individual workflow `strict` frontmatter fields. Workflows cannot opt-out of strict mode when the CLI flag is set.
+
+**Example:**
+```bash wrap
+# Enable strict mode for all workflows
+gh aw compile --strict
+
+# Strict mode with security scanning (fails on findings)
+gh aw compile --strict --zizmor
+
+# Validate schema and enforce strict mode
+gh aw compile --validate --strict
+```
+
+See [Strict Mode reference](/gh-aw/reference/frontmatter/#strict-mode-strict) for frontmatter configuration and [Security Guide](/gh-aw/guides/security/#strict-mode-validation) for best practices.
+
 ### Testing
 
 #### `trial`