diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
index 88d9325600..82982805f9 100644
--- a/docs/src/content/docs/reference/frontmatter.md
+++ b/docs/src/content/docs/reference/frontmatter.md
@@ -218,35 +218,49 @@ The compiler validates workflows have sufficient permissions for their configure
 
 **Strict mode** (`gh aw compile --strict`): Treats under-provisioned permissions as compilation errors. Use for production workflows requiring enhanced security validation.
 
-### Repository Access Roles (`roles:`)
+### Repository Access Roles (`on.roles:`)
 
 Controls who can trigger agentic workflows based on repository permission level. Defaults to `[admin, maintainer, write]`.
 
 ```yaml wrap
-roles: [admin, maintainer, write]  # Default
-roles: all                         # Allow any user (⚠️ use with caution)
+on:
+  issues:
+    types: [opened]
+  roles: [admin, maintainer, write]  # Default
+```
+
+```yaml wrap
+on:
+  workflow_dispatch:
+  roles: all                         # Allow any user (⚠️ use with caution)
 ```
 
 Available roles: `admin`, `maintainer`, `write`, `read`, `all`. Workflows with unsafe triggers (`push`, `issues`, `pull_request`) automatically enforce permission checks. Failed checks cancel the workflow with a warning.
 
-### Bot Filtering (`bots:`)
+> [!TIP]
+> Run `gh aw fix workflow.md --write` to automatically migrate top-level `roles:` to `on.roles:` using the built-in codemod.
+
+### Bot Filtering (`on.bots:`)
 
 Configure which GitHub bot accounts can trigger workflows. Useful for allowing specific automation bots while maintaining security controls.
 
 ```yaml wrap
-bots: 
-  - "dependabot[bot]"
-  - "renovate[bot]"
-  - "agentic-workflows-dev[bot]"
+on:
+  issues:
+    types: [opened]
+  bots:
+    - "dependabot[bot]"
+    - "renovate[bot]"
+    - "agentic-workflows-dev[bot]"
 ```
 
 **Behavior**:
 
 - When specified, only the listed bot accounts can trigger the workflow
 - The bot must be active (installed) on the repository to trigger the workflow
-- Combine with `roles:` for comprehensive access control
+- Combine with `on.roles:` for comprehensive access control
 - Applies to all workflow triggers (`pull_request`, `issues`, etc.)
-- When `roles: all` is set, bot filtering is not enforced
+- When `on.roles: all` is set, bot filtering is not enforced
 
 **Common bot names**:
 
@@ -255,6 +269,9 @@ bots:
 - `github-actions[bot]` - GitHub Actions bot
 - `agentic-workflows-dev[bot]` - Development bot for testing workflows
 
+> [!TIP]
+> Run `gh aw fix workflow.md --write` to automatically migrate top-level `bots:` to `on.bots:` using the built-in codemod.
+
 ### Skip Roles (`on.skip-roles`)
 
 Skip workflow execution for users with specific repository permission levels. Useful for exempting team members from automated checks that should only apply to external contributors.
@@ -444,11 +461,15 @@ Standard GitHub Actions `env:` syntax for workflow-level environment variables:
 ```yaml wrap
 env:
   CUSTOM_VAR: "value"
-  SECRET_VAR: ${{ secrets.MY_SECRET }}
 ```
 
 Environment variables can be defined at multiple scopes (workflow, job, step, engine, safe-outputs, etc.) with clear precedence rules. See [Environment Variables](/gh-aw/reference/environment-variables/) for complete documentation on all 13 env scopes and precedence order.
 
+> [!WARNING]
+> Do not use `${{ secrets.* }}` expressions in the workflow-level `env:` section. Environment variables defined here are passed directly to the agent container, which means secret values would be visible to the AI model. In strict mode, this is a compilation error. In non-strict mode, it emits a warning.
+>
+> Use engine-specific secret configuration instead of the `env:` section to pass secrets securely.
+
 ## Secrets (`secrets:`)
 
 Defines secret values passed to workflow execution. Secrets are typically used to provide sensitive configuration to MCP servers or workflow components. Values must be GitHub Actions expressions that reference secrets (e.g., `${{ secrets.API_KEY }}`).
