diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 3b1c27f94f..cdd7db7834 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -80,6 +80,10 @@ export default defineConfig({
 					label: 'Tools',
 					autogenerate: { directory: 'tools' },
 				},
+				{
+					label: 'Troubleshooting',
+					autogenerate: { directory: 'troubleshooting' },
+				},
 				// ...makeChangelogsSidebarLinks([
 				// 	{ type: 'all', base: 'changelog', label: 'Changelog' }
 				// ]),
diff --git a/docs/src/content/docs/troubleshooting/common-issues.md b/docs/src/content/docs/troubleshooting/common-issues.md
new file mode 100644
index 0000000000..131fec3796
--- /dev/null
+++ b/docs/src/content/docs/troubleshooting/common-issues.md
@@ -0,0 +1,529 @@
+---
+title: Common Issues
+description: Frequently encountered issues when working with GitHub Agentic Workflows and their solutions.
+sidebar:
+  order: 200
+---
+
+This reference documents frequently encountered issues when working with GitHub Agentic Workflows, organized by workflow stage and component.
+
+## Workflow Compilation Issues
+
+### Workflow Won't Compile
+
+**Symptoms:** Running `gh aw compile` fails with errors.
+
+**Common Causes:**
+
+1. **YAML syntax errors in frontmatter**
+   - Check indentation (use spaces, not tabs)
+   - Verify colons have spaces after them
+   - Ensure arrays use proper `[item1, item2]` or list syntax
+
+2. **Missing required fields**
+   - The `on:` trigger is required
+   - Verify all required fields for your chosen trigger type
+
+3. **Invalid field values**
+   - Check field types match schema (strings, integers, booleans)
+   - Verify enum values are correct (e.g., `engine: copilot`)
+
+**Solution:**
+```bash
+# Compile with verbose output to see detailed errors
+gh aw compile --verbose
+
+# Validate YAML syntax separately
+cat .github/workflows/my-workflow.md | head -20 | grep -A 20 "^---"
+```
+
+### Lock File Not Generated
+
+**Symptoms:** The `.lock.yml` file is not created after compilation.
+
+**Common Causes:**
+
+1. **Compilation errors prevent generation**
+   - Review compilation output for errors
+   - Fix all schema validation errors first
+
+2. **File permissions**
+   - Ensure write permissions on `.github/workflows/` directory
+
+**Solution:**
+```bash
+# Check for compilation errors
+gh aw compile 2>&1 | grep -i error
+
+# Verify directory permissions
+ls -la .github/workflows/
+```
+
+### Orphaned Lock Files
+
+**Symptoms:** Old `.lock.yml` files remain after deleting `.md` files.
+
+**Solution:**
+```bash
+# Remove orphaned lock files
+gh aw compile --purge
+```
+
+## Import and Include Issues
+
+### Import File Not Found
+
+**Symptoms:** Error message about failed import resolution.
+
+**Common Causes:**
+
+1. **Incorrect path**
+   - Import paths are relative to repository root
+   - Verify the file exists at the specified location
+
+2. **File not committed**
+   - Imported files must be committed to the repository
+   - Check `git status` for untracked files
+
+**Solution:**
+```yaml
+# Use correct import paths
+imports:
+  - .github/workflows/shared/tools.md  # From repo root
+  - shared/security-notice.md          # Relative to .github/workflows/
+```
+
+### Multiple Agent Files Error
+
+**Symptoms:** Error about multiple agent files in imports.
+
+**Cause:** More than one file under `.github/agents/` is imported.
+
+**Solution:** Import only one agent file per workflow:
+
+```yaml
+# Incorrect
+imports:
+  - .github/agents/agent1.md
+  - .github/agents/agent2.md
+  - shared/tools.md
+
+# Correct
+imports:
+  - .github/agents/agent1.md
+  - shared/tools.md
+```
+
+### Circular Import Dependencies
+
+**Symptoms:** Compilation hangs or fails with stack overflow.
+
+**Cause:** Import files import each other, creating a circular dependency.
+
+**Solution:** Review import chains and remove circular references:
+
+```yaml
+# File A imports File B
+# File B imports File A  ← Remove this circular dependency
+```
+
+## Tool Configuration Issues
+
+### GitHub Tools Not Available
+
+**Symptoms:** Workflow cannot use GitHub API tools.
+
+**Common Causes:**
+
+1. **Tools not configured**
+   - GitHub tools require explicit configuration
+   - Check the `tools:` section in frontmatter
+
+2. **Incorrect tool names**
+   - Verify tool names match the allowed list
+   - See [tools reference](/gh-aw/reference/tools/)
+
+**Solution:**
+```yaml
+tools:
+  github:
+    allowed:
+      - get_repository
+      - list_issues
+      - create_issue_comment
+```
+
+### MCP Server Connection Failures
+
+**Symptoms:** Workflow fails to connect to MCP servers.
+
+**Common Causes:**
+
+1. **Server not installed**
+   - Verify MCP server package is available
+   - Check Docker container is accessible
+
+2. **Configuration errors**
+   - Validate MCP server configuration syntax
+   - Ensure required environment variables are set
+
+**Solution:**
+```yaml
+mcp-servers:
+  my-server:
+    command: "npx"
+    args: ["@myorg/mcp-server"]
+    env:
+      API_KEY: "${{ secrets.MCP_API_KEY }}"
+```
+
+### Playwright Network Access Denied
+
+**Symptoms:** Playwright tools fail with network errors.
+
+**Cause:** Domain is not in the allowed list.
+
+**Solution:** Add domains to `allowed_domains`:
+
+```yaml
+tools:
+  playwright:
+    allowed_domains:
+      - "github.com"
+      - "*.github.io"
+```
+
+## Permission Issues
+
+### Write Operations Fail
+
+**Symptoms:** Cannot create issues, comments, or pull requests.
+
+**Common Causes:**
+
+1. **Missing permissions**
+   - Check the `permissions:` section
+   - Verify required permissions are granted
+
+2. **Read-only token**
+   - The workflow might be using a read-only token
+   - Check token configuration
+
+**Solution:**
+```yaml
+# For direct write operations
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+# Or use safe-outputs (recommended)
+permissions:
+  contents: read
+safe-outputs:
+  create-issue:
+  add-comment:
+```
+
+### Safe Outputs Not Creating Issues
+
+**Symptoms:** Workflow completes but no issues are created.
+
+**Common Causes:**
+
+1. **Safe outputs not configured correctly**
+   - Verify `safe-outputs:` syntax
+   - Check the workflow output format
+
+2. **Staged mode enabled**
+   - Safe outputs in staged mode only preview
+   - Set `staged: false` for actual creation
+
+**Solution:**
+```yaml
+safe-outputs:
+  staged: false  # Ensure not in preview mode
+  create-issue:
+    title-prefix: "[bot] "
+    labels: [automation]
+```
+
+### Token Permission Errors
+
+**Symptoms:** "Resource not accessible by integration" errors.
+
+**Cause:** The `GITHUB_TOKEN` lacks required permissions.
+
+**Solution:** Add permissions to the workflow or use a Personal Access Token:
+
+```yaml
+# Increase GITHUB_TOKEN permissions
+permissions:
+  contents: write
+  issues: write
+
+# Or use custom token
+safe-outputs:
+  github-token: ${{ secrets.CUSTOM_PAT }}
+  create-issue:
+```
+
+## Engine-Specific Issues
+
+### Copilot CLI Not Found
+
+**Symptoms:** "copilot: command not found" in workflow logs.
+
+**Cause:** The Copilot CLI is not installed or not in PATH.
+
+**Solution:** Ensure the Copilot CLI installation step is included in the workflow. This is typically handled automatically by the compiled workflow.
+
+### Claude Engine Timeout
+
+**Symptoms:** Workflow times out before completing.
+
+**Cause:** Task is too complex or `max-turns` is set too high.
+
+**Solution:** Reduce scope or adjust timeout:
+
+```yaml
+timeout_minutes: 30
+engine:
+  id: claude
+  max-turns: 5  # Reduce if timing out
+```
+
+### Model Not Available
+
+**Symptoms:** "Model not found" or similar errors.
+
+**Cause:** Specified model is not available for the engine.
+
+**Solution:** Use default model or verify model availability:
+
+```yaml
+# Let engine use default model
+engine: copilot
+
+# Or specify available model
+engine:
+  id: copilot
+  model: gpt-4
+```
+
+## Context Expression Issues
+
+### Unauthorized Expression
+
+**Symptoms:** Compilation fails with "unauthorized expression" error.
+
+**Cause:** Using a GitHub Actions expression that is not in the allowed list.
+
+**Solution:** Use only [allowed expressions](/gh-aw/reference/templating/):
+
+```yaml
+# Allowed
+${{ github.event.issue.number }}
+${{ github.repository }}
+${{ needs.activation.outputs.text }}
+
+# Not allowed
+${{ secrets.GITHUB_TOKEN }}
+${{ env.MY_VAR }}
+```
+
+### Sanitized Context Empty
+
+**Symptoms:** `needs.activation.outputs.text` is empty.
+
+**Cause:** Workflow was not triggered by an issue, PR, or comment event.
+
+**Solution:** The sanitized context is only populated for specific events:
+
+```yaml
+on:
+  issues:
+    types: [opened]  # Populates sanitized context
+  push:              # Does not populate sanitized context
+```
+
+## Build and Test Issues
+
+### Documentation Build Fails
+
+**Symptoms:** `npm run build` fails in the `docs/` directory.
+
+**Common Causes:**
+
+1. **Dependencies not installed**
+   ```bash
+   cd docs && npm install
+   ```
+
+2. **Syntax errors in markdown**
+   - Check for malformed frontmatter
+   - Verify MDX syntax is valid
+
+3. **Broken links**
+   - Fix internal link paths
+   - Ensure referenced files exist
+
+**Solution:**
+```bash
+# Clean install
+cd docs
+rm -rf node_modules package-lock.json
+npm install
+npm run build
+```
+
+### Tests Failing After Changes
+
+**Symptoms:** `make test` or `make test-unit` fails.
+
+**Common Causes:**
+
+1. **Go code syntax errors**
+   - Run `make fmt` to format code
+   - Run `make lint` to check for issues
+
+2. **Test expectations outdated**
+   - Review test failures and update expectations
+   - Ensure changes maintain backward compatibility
+
+**Solution:**
+```bash
+# Format and lint
+make fmt
+make lint
+
+# Run tests
+make test-unit
+```
+
+## Network and Connectivity Issues
+
+### Cannot Download Remote Imports
+
+**Symptoms:** Error downloading workflow from remote repository.
+
+**Cause:** Network connectivity or authentication issues.
+
+**Solution:**
+```bash
+# Verify network access
+curl -I https://raw.githubusercontent.com/githubnext/gh-aw/main/README.md
+
+# Check GitHub authentication
+gh auth status
+```
+
+### MCP Server Connection Timeout
+
+**Symptoms:** Timeout when connecting to HTTP MCP servers.
+
+**Cause:** Server is not responding or network is blocked.
+
+**Solution:**
+```yaml
+# Use local MCP server instead of HTTP
+mcp-servers:
+  my-server:
+    type: local  # Change from http
+    command: "node"
+    args: ["./server.js"]
+```
+
+## Cache Issues
+
+### Cache Not Restoring
+
+**Symptoms:** Cache is not restored between workflow runs.
+
+**Common Causes:**
+
+1. **Cache key changed**
+   - Verify cache key pattern matches
+   - Check if dependencies changed
+
+2. **Cache expired**
+   - GitHub Actions caches expire after 7 days
+   - Rebuild cache if expired
+
+**Solution:**
+```yaml
+cache:
+  key: deps-${{ hashFiles('package-lock.json') }}
+  restore-keys: |
+    deps-  # Fallback pattern
+```
+
+### Cache Memory Not Persisting
+
+**Symptoms:** Memory MCP server loses data between runs.
+
+**Cause:** Cache configuration is incorrect or cache is not being saved.
+
+**Solution:**
+```yaml
+tools:
+  cache-memory:
+    key: memory-${{ github.workflow }}-${{ github.run_id }}
+```
+
+## Debugging Strategies
+
+### Enable Verbose Logging
+
+```bash
+# Compile with verbose output
+gh aw compile --verbose
+
+# Run workflow with debug logging
+# (Set repository secret ACTIONS_STEP_DEBUG = true)
+```
+
+### Inspect Generated Workflow
+
+```bash
+# View the generated lock file
+cat .github/workflows/my-workflow.lock.yml
+
+# Compare with source
+diff <(cat .github/workflows/my-workflow.md) \
+     <(cat .github/workflows/my-workflow.lock.yml)
+```
+
+### Check MCP Configuration
+
+```bash
+# Inspect MCP servers in workflow
+gh aw mcp inspect my-workflow
+
+# List tools available
+gh aw mcp list-tools github my-workflow
+```
+
+### Review Workflow Logs
+
+```bash
+# Download logs for analysis
+gh aw logs my-workflow
+
+# Audit specific run
+gh aw audit RUN_ID
+```
+
+## Getting Help
+
+If the issue persists after trying these solutions:
+
+1. **Check documentation:** Review [reference docs](/gh-aw/reference/workflow-structure/) for detailed configuration options
+2. **Search issues:** Look for similar issues in the [GitHub repository](https://github.com/githubnext/gh-aw/issues)
+3. **Enable debugging:** Use verbose flags and review logs carefully
+4. **Report bugs:** Create an issue with reproduction steps and error messages
+
+For more information, see:
+- [Error Reference](/gh-aw/troubleshooting/errors/)
+- [Validation Timing](/gh-aw/troubleshooting/validation-timing/)
+- [Frontmatter Reference](/gh-aw/reference/frontmatter/)
diff --git a/docs/src/content/docs/troubleshooting/errors.md b/docs/src/content/docs/troubleshooting/errors.md
new file mode 100644
index 0000000000..e7c74b8409
--- /dev/null
+++ b/docs/src/content/docs/troubleshooting/errors.md
@@ -0,0 +1,467 @@
+---
+title: Error Reference
+description: Comprehensive reference of error messages in GitHub Agentic Workflows, including schema validation, compilation, and runtime errors with solutions.
+sidebar:
+  order: 100
+---
+
+This reference documents common error messages encountered when working with GitHub Agentic Workflows, organized by when they occur during the workflow lifecycle.
+
+## Schema Validation Errors
+
+Schema validation errors occur when the workflow frontmatter does not conform to the expected JSON schema. These errors are detected during the compilation process.
+
+### Frontmatter Not Properly Closed
+
+**Error Message:**
+```
+frontmatter not properly closed
+```
+
+**Cause:** The YAML frontmatter section lacks a closing `---` delimiter, or the delimiters are malformed.
+
+**Solution:** Ensure the frontmatter is enclosed between two `---` lines:
+
+```aw
+---
+on: push
+permissions:
+  contents: read
+---
+
+# Workflow content
+```
+
+**Related:** Frontmatter must start with `---` on the first line and end with `---` before the markdown content begins.
+
+### Failed to Parse Frontmatter
+
+**Error Message:**
+```
+failed to parse frontmatter: [yaml error details]
+```
+
+**Cause:** The YAML syntax in the frontmatter is invalid. Common issues include incorrect indentation, missing colons, or invalid characters.
+
+**Solution:** Validate the YAML syntax. Common fixes include:
+
+- Check indentation (use spaces, not tabs)
+- Ensure colons are followed by spaces
+- Quote strings containing special characters
+- Verify array and object syntax
+
+```yaml
+# Incorrect
+on:
+issues:
+  types:[opened]
+
+# Correct
+on:
+  issues:
+    types: [opened]
+```
+
+### Invalid Field Type
+
+**Error Message:**
+```
+timeout_minutes must be an integer
+```
+
+**Cause:** A field received a value of the wrong type according to the schema.
+
+**Solution:** Provide the correct type as specified in the [frontmatter reference](/gh-aw/reference/frontmatter/):
+
+```yaml
+# Incorrect
+timeout_minutes: "10"
+
+# Correct
+timeout_minutes: 10
+```
+
+### Imports Field Must Be Array
+
+**Error Message:**
+```
+imports field must be an array of strings
+```
+
+**Cause:** The `imports:` field was provided but is not an array of string paths.
+
+**Solution:** Provide an array of import paths:
+
+```yaml
+# Incorrect
+imports: shared/tools.md
+
+# Correct
+imports:
+  - shared/tools.md
+  - shared/security.md
+```
+
+### Multiple Agent Files in Imports
+
+**Error Message:**
+```
+multiple agent files found in imports: 'file1.md' and 'file2.md'. Only one agent file is allowed per workflow
+```
+
+**Cause:** More than one file under `.github/agents/` was included in the imports list.
+
+**Solution:** Import only one agent file per workflow:
+
+```yaml
+# Incorrect
+imports:
+  - .github/agents/agent1.md
+  - .github/agents/agent2.md
+
+# Correct
+imports:
+  - .github/agents/agent1.md
+```
+
+## Compilation Errors
+
+Compilation errors occur when the workflow file is being converted to a GitHub Actions YAML workflow (`.lock.yml` file).
+
+### Workflow File Not Found
+
+**Error Message:**
+```
+workflow file not found: [path]
+```
+
+**Cause:** The specified workflow file does not exist at the given path.
+
+**Solution:** Verify the file exists in `.github/workflows/` and the filename is correct. Use `gh aw compile` without arguments to compile all workflows in the directory.
+
+### Failed to Resolve Import
+
+**Error Message:**
+```
+failed to resolve import 'path': [details]
+```
+
+**Cause:** An imported file specified in the `imports:` field could not be found or accessed.
+
+**Solution:** Verify the import path:
+
+- Check the file exists at the specified path
+- Ensure the path is relative to the repository root
+- Verify file permissions allow reading
+
+```yaml
+# Imports are relative to repository root
+imports:
+  - .github/workflows/shared/tools.md
+```
+
+### Invalid Workflow Specification
+
+**Error Message:**
+```
+invalid workflowspec: must be owner/repo/path[@ref]
+```
+
+**Cause:** When using remote imports, the specification format is incorrect.
+
+**Solution:** Use the correct format: `owner/repo/path[@ref]`
+
+```yaml
+imports:
+  - githubnext/gh-aw/.github/workflows/shared/example.md@main
+```
+
+### Section Not Found
+
+**Error Message:**
+```
+section 'name' not found
+```
+
+**Cause:** An attempt to extract a specific section from the frontmatter failed because the section doesn't exist.
+
+**Solution:** Verify the referenced section exists in the frontmatter. This typically occurs during internal processing and may indicate a bug.
+
+## Runtime Errors
+
+Runtime errors occur when the compiled workflow executes in GitHub Actions.
+
+### Time Delta Errors
+
+**Error Message:**
+```
+invalid time delta format: +[value]. Expected format like +25h, +3d, +1w, +1mo, +1d12h30m
+```
+
+**Cause:** The `stop-after` field in the `on:` section contains an invalid time delta format.
+
+**Solution:** Use the correct time delta syntax:
+
+```yaml
+on:
+  issues:
+    types: [opened]
+  stop-after: +24h  # Valid: hours, days, weeks, months
+```
+
+**Supported units:**
+- `h` - hours (minimum unit for stop-after)
+- `d` - days
+- `w` - weeks
+- `mo` - months
+
+**Error Message:**
+```
+minute unit 'm' is not allowed for stop-after. Minimum unit is hours 'h'. Use +[hours]h instead of +[minutes]m
+```
+
+**Cause:** The `stop-after` field uses minutes (`m`), but the minimum allowed unit is hours.
+
+**Solution:** Convert to hours:
+
+```yaml
+# Incorrect
+stop-after: +90m
+
+# Correct
+stop-after: +2h
+```
+
+### Time Delta Too Large
+
+**Error Message:**
+```
+time delta too large: [value] [unit] exceeds maximum of [max]
+```
+
+**Cause:** The time delta exceeds the maximum allowed value for the specified unit.
+
+**Solution:** Reduce the time delta or use a larger unit:
+
+- Maximum: 12 months, 52 weeks, 365 days, 8760 hours
+
+```yaml
+# Incorrect
+stop-after: +400d
+
+# Correct
+stop-after: +12mo
+```
+
+### Duplicate Time Unit
+
+**Error Message:**
+```
+duplicate unit '[unit]' in time delta: +[value]
+```
+
+**Cause:** The same time unit appears multiple times in a time delta.
+
+**Solution:** Combine values for the same unit:
+
+```yaml
+# Incorrect
+stop-after: +1d2d
+
+# Correct
+stop-after: +3d
+```
+
+### Unable to Parse Date-Time
+
+**Error Message:**
+```
+unable to parse date-time: [value]. Supported formats include: YYYY-MM-DD HH:MM:SS, MM/DD/YYYY, January 2 2006, 1st June 2025, etc
+```
+
+**Cause:** The `stop-after` field contains an absolute timestamp that couldn't be parsed.
+
+**Solution:** Use one of the supported date formats:
+
+```yaml
+stop-after: "2025-12-31 23:59:59"
+# or
+stop-after: "December 31, 2025"
+# or
+stop-after: "12/31/2025"
+```
+
+### JQ Not Found
+
+**Error Message:**
+```
+jq not found in PATH
+```
+
+**Cause:** The `jq` command-line tool is required but not available in the environment.
+
+**Solution:** Install `jq` on the system:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install jq
+
+# macOS
+brew install jq
+```
+
+### Authentication Errors
+
+**Error Message:**
+```
+authentication required
+```
+
+**Cause:** GitHub CLI authentication is required but not configured.
+
+**Solution:** Authenticate with GitHub CLI:
+
+```bash
+gh auth login
+```
+
+For GitHub Actions, ensure `GITHUB_TOKEN` or the appropriate token is available:
+
+```yaml
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## Engine-Specific Errors
+
+### Manual Approval Invalid Format
+
+**Error Message:**
+```
+manual-approval value must be a string
+```
+
+**Cause:** The `manual-approval:` field in the `on:` section has an incorrect type.
+
+**Solution:** Provide a string value:
+
+```yaml
+# Incorrect
+on:
+  manual-approval: true
+
+# Correct
+on:
+  manual-approval: "Approve deployment to production"
+```
+
+### Invalid On Section Format
+
+**Error Message:**
+```
+invalid on: section format
+```
+
+**Cause:** The `on:` trigger configuration is malformed or contains unsupported syntax.
+
+**Solution:** Verify the trigger configuration follows [GitHub Actions syntax](/gh-aw/reference/triggers/):
+
+```yaml
+# Valid formats
+on: push
+
+# or
+on:
+  push:
+    branches: [main]
+
+# or
+on:
+  issues:
+    types: [opened, edited]
+```
+
+## File Processing Errors
+
+### Failed to Read File
+
+**Error Message:**
+```
+failed to read file [path]: [details]
+```
+
+**Cause:** The file cannot be read due to permissions, missing file, or I/O error.
+
+**Solution:** Verify:
+- File exists at the specified path
+- File permissions allow reading
+- Disk is not full or experiencing errors
+
+### Failed to Create Directory
+
+**Error Message:**
+```
+failed to create .github/workflows directory: [details]
+```
+
+**Cause:** The required directory structure cannot be created.
+
+**Solution:** Check file system permissions and available disk space.
+
+### Workflow File Already Exists
+
+**Error Message:**
+```
+workflow file '[path]' already exists. Use --force to overwrite
+```
+
+**Cause:** Attempting to create a workflow that already exists.
+
+**Solution:** Use the `--force` flag to overwrite:
+
+```bash
+gh aw init my-workflow --force
+```
+
+## Safe Output Errors
+
+### Failed to Parse Existing MCP Config
+
+**Error Message:**
+```
+failed to parse existing mcp.json: [details]
+```
+
+**Cause:** The existing `.vscode/mcp.json` file contains invalid JSON.
+
+**Solution:** Fix the JSON syntax or delete the file to regenerate:
+
+```bash
+# Validate JSON
+cat .vscode/mcp.json | jq .
+
+# Or remove and regenerate
+rm .vscode/mcp.json
+```
+
+### Failed to Marshal MCP Config
+
+**Error Message:**
+```
+failed to marshal mcp.json: [details]
+```
+
+**Cause:** Internal error when generating the MCP configuration.
+
+**Solution:** This typically indicates a bug. Report the issue with reproduction steps.
+
+## Troubleshooting Tips
+
+1. **Enable verbose output:** Use `--verbose` flag with CLI commands for detailed error information
+2. **Validate YAML syntax:** Use online YAML validators or editor extensions
+3. **Check file paths:** Ensure all paths are correct and files exist
+4. **Review frontmatter schema:** Consult the [frontmatter reference](/gh-aw/reference/frontmatter-full/) for all available options
+5. **Compile early:** Run `gh aw compile` frequently to catch errors early
+6. **Check logs:** Review GitHub Actions workflow logs for runtime errors
+
+For additional help, see [Common Issues](/gh-aw/troubleshooting/common-issues/) and [Validation Timing](/gh-aw/troubleshooting/validation-timing/).
diff --git a/docs/src/content/docs/troubleshooting/validation-timing.md b/docs/src/content/docs/troubleshooting/validation-timing.md
new file mode 100644
index 0000000000..930cb539ea
--- /dev/null
+++ b/docs/src/content/docs/troubleshooting/validation-timing.md
@@ -0,0 +1,404 @@
+---
+title: Validation Timing
+description: Understand when validation and errors occur during the GitHub Agentic Workflows lifecycle, from authoring to runtime execution.
+sidebar:
+  order: 300
+---
+
+GitHub Agentic Workflows validates workflows at three distinct stages: during authoring, at compilation time, and during runtime execution. Understanding when each type of validation occurs helps identify and fix errors more efficiently.
+
+## Validation Stages Overview
+
+| Stage | When | What is Validated | Tool/Process |
+|-------|------|-------------------|--------------|
+| **Schema Validation** | Compilation | Frontmatter structure and types | `gh aw compile` |
+| **Compilation Validation** | Compilation | File resolution, imports, and workflow generation | `gh aw compile` |
+| **Runtime Validation** | Execution | GitHub Actions syntax, permissions, and engine operations | GitHub Actions |
+
+## Schema Validation (Compile Time)
+
+Schema validation occurs when running `gh aw compile` and validates the workflow frontmatter against the defined JSON schema.
+
+### What is Checked
+
+**Frontmatter Structure:**
+- YAML syntax is valid
+- All delimiters (`---`) are present
+- Fields match the expected schema
+
+**Field Types:**
+- Strings are strings (`engine: "copilot"`)
+- Numbers are numbers (`timeout_minutes: 10`)
+- Booleans are booleans (`strict: true`)
+- Arrays are arrays (`imports: [...]`)
+- Objects are objects (`tools: {...}`)
+
+**Required Fields:**
+- `on:` trigger configuration is present
+- Engine-specific required fields exist
+
+**Enum Values:**
+- Fields with fixed value sets use valid values
+- Examples: `engine: copilot`, `state: open`
+
+**Field Constraints:**
+- Numeric ranges (e.g., `timeout_minutes: 1-360`)
+- String patterns (e.g., time delta format)
+
+### When Schema Validation Runs
+
+```bash
+# Explicit compilation
+gh aw compile
+
+# Compile specific workflow
+gh aw compile my-workflow
+
+# Compile with verbose output
+gh aw compile --verbose
+```
+
+**Timing:** Immediately when the command executes, before any file I/O or transformation.
+
+### Example Schema Errors
+
+**Invalid YAML Syntax:**
+```aw
+---
+on:
+issues:  # Missing indentation
+  types: [opened]
+---
+```
+
+**Error:** `failed to parse frontmatter: yaml: line X: mapping values are not allowed in this context`
+
+**Wrong Field Type:**
+```aw
+---
+on: push
+timeout_minutes: "10"  # String instead of number
+---
+```
+
+**Error:** `timeout_minutes must be an integer`
+
+**Invalid Enum Value:**
+```aw
+---
+on: push
+engine: gpt4  # Not a valid engine ID
+---
+```
+
+**Error:** `engine must be one of: copilot, claude, codex, custom`
+
+## Compilation Validation (Compile Time)
+
+Compilation validation occurs during the transformation of the `.md` file into a `.lock.yml` GitHub Actions workflow file.
+
+### What is Checked
+
+**File Resolution:**
+- Source workflow file exists
+- Import files can be found and read
+- Custom agent files are accessible
+
+**Import Processing:**
+- Import paths are valid
+- Imported files have valid frontmatter
+- No circular import dependencies
+
+**Workflow Generation:**
+- Engine configuration is complete
+- Tool configurations are valid
+- Safe outputs can be processed
+- MCP server configurations are correct
+
+**Expression Validation:**
+- Context expressions use allowed variables only
+- Expression syntax is valid
+
+**Cross-File References:**
+- Shared components resolve correctly
+- Remote workflow specifications are valid
+
+### When Compilation Validation Runs
+
+Compilation validation runs after schema validation passes:
+
+```bash
+gh aw compile
+```
+
+**Timing:** After schema validation, during the workflow transformation process.
+
+### Example Compilation Errors
+
+**Import Not Found:**
+```aw
+---
+on: push
+imports:
+  - shared/missing-file.md  # File doesn't exist
+---
+```
+
+**Error:** `failed to resolve import 'shared/missing-file.md': file not found`
+
+**Multiple Agent Files:**
+```aw
+---
+on: push
+imports:
+  - .github/agents/agent1.md
+  - .github/agents/agent2.md
+---
+```
+
+**Error:** `multiple agent files found in imports: 'agent1.md' and 'agent2.md'. Only one agent file is allowed per workflow`
+
+**Unauthorized Expression:**
+```aw
+---
+on: push
+---
+
+Access secret: ${{ secrets.MY_SECRET }}
+```
+
+**Error:** Compilation fails due to unauthorized expression `${{ secrets.MY_SECRET }}`
+
+## Runtime Validation (Execution Time)
+
+Runtime validation occurs when the compiled workflow executes in GitHub Actions.
+
+### What is Checked
+
+**GitHub Actions Syntax:**
+- The generated `.lock.yml` is valid GitHub Actions YAML
+- Job dependencies are correct
+- Step configurations are valid
+
+**Permissions:**
+- Token has required permissions for operations
+- Repository settings allow the operations
+
+**Environment:**
+- Required tools are available (jq, git, etc.)
+- Environment variables are set
+- Secrets are accessible
+
+**Engine Operations:**
+- AI engine is accessible and authenticated
+- MCP servers can connect
+- Network access is available (if needed)
+
+**Dynamic Conditions:**
+- Trigger conditions match event
+- Expressions evaluate correctly
+- File paths resolve
+
+**Safe Outputs:**
+- Output format is correct
+- Target repositories are accessible
+- Branch protections allow operations
+
+### When Runtime Validation Occurs
+
+Runtime validation happens in GitHub Actions during workflow execution:
+
+1. **Workflow Trigger:** Event matches `on:` configuration
+2. **Job Start:** Environment setup and authentication
+3. **Step Execution:** Each step validates its preconditions
+4. **Tool Invocation:** MCP servers and tools validate inputs
+5. **Safe Output Processing:** Post-processing jobs validate outputs
+
+**Timing:** Continuous throughout the workflow run, as each component executes.
+
+### Example Runtime Errors
+
+**Missing Tool:**
+```bash
+jq not found in PATH
+```
+
+**Cause:** The `jq` command is required but not installed in the runner environment.
+
+**Permission Denied:**
+```
+Error: Resource not accessible by integration
+```
+
+**Cause:** `GITHUB_TOKEN` lacks the required permission (e.g., `issues: write`).
+
+**Authentication Required:**
+```
+Error: authentication required
+```
+
+**Cause:** GitHub CLI authentication failed or token is invalid.
+
+**Time Delta Validation:**
+```
+Error: invalid time delta format: +90m. Expected format like +25h, +3d
+```
+
+**Cause:** `stop-after: +90m` uses minutes, but minimum unit is hours.
+
+**Network Connection Failure:**
+```
+Error: failed to connect to MCP server at https://example.com
+```
+
+**Cause:** MCP server is unreachable or network access is blocked.
+
+## Validation Flow Diagram
+
+```
+┌─────────────────┐
+│ Write Workflow  │
+│   (.md file)    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   gh aw compile │ ◄─── Command executed
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────────┐
+│ Schema Validation   │ ◄─── Frontmatter structure & types
+├─────────────────────┤
+│ • YAML syntax       │
+│ • Field types       │
+│ • Required fields   │
+│ • Enum values       │
+└────────┬────────────┘
+         │
+         ▼
+    [PASS/FAIL]
+         │
+         ▼ (if pass)
+┌──────────────────────┐
+│ Compilation          │ ◄─── File resolution & transformation
+│ Validation           │
+├──────────────────────┤
+│ • Import resolution  │
+│ • Agent files        │
+│ • Tool configs       │
+│ • Expression checks  │
+└────────┬─────────────┘
+         │
+         ▼
+    [PASS/FAIL]
+         │
+         ▼ (if pass)
+┌──────────────────────┐
+│ Generate .lock.yml   │ ◄─── Output file created
+└────────┬─────────────┘
+         │
+         ▼
+┌──────────────────────┐
+│ Commit & Push        │
+└────────┬─────────────┘
+         │
+         ▼
+┌──────────────────────┐
+│ GitHub Actions       │ ◄─── Workflow triggered
+│ Workflow Triggered   │
+└────────┬─────────────┘
+         │
+         ▼
+┌──────────────────────┐
+│ Runtime Validation   │ ◄─── Execution-time checks
+├──────────────────────┤
+│ • GH Actions syntax  │
+│ • Permissions        │
+│ • Environment setup  │
+│ • Tool availability  │
+│ • Engine operations  │
+│ • Safe outputs       │
+└────────┬─────────────┘
+         │
+         ▼
+    [SUCCESS/FAILURE]
+```
+
+## Best Practices for Each Stage
+
+### Schema Validation Best Practices
+
+1. **Validate early:** Run `gh aw compile` after each significant change
+2. **Use verbose mode:** Add `--verbose` flag to see detailed validation messages
+3. **Check types:** Ensure numbers are not quoted, booleans are true/false
+4. **Verify enums:** Consult the [frontmatter reference](/gh-aw/reference/frontmatter-full/) for valid values
+5. **Format YAML:** Use consistent indentation (2 spaces) and proper YAML syntax
+
+### Compilation Validation Best Practices
+
+1. **Organize imports:** Keep import files in a consistent location
+2. **Test imports:** Verify imported files compile independently
+3. **Limit agent files:** Use only one agent file per workflow
+4. **Check expressions:** Use only [allowed context expressions](/gh-aw/reference/templating/)
+5. **Review lock files:** Inspect generated `.lock.yml` to verify correctness
+
+### Runtime Validation Best Practices
+
+1. **Test locally:** Use `gh aw compile` to catch issues before pushing
+2. **Check permissions:** Verify `permissions:` section matches operations
+3. **Verify secrets:** Ensure required secrets are set in repository settings
+4. **Monitor logs:** Review GitHub Actions logs for runtime errors
+5. **Use safe outputs:** Prefer safe outputs over direct write permissions
+6. **Set timeouts:** Configure appropriate `timeout_minutes` for task complexity
+
+## Debugging by Stage
+
+### Schema Errors
+
+**Symptoms:** Compilation fails immediately with YAML or type errors.
+
+**Debug Steps:**
+1. Run `gh aw compile --verbose`
+2. Check the error line number in frontmatter
+3. Validate YAML syntax with online validator
+4. Consult the [frontmatter schema reference](/gh-aw/reference/frontmatter-full/)
+
+### Compilation Errors
+
+**Symptoms:** Schema validation passes but compilation fails.
+
+**Debug Steps:**
+1. Check import file paths and verify files exist
+2. Review error message for specific file or configuration issue
+3. Test imported files independently
+4. Validate expression usage against allowed list
+
+### Runtime Errors
+
+**Symptoms:** Workflow compiles but fails during execution.
+
+**Debug Steps:**
+1. Review GitHub Actions workflow logs
+2. Check permissions and token access
+3. Verify environment has required tools
+4. Test MCP server connectivity
+5. Download logs with `gh aw logs` for detailed analysis
+
+## Error Recovery Workflow
+
+When an error occurs:
+
+1. **Identify the stage:** Determine if error is schema, compilation, or runtime
+2. **Read the message:** Error messages indicate the specific problem
+3. **Consult references:** Use this guide and [error reference](/gh-aw/troubleshooting/errors/)
+4. **Fix and revalidate:** Make corrections and run `gh aw compile` again
+5. **Test incrementally:** Compile after each fix to isolate remaining issues
+
+## Related Resources
+
+- [Error Reference](/gh-aw/troubleshooting/errors/) - Detailed error messages and solutions
+- [Common Issues](/gh-aw/troubleshooting/common-issues/) - Frequently encountered problems
+- [Frontmatter Reference](/gh-aw/reference/frontmatter/) - Complete frontmatter options
+- [Workflow Structure](/gh-aw/reference/workflow-structure/) - Workflow file format
+- [Templating](/gh-aw/reference/templating/) - Allowed context expressions