Clarify Copilot agent assignment methods in documentation

docs/src/content/docs/agent-factory-status.mdx

@@ -112,7 +112,6 @@ These are experimental agentic workflows used by the GitHub Next team to learn,
 | [Safe Output Health Monitor](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/safe-output-health.md) | claude | [![Safe Output Health Monitor](https://github.com/githubnext/gh-aw/actions/workflows/safe-output-health.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/safe-output-health.lock.yml) | - | - |
 | [Schema Consistency Checker](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/schema-consistency-checker.md) | claude | [![Schema Consistency Checker](https://github.com/githubnext/gh-aw/actions/workflows/schema-consistency-checker.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/schema-consistency-checker.lock.yml) | - | - |
 | [Scout](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/scout.md) | claude | [![Scout](https://github.com/githubnext/gh-aw/actions/workflows/scout.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/scout.lock.yml) | - | `/scout` |
-| [Security Alert Burndown](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-alert-burndown.campaign.md) | copilot | [![Security Alert Burndown](https://github.com/githubnext/gh-aw/actions/workflows/security-alert-burndown.campaign.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-alert-burndown.campaign.lock.yml) | - | - |
 | [Security Compliance Campaign](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-compliance.md) | copilot | [![Security Compliance Campaign](https://github.com/githubnext/gh-aw/actions/workflows/security-compliance.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-compliance.lock.yml) | - | - |
 | [Security Fix PR](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-fix-pr.md) | copilot | [![Security Fix PR](https://github.com/githubnext/gh-aw/actions/workflows/security-fix-pr.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-fix-pr.lock.yml) | - | - |
 | [Security Review Agent 🔒](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-review.md) | copilot | [![Security Review Agent 🔒](https://github.com/githubnext/gh-aw/actions/workflows/security-review.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-review.lock.yml) | - | `/security` |
@@ -122,12 +121,14 @@ These are experimental agentic workflows used by the GitHub Next team to learn,
 | [Smoke Claude](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-claude.md) | claude | [![Smoke Claude](https://github.com/githubnext/gh-aw/actions/workflows/smoke-claude.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-claude.lock.yml) | - | - |
 | [Smoke Codex](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-codex.md) | codex | [![Smoke Codex](https://github.com/githubnext/gh-aw/actions/workflows/smoke-codex.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-codex.lock.yml) | - | - |
 | [Smoke Copilot](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-copilot.md) | copilot | [![Smoke Copilot](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot.lock.yml) | - | - |
+| [Smoke OpenCode](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-opencode.md) | copilot | [![Smoke OpenCode](https://github.com/githubnext/gh-aw/actions/workflows/smoke-opencode.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-opencode.lock.yml) | - | - |
 | [Stale Repository Identifier](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/stale-repo-identifier.md) | copilot | [![Stale Repository Identifier](https://github.com/githubnext/gh-aw/actions/workflows/stale-repo-identifier.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/stale-repo-identifier.lock.yml) | - | - |
 | [Static Analysis Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/static-analysis-report.md) | claude | [![Static Analysis Report](https://github.com/githubnext/gh-aw/actions/workflows/static-analysis-report.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/static-analysis-report.lock.yml) | - | - |
 | [Step Name Alignment](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/step-name-alignment.md) | claude | [![Step Name Alignment](https://github.com/githubnext/gh-aw/actions/workflows/step-name-alignment.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/step-name-alignment.lock.yml) | `daily` | - |
 | [Sub-Issue Closer](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/sub-issue-closer.md) | copilot | [![Sub-Issue Closer](https://github.com/githubnext/gh-aw/actions/workflows/sub-issue-closer.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/sub-issue-closer.lock.yml) | - | - |
 | [Super Linter Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/super-linter.md) | copilot | [![Super Linter Report](https://github.com/githubnext/gh-aw/actions/workflows/super-linter.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/super-linter.lock.yml) | `0 14 * * 1-5` | - |
 | [Terminal Stylist](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/terminal-stylist.md) | copilot | [![Terminal Stylist](https://github.com/githubnext/gh-aw/actions/workflows/terminal-stylist.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/terminal-stylist.lock.yml) | - | - |
+| [Test Create PR Error Handling](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/test-create-pr-error-handling.md) | claude | [![Test Create PR Error Handling](https://github.com/githubnext/gh-aw/actions/workflows/test-create-pr-error-handling.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/test-create-pr-error-handling.lock.yml) | - | - |
 | [The Daily Repository Chronicle](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/daily-repo-chronicle.md) | copilot | [![The Daily Repository Chronicle](https://github.com/githubnext/gh-aw/actions/workflows/daily-repo-chronicle.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/daily-repo-chronicle.lock.yml) | `0 16 * * 1-5` | - |
 | [The Great Escapi](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/firewall-escape.md) | copilot | [![The Great Escapi](https://github.com/githubnext/gh-aw/actions/workflows/firewall-escape.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/firewall-escape.lock.yml) | - | - |
 | [Tidy](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/tidy.md) | copilot | [![Tidy](https://github.com/githubnext/gh-aw/actions/workflows/tidy.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/tidy.lock.yml) | `0 7 * * *` | - |

docs/src/content/docs/blog/2026-01-27-operational-patterns.md

@@ -318,7 +318,7 @@ The [`duplicate-code-detector`](https://github.com/githubnext/gh-aw/tree/2c1f68a
 
 **Research**: Uses Serena MCP for semantic analysis, creates report
 **Plan**: Creates well-scoped issues (max 3 per run) with refactoring strategies
-**Assign**: Pre-assigns to `@copilot` since fixes are straightforward
+**Assign**: Creates issues and [assigns to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) (via `assignees: copilot`) since fixes are straightforward
 
 The key benefits are:
 

docs/src/content/docs/guides/researchplanassign.md

@@ -19,7 +19,7 @@ The developer reviews the research report to determine if worthwhile improvement
 
 ### Phase 3: Assign
 
-The developer reviews the generated issues and decides which ones to execute. Approved issues are assigned to `@copilot` for automated implementation and can be executed sequentially or in parallel depending on dependencies. Each copilot agent creates a pull request with the implementation for developer review and merging.
+The developer reviews the generated issues and decides which ones to execute. Approved issues are [assigned to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) for automated implementation and can be executed sequentially or in parallel depending on dependencies. Copilot creates a pull request with the implementation for developer review and merging.
 
 ## When to Use ResearchPlanAssign
 
@@ -37,17 +37,17 @@ Runs daily to scan all agentic workflows with security tools (zizmor, poutine, a
 
 **Plan Phase**: Developer reviews the security discussion and uses the `/plan` command to convert high-priority findings into issues.
 
-**Assign Phase**: Developer assigns generated issues to `@copilot` for automated fixes.
+**Assign Phase**: Developer [assigns generated issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) for automated fixes.
 
 ### Duplicate Code Detection → Plan → Refactor
 
 **Research Phase**: [`duplicate-code-detector.md`](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/duplicate-code-detector.md)
 
-Runs daily using Serena MCP for semantic code analysis to identify exact, structural, and functional duplication. Creates one issue per distinct pattern (max 3 per run) and assigns directly to `@copilot` since duplication fixes are typically straightforward.
+Runs daily using Serena MCP for semantic code analysis to identify exact, structural, and functional duplication. Creates one issue per distinct pattern (max 3 per run) that are [assigned to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) (via `assignees: copilot` in workflow config) since duplication fixes are typically straightforward.
 
 **Plan Phase**: Since issues are already well-scoped, the plan phase is implicit in the research output.
 
-**Assign Phase**: Issues are pre-assigned to `@copilot` for automated refactoring.
+**Assign Phase**: Issues are created and [assigned to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) (via `assignees: copilot`) for automated refactoring.
 
 ### File Size Analysis → Plan → Refactor
 
@@ -57,7 +57,7 @@ Runs weekdays to monitor file sizes, identify files exceeding healthy size thres
 
 **Plan Phase**: The research issue already contains a concrete refactoring plan.
 
-**Assign Phase**: Developer reviews and assigns to `@copilot` or handles manually depending on complexity.
+**Assign Phase**: Developer reviews and [assigns to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) or handles manually depending on complexity.
 
 ### Deep Research → Plan → Implementation
 
@@ -79,7 +79,7 @@ Performs deep research investigations using multiple research MCPs (Tavily, arXi
 
 ## Customization
 
-Adapt the ResearchPlanAssign strategy by customizing the research focus (static analysis, performance metrics, documentation quality, security, code duplication, test coverage), frequency (daily, weekly, on-demand), report format (discussions vs issues), planning approach (automatic vs manual), and assignment method (pre-assign to `@copilot`, manual, or mixed).
+Adapt the ResearchPlanAssign strategy by customizing the research focus (static analysis, performance metrics, documentation quality, security, code duplication, test coverage), frequency (daily, weekly, on-demand), report format (discussions vs issues), planning approach (automatic vs manual), and assignment method (pre-assign via `assignees: copilot` in workflow config, [manual assignment through GitHub UI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot), or mixed).
 
 ## Benefits
 

docs/src/content/docs/reference/safe-outputs.md

@@ -779,7 +779,7 @@ Creates Copilot agent sessions. Requires `COPILOT_GITHUB_TOKEN` or `GH_AW_GITHUB
 
 ### Assign to Agent (`assign-to-agent:`)
 
-Assigns Copilot coding agent to issues or pull requests. Requires fine-grained PAT with actions, contents, issues, pull requests write access stored as `GH_AW_AGENT_TOKEN`, or GitHub App token. Supported agents: `copilot` (`copilot-swe-agent`).
+Programmatically assigns GitHub Copilot agents to **existing** issues or pull requests through workflow automation. This safe output automates the [standard GitHub workflow for assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot). Requires fine-grained PAT with actions, contents, issues, pull requests write access stored as `GH_AW_AGENT_TOKEN`, or GitHub App token. Supported agents: `copilot` (`copilot-swe-agent`).
 
 Auto-resolves target from workflow context (issue/PR events) when `issue_number` or `pull_number` not explicitly provided. Restrict with `allowed` list. Target: `"triggering"` (default), `"*"` (any), or number.
 
@@ -801,6 +801,21 @@ safe-outputs:
 **Assignee Filtering:**
 When `allowed` list is configured, existing agent assignees not in the list are removed while regular user assignees are preserved.
 
+> [!TIP]
+> Assignment methods
+> 
+> Use `assign-to-agent` when you need to programmatically assign agents to **existing** issues or PRs through workflow automation. If you're creating new issues and want to assign an agent immediately, use `assignees: copilot` in your [`create-issue`](#issue-creation-create-issue) configuration instead, which is simpler:
+> 
+> ```yaml
+> safe-outputs:
+>   create-issue:
+>     assignees: copilot  # Assigns agent when creating issue
+> ```
+> 
+> **Important**: Both methods use the **same token** (`GH_AW_AGENT_TOKEN`) and **same GraphQL API** (`replaceActorsForAssignable` mutation) to assign copilot. When you use `assignees: copilot` in create-issue, the copilot assignee is automatically filtered out and assigned in a separate post-step using the agent token and GraphQL, identical to the `assign-to-agent` safe output.
+> 
+> Both methods result in the same outcome as [manually assigning issues to Copilot through the GitHub UI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot). See [GitHub Tokens reference](/gh-aw/reference/tokens/#gh_aw_agent_token-agent-assignment) for token configuration details and [GitHub's official Copilot coding agent documentation](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) for more about the Copilot agent.
+
 ### Assign to User (`assign-to-user:`)
 
 Assigns users to issues. Restrict with `allowed` list. Target: `"triggering"` (issue event), `"*"` (any), or number. Supports single or multiple assignees.
@@ -900,7 +915,7 @@ safe-outputs:
 
 ## Assigning to Copilot
 
-Use `assignees: copilot` or `reviewers: copilot` for bot assignment. Requires `COPILOT_GITHUB_TOKEN` or `GH_AW_GITHUB_TOKEN` PAT—default `GITHUB_TOKEN` lacks permissions.
+Use `assignees: copilot` or `reviewers: copilot` for bot assignment. Requires `GH_AW_AGENT_TOKEN` (or fallback to `GH_AW_GITHUB_TOKEN`/`GITHUB_TOKEN`)—uses GraphQL API to assign the bot.
 
 ## Custom Runner Image
 

docs/src/content/docs/reference/tokens.md

@@ -314,7 +314,7 @@ gh aw secrets set COPILOT_GITHUB_TOKEN --value "YOUR_COPILOT_PAT"
 
 **Type**: Personal Access Token (user must configure)
 
-Specialized token for `assign-to-agent:` safe outputs that assign GitHub Copilot agents to issues or pull requests.
+Specialized token for `assign-to-agent:` safe outputs that programmatically assign GitHub Copilot agents to issues or pull requests. This is distinct from the standard GitHub UI workflow for [assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot)—this token is used for automated agent assignment through workflow safe outputs.
 
 **Required for**:
 
@@ -358,6 +358,34 @@ gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT"
 
 **Token precedence**: per-output → global safe-outputs → workflow-level → `GH_AW_AGENT_TOKEN` (no further fallback - must be explicitly configured)
 
+> [!NOTE]
+> Two ways to assign Copilot agents
+> 
+> There are two different methods for assigning GitHub Copilot agents to issues or pull requests. **Both methods use the same token (`GH_AW_AGENT_TOKEN`) and GraphQL API** to perform the assignment:
+> 
+> 1. **Via `assign-to-agent` safe output**: Use when you need to programmatically assign agents to **existing** issues or PRs through workflow automation. This is a standalone operation that requires the token documented on this page.
+> 
+>    ```yaml
+>    safe-outputs:
+>      assign-to-agent:
+>        name: "copilot"
+>        allowed: [copilot]
+>    ```
+> 
+> 2. **Via `assignees` field in `create-issue`**: Use when creating new issues through workflows and want to assign the agent immediately. When `copilot` is in the assignees list, it's automatically filtered out and assigned via GraphQL in a separate step after issue creation (using the same token and API as method 1).
+> 
+>    ```yaml
+>    safe-outputs:
+>      create-issue:
+>        assignees: copilot  # or assignees: [copilot, user1]
+>    ```
+> 
+> Both methods result in the same outcome as [manually assigning issues to Copilot through the GitHub UI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot). Method 2 is simpler when creating issues, while method 1 provides fine-grained control for existing issues.
+> 
+> **Technical Implementation**: Both methods use the GraphQL `replaceActorsForAssignable` mutation to assign the `copilot-swe-agent` bot to issues or PRs. The token precedence for both is: per-output → global safe-outputs → workflow-level → `GH_AW_AGENT_TOKEN` (with fallback to `GH_AW_GITHUB_TOKEN` or `GITHUB_TOKEN` if not set).
+> 
+> See [GitHub's official documentation on assigning issues to Copilot](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) for more details on the Copilot coding agent.
+
 > [!NOTE]
 > Resource owner requirements
 > The token's resource owner must match the repository ownership: