diff --git a/docs/src/content/docs/examples/index.md b/docs/src/content/docs/examples/index.md
index 04077eda462..38d5f247648 100644
--- a/docs/src/content/docs/examples/index.md
+++ b/docs/src/content/docs/examples/index.md
@@ -21,6 +21,10 @@ GitHub Agentic Workflows (`gh-aw`) examples show how Markdown workflows can run
 | Scheduled maintenance | Review a backlog regularly, select bounded maintenance tasks, and propose controlled changes. | [Automated repository maintenance](/gh-aw/examples/maintaining-repos/) |
 | Security review | Combine deterministic security tools with AI interpretation to report suspicious changes or compliance work. | [Security-related workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-security-compliance/) |
 
+## Examples and AI engines
+
+Most examples specify the default Copilot engine or omit `engine:` entirely, so the published example set is not evenly distributed across engines. Examples are engine-portable: to run one on Claude, Codex, Gemini, or Pi, change `engine:` in the workflow frontmatter and configure that engine's authentication secret. Engine-specific options such as `engine.agent` or `engine.harness` are not portable — see the [engine feature comparison](/gh-aw/reference/engines/#engine-feature-comparison) before switching.
+
 ## Use an example safely
 
 Before enabling an example, review its trigger, AI engine authentication, tools, network access, permissions, and safe outputs. Compile the Markdown source with `gh aw compile`, inspect both the `.md` and generated `.lock.yml` files, and begin with the narrowest permissions and outputs that satisfy the task.
diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
index 8b4b85a28a3..71f4269e9c3 100644
--- a/docs/src/content/docs/reference/engines.md
+++ b/docs/src/content/docs/reference/engines.md
@@ -79,6 +79,9 @@ imports:
 
 Do not treat imported definitions as supported unless their engine owner explicitly supports them. The OpenCode, Aider, Crush, Cursor, and Kiro files listed above remain samples; copy or adapt them only under the maintenance and support terms provided by their respective owners.
 
+> [!NOTE]
+> There is no flat `engine: custom` value. `engine:` in string form only accepts a built-in engine ID (`copilot`, `claude`, `codex`, `gemini`, `pi`); any other value fails compilation. Third-party and self-defined engines always use the nested object form with `engine.id` set to the ID declared by an imported engine definition, as shown above.
+
 ## Extended Coding Agent Configuration
 
 Workflows can specify extended configuration for the coding agent:
diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index 6ec3148f684..40f34479296 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -148,7 +148,7 @@ Commands are organized by workflow lifecycle: creating, building, testing, monit
 
 #### `init`
 
-Initialize repository for agentic workflows. Configures `.gitattributes`, creates the dispatcher skill file (`.github/skills/agentic-workflows/SKILL.md`), and performs non-interactive setup. With the Copilot engine (`--engine copilot`), it also creates the Agentic Workflows custom agent (`.github/agents/agentic-workflows.md`) and enables MCP server integration by default (use `--no-mcp`/`--no-agent` to skip these Copilot-specific artifacts). Use `--no-skill` to skip dispatcher skill creation. Non-Copilot engines skip Copilot-specific artifacts.
+Initialize repository for agentic workflows. Configures `.gitattributes`, creates the dispatcher skill file (`.github/skills/agentic-workflows/SKILL.md`), and performs non-interactive setup. With the Copilot engine (`--engine copilot`), it also creates the Agentic Workflows custom agent (`.github/agents/agentic-workflows.md`) and enables MCP server integration by default (use `--no-mcp`/`--no-agent` to skip these Copilot-specific artifacts). Use `--no-skill` to skip dispatcher skill creation. Non-Copilot engines skip Copilot-specific artifacts; see [Initializing for non-Copilot engines](#initializing-for-non-copilot-engines).
 
 ```bash wrap
 gh aw init                              # Initialize repository with defaults (non-interactive)
@@ -164,6 +164,21 @@ gh aw init --create-pull-request        # Initialize and open a pull request
 
 **Options:** `--engine/-e`, `--no-mcp`, `--no-skill`, `--no-agent`, `--codespaces`, `--completions`, `--create-pull-request`
 
+##### Initializing for non-Copilot engines
+
+With `--engine claude`, `--engine codex`, `--engine gemini`, or `--engine pi`, `init` still performs the engine-independent setup and only skips the Copilot-specific artifacts:
+
+| Artifact | Copilot engine | Other engines | Replacement for other engines |
+|---|:---:|:---:|---|
+| `.gitattributes` entries for compiled `.lock.yml` files | ✅ | ✅ | Not needed — created for every engine |
+| Dispatcher skill `.github/skills/agentic-workflows/SKILL.md` | ✅ | ✅ | Not needed — created for every engine; the instructions are plain Markdown that any agent can be pointed at |
+| Custom agent `.github/agents/agentic-workflows.md` | ✅ | ❌ | Use the dispatcher skill, or author an agent file in your own agent's format (Claude Code subagents, Codex prompts) from the same instructions |
+| MCP wiring: `.github/mcp.json` and `.github/workflows/copilot-setup-steps.yml` | ✅ | ❌ | Register `gh aw mcp-server` in your own MCP host configuration — see [GH-AW as an MCP Server](/gh-aw/reference/gh-aw-as-mcp-server/) |
+
+After `init`, the remaining steps are the same for every engine: pick the engine in workflow frontmatter (`engine: claude`, `engine: codex`, `engine: gemini`, `engine: pi`) and configure that engine's authentication secret. See [AI Engines](/gh-aw/reference/engines/) and [Authentication](/gh-aw/reference/auth/).
+
+The engine chosen at `init` time does not restrict workflows: every workflow selects its own engine in frontmatter, and example workflows written for one engine can be adapted to another by changing `engine:` and its authentication secret.
+
 #### `add-wizard`
 
 Add a workflow with interactive guided setup. Checks requirements, adds the markdown file, and generates the compiled YAML. Prompts for missing API keys and secrets. For remote workflows, this command follows frontmatter [`redirect`](/gh-aw/reference/frontmatter/#redirect-redirect) declarations before installation.