Document top 20 user-facing error messages with solutions and examples

[Copilot]

Out of 328 error messages in the codebase, zero were documented. This adds comprehensive documentation for the 19 most critical user-facing errors.

Changes

Added "Top User-Facing Errors" section to docs/src/content/docs/troubleshooting/errors.md:

• Strict mode errors (5): Network configuration required, write permissions blocked, wildcard restrictions, bash command restrictions, custom MCP server network requirements
• Command trigger conflicts (1): Command trigger incompatibility with explicit event triggers
• MCP configuration errors (4): Missing URL field, type detection failures, container/command conflicts, HTTP/container conflicts
• Time delta errors (5): Stop-time deprecation, invalid format, minute unit restriction, maximum value limits, duplicate units
• Engine support errors (3): HTTP transport compatibility, repository feature requirements, firewall support
• Job errors (1): Empty job name validation

Documentation Pattern

Each error follows the stop-time migration pattern:

### Error Name

**Error Message:**

exact error text

**Cause:** Brief explanation

**Solution:** Actionable fix with incorrect/correct examples

**Example:** Complete working workflow

All 4 exemplary errors from #2969 included:

• cannot use 'command' with 'issues' in the same workflow
• strict mode: 'network' configuration is required
• job name cannot be empty
• http MCP tool '%s' missing required 'url' field

Brings total documented errors from 22 to 41, all searchable via Pagefind.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
  • Triggering command: node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro preview (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[task] Document top 20 error messages in troubleshooting guide</issue_title>
<issue_description>## Objective
Extract and document the top 20 most common error messages from the codebase with solutions and examples.

Context

This addresses Issue #3 from discussion #2969. Out of 328 error messages in the codebase, zero are documented. This task focuses on documenting the most critical ones first.

Approach

1. Search codebase for errors.New and fmt.Errorf patterns
2. Identify the 20 most user-facing error messages based on:
   • Frequency of occurrence in code
   • Likelihood of user encountering them
   • Complexity requiring explanation
3. For each error, document in docs/src/content/docs/troubleshooting/errors.md:
   • Error message text
   • What causes it
   • How to fix it
   • Working example (follow stop-time migration pattern)
4. Include the exemplary errors mentioned in discussion [Schema Consistency] 🔍 Schema Consistency Check - Required Fields & Error Documentation Gap (Nov 2, 2025) #2969:
   • "cannot use 'command' with 'issues' in the same workflow"
   • "strict mode: 'network' configuration is required"
   • "job name cannot be empty"
   • "http MCP tool '%s' missing required 'url' field"

Files to Modify

• docs/src/content/docs/troubleshooting/errors.md - Add top 20 error messages

Gold Standard Example

Follow the stop-time deprecation error pattern from compiler.go:

• Clear explanation
• Migration path
• Working code example
• Preserves user's value

Acceptance Criteria

• 20 error messages documented with cause and solution
• Each error includes a code example
• Errors are searchable in documentation
• Documentation follows the stop-time migration pattern
• Documentation builds successfully
  Related to [Schema Consistency] 🔍 Schema Consistency Check - Required Fields & Error Documentation Gap (Nov 2, 2025) #2969

AI generated by Plan Command for discussion #2969</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [task] Document top 20 error messages in troubleshooting guide #2974

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull Request Overview

This PR adds documentation for the forks: security feature for pull request triggers in GitHub Agentic Workflows. The feature provides a secure-by-default approach where workflows block all fork PRs unless explicitly configured.

• Documents the new forks: field for pull_request triggers with allowlist patterns
• Adds comprehensive error documentation section covering common user-facing errors
• Includes security guidance emphasizing fork blocking as the default behavior

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
pkg/cli/templates/github-agentic-workflows.instructions.md	Documents the forks: field in frontmatter schema, trigger examples, and security considerations section
docs/src/content/docs/troubleshooting/errors.md	Adds extensive "Top User-Facing Errors" section with detailed error messages, causes, and solutions; expands troubleshooting tips and help sections

---

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

[Copilot]

The forks: field documentation is placed under the on: section but appears at the same indentation level as stop-after:. However, forks: is specific to pull_request triggers (not a general on: property like stop-after:). Consider clarifying this relationship or restructuring to show it's a sub-field of pull_request triggers specifically.

Suggested change

	- **`forks:`** - Fork allowlist for `pull_request` triggers (array or string). By default, workflows block all forks and only allow same-repo PRs. Use `["*"]` to allow all forks, or specify patterns like `["org/*", "user/repo"]`
	- **`pull_request:`** - Configuration for pull request triggers
	- **`forks:`** - Fork allowlist for `pull_request` triggers (array or string). By default, workflows block all forks and only allow same-repo PRs. Use `["*"]` to allow all forks, or specify patterns like `["org/*", "user/repo"]`

[Copilot]

The engine name should be 'Claude' (capitalized) for consistency with 'Copilot', but 'Codex' appears to be a reference to OpenAI Codex which has been deprecated since March 2023. Verify if 'Codex' is the correct engine name for this system or if it should be updated to a current engine name.

Suggested change

- ❌ Codex: stdio only