github · pelikhan · Mar 23, 2026 · Mar 23, 2026
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -44,7 +44,7 @@ Developed by GitHub Next and Microsoft Research, workflows run with added guardr
   <FeatureCard icon="mark-github" title="GitHub Integration" href="/gh-aw/reference/github-tools/">
     Deep integration with Actions, Issues, PRs, Discussions, and repository management
   </FeatureCard>
-  <FeatureCard icon="shield-lock" title="Safety First" href="/gh-aw/introduction/architecture">
+  <FeatureCard icon="shield-lock" title="Safety First" href="/gh-aw/introduction/architecture/">
     Sandboxed execution with minimal permissions and safe output processing
   </FeatureCard>
   <FeatureCard icon="beaker" title="Multiple AI Engines" href="/gh-aw/reference/engines/">

diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
@@ -20,6 +20,26 @@ Set `engine:` in your workflow frontmatter and configure the corresponding secre
 
 Copilot CLI is the default — `engine:` can be omitted when using Copilot. See the linked authentication docs for secret setup instructions.
 
+## Engine Feature Comparison
+
+Not all features are available across all engines. The table below summarizes per-engine support for commonly used workflow options:
+
+| Feature | Copilot | Claude | Codex | Gemini |
+|---------|:-------:|:------:|:-----:|:------:|
+| `max-turns` | ❌ | ✅ | ❌ | ❌ |
+| `max-continuations` | ✅ | ❌ | ❌ | ❌ |
+| `tools.web-fetch` | ✅ | ✅ | ✅ | ✅ |
+| `tools.web-search` | via MCP | via MCP | ✅ (opt-in) | via MCP |
+| `engine.agent` (custom agent file) | ✅ | ❌ | ❌ | ❌ |
+| `engine.api-target` (custom endpoint) | ✅ | ✅ | ✅ | ✅ |
+| Tools allowlist | ✅ | ✅ | ✅ | ✅ |
+
+**Notes:**
+- `max-turns` limits the number of AI chat iterations per run (Claude only).
+- `max-continuations` enables autopilot mode with multiple consecutive runs (Copilot only).
+- `web-search` for Codex is disabled by default; add `tools: web-search:` to enable it. Other engines use a third-party MCP server — see [Using Web Search](/gh-aw/guides/web-search/).
+- `engine.agent` references a `.github/agents/` file for custom Copilot agent behavior. See [Copilot Custom Configuration](#copilot-custom-configuration).
+
 ## Extended Coding Agent Configuration
 
 Workflows can specify extended configuration for the coding agent:

diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md
@@ -64,6 +64,7 @@ The agent requests issue creation; a separate job with `issues: write` creates i
 
 - [**Dispatch Workflow**](#workflow-dispatch-dispatch-workflow) (`dispatch-workflow`) - Trigger other workflows with inputs (max: 3, same-repo only)
 - [**Call Workflow**](#workflow-call-call-workflow) (`call-workflow`) - Call reusable workflows via compile-time fan-out (max: 1, same-repo only)
+- [**Dispatch Repository Event**](#repository-dispatch-dispatch_repository) (`dispatch_repository`) - Trigger `repository_dispatch` events in external repositories, experimental (cross-repo)
 - [**Code Scanning Alerts**](#code-scanning-alerts-create-code-scanning-alert) (`create-code-scanning-alert`) - Generate SARIF security advisories (max: unlimited, same-repo only)
 - [**Autofix Code Scanning Alerts**](#autofix-code-scanning-alerts-autofix-code-scanning-alert) (`autofix-code-scanning-alert`) - Create automated fixes for code scanning alerts (max: 10, same-repo only)
 - [**Create Agent Session**](#agent-session-creation-create-agent-session) (`create-agent-session`) - Create Copilot coding agent sessions (max: 1)
@@ -1269,6 +1270,55 @@ Use `call-workflow` for deterministic fan-out where actor attribution and zero A
 - **Allowlist enforcement** - Only workflows listed in `workflows` can be called; unlisted names are rejected at runtime.
 - **Compile-time validation** - Misconfiguration is caught before the workflow runs.
 
+### Repository Dispatch (`dispatch_repository`)
+
+> [!CAUTION]
+> This is an experimental feature. Compiling a workflow with `dispatch_repository` emits a warning: `Using experimental feature: dispatch_repository`. The API may change in future releases.
+
+Triggers [`repository_dispatch`](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#repository_dispatch) events in external repositories. Unlike `dispatch-workflow` (same-repo only), `dispatch_repository` is designed for cross-repository orchestration.
+
+Each key under `dispatch_repository:` defines a named tool exposed to the agent:
+
+```yaml wrap
+safe-outputs:
+  dispatch_repository:
+    trigger_ci:
+      description: Trigger CI in another repository
+      workflow: ci.yml
+      event_type: ci_trigger
+      repository: ${{ inputs.target_repo }}   # GitHub Actions expressions supported
+      inputs:
+        environment:
+          type: choice
+          options: [staging, production]
+          default: staging
+      max: 1
+    notify_service:
+      workflow: notify.yml
+      event_type: notify_event
+      allowed_repositories:
+        - org/service-repo
+        - ${{ vars.DYNAMIC_REPO }}             # Expressions bypass slug format validation
+      inputs:
+        message:
+          type: string
+```
+
+#### Configuration Fields (per tool)
+
+- **`workflow`** (required) — Identifier forwarded in `client_payload.workflow` so the receiving workflow can route by job type.
+- **`event_type`** (required) — The `event_type` sent with the `repository_dispatch` event.
+- **`repository`** (required, unless `allowed_repositories` is set) — Static `owner/repo` slug or a GitHub Actions expression (`${{ ... }}`). Expressions are passed through without format validation.
+- **`allowed_repositories`** (required, unless `repository` is set) — List of allowed `owner/repo` slugs or expressions. The agent selects the target from this list at runtime.
+- **`inputs`** (optional) — Structured input schema forwarded in `client_payload`. Supports `type: string`, `type: choice` (with `options`), and `default` values.
+- **`description`** (optional) — Human-readable description of the tool shown to the agent.
+- **`max`** (optional) — Maximum number of dispatches allowed per run (default: 1).
+
+#### Security
+
+- **Cross-repo allowlist** — At runtime the handler validates the target repository against the configured `repository` or `allowed_repositories` before calling the API (SEC-005).
+- **Staged mode** — Supports `staged: true` for preview without dispatching.
+
 ### Agent Session Creation (`create-agent-session:`)
 
 Creates Copilot coding agent sessions from workflow output. Allows workflows to spawn new agent sessions for follow-up work.

diff --git a/docs/src/content/docs/troubleshooting/common-issues.md b/docs/src/content/docs/troubleshooting/common-issues.md
@@ -85,6 +85,23 @@ The CLI validates three permission layers. Fix restrictions in Repository Settin
 
 ## Workflow Compilation Issues
 
+### Frontmatter Field Not Taking Effect
+
+If a frontmatter setting appears to be silently ignored, the field name may be misspelled. The compiler does not warn about unknown field names — they are silently discarded.
+
+> [!WARNING]
+> Common frontmatter field name mistakes:
+>
+> | Wrong | Correct |
+> |-------|---------|
+> | `agent:` | `engine:` |
+> | `mcp-servers:` | `tools:` (under which MCP servers are configured) |
+> | `tool-sets:` | `toolsets:` (under `tools.github:`) |
+> | `allowed_repos:` | `allowed-repos:` (under `tools.github:`) |
+> | `timeout:` | `timeout-minutes:` |
+>
+> Run `gh aw compile --verbose` to confirm which settings were parsed. If your setting is missing from the output, check the [Frontmatter Reference](/gh-aw/reference/frontmatter/) for the correct field name.
+
 ### Workflow Won't Compile
 
 Check YAML frontmatter syntax (indentation, colons with spaces), verify required fields (`on:`), and ensure types match the schema. Use `gh aw compile --verbose` for details.