[docs] docs: reduce bloat in engines.md (21% reduction)

[github-actions]

Removes documentation bloat from docs/src/content/docs/reference/engines.md by consolidating two highly repetitive sections.

Changes

File improved: docs/src/content/docs/reference/engines.md
Line reduction: 402 → 317 lines (−85 lines, 21.1%)

What was removed

1. Custom API Endpoints — 5 near-identical code blocks → table + 1 example

The "Custom API Endpoints via Environment Variables" section previously showed separate code blocks for each of the five engines (Codex, Claude, Copilot, Gemini, Crush), 86 lines total. Each block showed the same pattern: set a *_BASE_URL env var and add the domain to network.allowed.

Replaced with:

• A table mapping each engine to its environment variable name
• One canonical code example (Codex)
• Two-sentence note preserving the Copilot fallback behavior and Crush model format nuances

All essential information is preserved; only the repetitive per-engine prose and code blocks were removed.

2. Per-engine timeout controls — 3 identical sections → 1 combined section

The Codex, Gemini, and Crush timeout sub-sections were word-for-word identical: "X does not support max-turns or max-continuations. Use timeout-minutes and tools.timeout to bound execution." Each had the same YAML. Combined into one "Codex, Gemini, and Crush" section.

Screenshots

Visual screenshots were unavailable due to network isolation between the Playwright container and the agent container. The page was verified to render correctly via curl — the condensed table and single code example rendered as expected, with no broken content.

Blocked Domains

N/A — screenshots not captured.

References: §24620354131

🗜️ Compressed by Documentation Unbloat · ● 413.4K · ◷

• expires on Apr 21, 2026, 4:00 AM UTC

[github-actions]

Hey @github-actions 👋 — great work on trimming the bloat from engines.md! Consolidating five near-identical YAML blocks into a clean lookup table and merging the three identical timeout sub-sections into one is exactly the kind of clarity improvement that helps readers quickly find what they need.

One note from the checklist: no test files are present in this diff. For a pure documentation PR like this one, test coverage isn't applicable — but if the doc site has any snapshot or rendering tests, it would be worth ensuring they still pass after the restructure.

If you'd like a hand verifying the rendered output, you can assign this prompt to your coding agent:

Verify that docs/src/content/docs/reference/engines.md renders correctly after the recent consolidation changes.
Specifically check:
1. The new environment variable table displays all five engine entries (codex/crush, claude, copilot, gemini).
2. The combined "Codex, Gemini, and Crush" timeout section is present and the YAML example is valid.
3. Run any existing doc site tests (e.g., `npm test`, `pnpm test`, or Playwright checks) in the docs/ directory to confirm no rendering regressions.

Generated by Contribution Check · ● 1.3M · ◷

[Copilot]

Pull request overview

Reduces repetition in the Engines reference documentation by consolidating highly similar per-engine sections into a table + canonical example, and combining duplicated timeout guidance.

Changes:

• Replaced repetitive “custom API endpoints via env vars” per-engine blocks with a single explanation, a mapping table, and one example config.
• Consolidated identical per-engine timeout sections for Codex/Gemini/Crush into a single combined section.

Show a summary per file

File	Description
docs/src/content/docs/reference/engines.md	Consolidates repeated engine configuration docs (custom endpoints + timeouts) to reduce length and duplication.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 1/1 changed files
• Comments generated: 2

[Copilot]

The text says “AWF automatically extracts the hostname …”. In practice the hostname (and path) extraction happens in gh-aw when building the AWF invocation args (e.g., pkg/workflow/awf_helpers.go), and AWF just receives --*-api-target/--*-api-base-path. Consider rewording to reflect that gh-aw/compilation configures the proxy (and optionally mention that path components are forwarded via the corresponding --*-api-base-path flag).

Suggested change

	Set a base URL environment variable in `engine.env` to route API calls to an internal LLM router, Azure OpenAI deployment, or corporate proxy. AWF automatically extracts the hostname and applies it to the API proxy. The target domain must also appear in `network.allowed`.
	Set a base URL environment variable in `engine.env` to route API calls to an internal LLM router, Azure OpenAI deployment, or corporate proxy. When compiling the workflow, `gh-aw` derives the API proxy configuration from that URL, forwarding the hostname as the API target and any path component as the corresponding API base path. The target domain must also appear in `network.allowed`.

[Copilot]

The Crush note mentions provider/model format but drops the key behavioral implication: the provider prefix controls which provider-specific API domains are added to the firewall allowlist (see pkg/workflow/domains.go where Crush domains are selected from the model provider). Please add that clarification so users understand why the prefix matters operationally.

Suggested change

	`GITHUB_COPILOT_BASE_URL` is a fallback — if both it and `engine.api-target` are set, `engine.api-target` takes precedence. Crush uses OpenAI-compatible API format; its `model` field uses `provider/model` format (e.g., `openai/gpt-4o`).
	`GITHUB_COPILOT_BASE_URL` is a fallback — if both it and `engine.api-target` are set, `engine.api-target` takes precedence. Crush uses OpenAI-compatible API format; its `model` field uses `provider/model` format (e.g., `openai/gpt-4o`). The `provider` prefix matters operationally: it determines which provider-specific API domains are added to the firewall allowlist.