Add troubleshooting documentation structure

[Copilot]

The codebase contains 328+ error messages but zero documentation for them, forcing users to file issues instead of self-serving.

Changes

Documentation Structure

• Created docs/src/content/docs/troubleshooting/ directory
• Added "Troubleshooting" section to sidebar navigation

Three Reference Documents

errors.md - Error messages organized by lifecycle stage:

• Schema validation (YAML syntax, field types, imports)
• Compilation (file resolution, agent files, expressions)
• Runtime (time deltas, authentication, environment)
• Safe outputs (MCP configuration)

Each entry includes error message, cause, solution, and code examples.

common-issues.md - Frequently encountered issues by component:

• Workflow compilation (lock files, orphaned files)
• Import resolution (paths, circular dependencies)
• Tool configuration (GitHub, MCP, Playwright)
• Permissions (tokens, safe outputs)
• Engine-specific (CLI, timeouts, models)
• Debugging strategies (verbose logging, inspection)

validation-timing.md - When validation occurs:

• Schema validation (compile-time frontmatter checks)
• Compilation validation (file resolution, workflow generation)
• Runtime validation (GitHub Actions execution)
• ASCII flow diagram of validation pipeline
• Stage-specific debugging approaches

Screenshots

Error Reference

Validation Timing with Flow Diagram

Closes #3

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 dev (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] Create troubleshooting documentation structure</issue_title>
<issue_description>## Objective
Create the docs/src/content/docs/troubleshooting/ directory structure with foundational troubleshooting documentation files.

Context

This addresses Issue #3 from discussion #2969. The codebase contains 328 error messages but has zero documentation for them. Users encountering errors cannot search documentation for solutions or understand error context.

Approach

1. Create directory: docs/src/content/docs/troubleshooting/
2. Create three foundational files:
   • errors.md - Common error messages and solutions
   • common-issues.md - Frequently encountered issues
   • validation-timing.md - When errors occur (schema vs compile vs runtime)
3. Follow Astro Starlight format with proper frontmatter
4. Use Diátaxis framework (this is reference documentation)

Files to Create

• docs/src/content/docs/troubleshooting/errors.md
• docs/src/content/docs/troubleshooting/common-issues.md
• docs/src/content/docs/troubleshooting/validation-timing.md

Structure for errors.md

Include sections for:

• Schema validation errors
• Compile-time errors
• Runtime errors
• Each error should include: description, cause, solution, example

Acceptance Criteria

• Directory docs/src/content/docs/troubleshooting/ exists
• All three markdown files created with proper frontmatter
• Files follow Astro Starlight and Diátaxis guidelines
• Navigation updated to include troubleshooting section
• Documentation builds successfully with npm run build
  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] Create troubleshooting documentation structure #2973

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull Request Overview

This PR adds comprehensive troubleshooting documentation to the GitHub Agentic Workflows project, providing users with detailed guidance on validation stages, error messages, and common issues they may encounter.

• Introduces three new documentation files covering validation timing, error reference, and common issues
• Adds a "Troubleshooting" section to the documentation navigation

Reviewed Changes

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

File	Description
docs/src/content/docs/troubleshooting/validation-timing.md	Documents the three validation stages (schema, compilation, runtime) with examples, timing, and best practices
docs/src/content/docs/troubleshooting/errors.md	Comprehensive error reference organized by lifecycle stage with causes and solutions
docs/src/content/docs/troubleshooting/common-issues.md	Frequently encountered issues organized by workflow component with debugging strategies
docs/astro.config.mjs	Adds troubleshooting section to documentation sidebar navigation

---

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