diff --git a/docs/src/content/docs/reference/permissions.md b/docs/src/content/docs/reference/permissions.md
index 803786bd5f..186099c342 100644
--- a/docs/src/content/docs/reference/permissions.md
+++ b/docs/src/content/docs/reference/permissions.md
@@ -45,7 +45,9 @@ Key permissions include `contents` (code access), `issues` (issue management), `
 
 #### Special Permission: `id-token`
 
-The `id-token: write` permission is a special case that is explicitly allowed in workflows, including strict mode. This permission enables [OpenID Connect (OIDC) authentication](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) for cloud provider authentication (AWS, GCP, Azure) without storing long-lived credentials.
+The `id-token` permission controls access to GitHub's OIDC token service for [OpenID Connect (OIDC) authentication](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) with cloud providers (AWS, GCP, Azure).
+
+The only valid values are `write` and `none`. `id-token: read` is not a valid permission and will be rejected at compile time.
 
 Unlike other write permissions, `id-token: write` does not grant any ability to modify repository content. It only allows the workflow to request a short-lived OIDC token from GitHub's token service for authentication with external cloud providers.
 
diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md
index 1715278c43..c97defed83 100644
--- a/docs/src/content/docs/reference/safe-outputs.md
+++ b/docs/src/content/docs/reference/safe-outputs.md
@@ -267,25 +267,47 @@ safe-outputs:
 
 ### Add Labels (`add-labels:`)
 
-Adds labels to issues or PRs. Specify `allowed` to restrict to specific labels.
+Adds labels to issues or PRs. Specify `allowed` to restrict to specific labels, or `blocked` to deny specific label patterns regardless of the allow list.
 
 ```yaml wrap
 safe-outputs:
   add-labels:
     allowed: [bug, enhancement]  # restrict to specific labels
+    blocked: ["~*", "*[bot]"]   # deny labels matching these glob patterns
     max: 3                       # max labels (default: 3)
     target: "*"                  # "triggering" (default), "*", or number
     target-repo: "owner/repo"    # cross-repository
 ```
 
+#### Blocked Label Patterns
+
+The `blocked` field accepts glob patterns that are evaluated before the `allowed` list. Any label matching a blocked pattern is rejected, even if it also appears in the allowed list. This provides infrastructure-level protection against prompt injection attacks in repositories with many labels where maintaining an exhaustive allowlist is impractical.
+
+Common patterns:
+
+| Pattern | Effect |
+|---------|--------|
+| `~*` | Denies all labels starting with `~` (often used as workflow triggers) |
+| `*[bot]` | Denies all labels ending with `[bot]` (administrative bot labels) |
+| `stale` | Denies the exact `stale` label |
+
+```yaml wrap
+safe-outputs:
+  add-labels:
+    blocked: ["~*", "*[bot]"]    # Blocked patterns evaluated first
+    allowed: [bug, enhancement]  # Allowed list applied after blocked check
+    max: 5
+```
+
 ### Remove Labels (`remove-labels:`)
 
-Removes labels from issues or PRs. Specify `allowed` to restrict which labels can be removed. If a label is not present on the item, it will be silently skipped.
+Removes labels from issues or PRs. Specify `allowed` to restrict which labels can be removed, or `blocked` to prevent removal of specific label patterns. If a label is not present on the item, it will be silently skipped.
 
 ```yaml wrap
 safe-outputs:
   remove-labels:
     allowed: [automated, stale]  # restrict to specific labels (optional)
+    blocked: ["~*"]              # deny removal of labels matching these glob patterns
     max: 3                       # max operations (default: 3)
     target: "*"                  # "triggering" (default), "*", or number
     target-repo: "owner/repo"    # cross-repository
@@ -293,7 +315,7 @@ safe-outputs:
 
 **Target**: `"triggering"` (requires issue/PR event), `"*"` (any issue/PR), or number (specific issue/PR).
 
-When `allowed` is omitted or set to `null`, any labels can be removed. Use `allowed` to restrict removal to specific labels only, providing control over which labels agents can manipulate.
+When `allowed` is omitted or set to `null`, any labels can be removed. Use `allowed` to restrict removal to specific labels only, providing control over which labels agents can manipulate. The `blocked` field takes precedence over `allowed`.
 
 **Example use case**: Label lifecycle management where agents add temporary labels during triage and remove them once processed.
 
@@ -1151,6 +1173,18 @@ safe-outputs:
 
 ## Global Configuration Options
 
+### Group Reports (`group-reports:`)
+
+Controls whether failed workflow runs are grouped under a parent "[agentics] Failed runs" issue. This is opt-in and defaults to `false`.
+
+```yaml wrap
+safe-outputs:
+  create-issue:
+  group-reports: true   # Enable parent issue grouping for failed runs (default: false)
+```
+
+When enabled, individual failed run reports are linked as sub-issues under a shared parent issue, making it easier to track recurring failures across workflow runs. When disabled (the default), each failure is reported independently.
+
 ### Custom GitHub Token (`github-token:`)
 
 Override for all safe outputs, or per safe output: