docs: add debug logging to common-issues troubleshooting page

[Copilot]

The DEBUG environment variable for gh aw commands was only documented in AGENTS.md (developer-facing), leaving users without a discoverable path to internal diagnostic logging when troubleshooting.

Changes

• docs/src/content/docs/troubleshooting/common-issues.md: Added a new "Enable Debug Logging" subsection under "Workflow Failures and Debugging" covering:
  • DEBUG=* to enable all logs, package-scoped patterns (workflow:*, cli:*, parser:*), multi-package combos, and exclusion syntax
  • DEBUG_COLORS=0 for clean log capture to file
  • Explanation of log line anatomy: namespace, message, and elapsed-time diff
  • pkg:filename namespace convention with common namespace examples

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: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build tion instructio (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

Add the "debug logging" from agents.md into the common-issues page in the debugging section so that user discover how to use the logging system.

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[Copilot]

Pull request overview

Adds user-facing troubleshooting documentation for enabling internal debug logging in gh aw commands, making diagnostic output discoverable outside developer-focused docs.

Changes:

• Added an “Enable Debug Logging” subsection to the Common Issues troubleshooting page with DEBUG / DEBUG_COLORS usage patterns and log output interpretation.
• Updated the Agent Factory status page to include the “Smoke Workflow Call with Inputs” workflow entry.

Reviewed changes

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

File	Description
docs/src/content/docs/troubleshooting/common-issues.md	Documents how to enable and interpret internal debug logs for troubleshooting workflow failures.
docs/src/content/docs/agent-factory-status.mdx	Adds the missing “Smoke Workflow Call with Inputs” row to the workflow status table.

---

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

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

The description of the time diff (+125ms) is slightly inaccurate: the logger tracks lastLog per-namespace (per logger.New(...) instance), so the diff is time since the last message from the same logger/namespace, not necessarily since the previous line in the combined output. Consider rewording to avoid implying it’s always a global “previous log entry” diff, especially when multiple namespaces are enabled and interleave.

Suggested change

	- **Time elapsed** – time since the previous log entry (e.g., `+125ms`), which helps identify slow steps
	- **Time elapsed** – time since the previous log entry from the same namespace (e.g., `+125ms`), which helps identify slow steps

[Copilot]

This paragraph says namespaces follow a strict pkg:filename convention, but the logger docs and codebase use both pkg:filename and pkg:component (e.g., workflow:compiler). To avoid contradicting the examples in the same sentence, consider updating the convention wording to reflect both allowed forms.

Suggested change

	Log namespaces follow a `pkg:filename` convention. Common namespaces include `cli:compile_command`, `workflow:compiler`, `workflow:expression_extraction`, and `parser:frontmatter`. Wildcards (`*`) match any suffix, so `workflow:*` captures all workflow-package logs.
	Log namespaces typically follow a `pkg:filename` or `pkg:component` convention. Common namespaces include `cli:compile_command`, `workflow:compiler`, `workflow:expression_extraction`, and `parser:frontmatter`. Wildcards (`*`) match any suffix, so `workflow:*` captures all workflow-package logs.