📚 Documentation Quality — Daily Status Report

Date: 2026-03-31 | Scope: gh-aw documentation health
Previous report: #22630 (2026-03-24)

---

Summary

Category	Count
Carry-over documentation gaps	1 ⚠️
Open issues with documentation problems	5 🔴
Issues answerable by existing documentation	1 ✅
Documentation gaps without coverage	3 ❌

---

⚠️ Carry-Over from Previous Report

Issue #22207 — toolsets: [all] shorthand undocumented

Status: Still open — no doc addition yet for toolsets: [all] in reference/github-tools.md.

docs/src/content/docs/reference/github-tools.md documents the dependabot toolset requirement (vulnerability-alerts: read) but never mentions [all] as a valid shorthand. Users who discover toolsets: [all] from examples have no docs warning them about implied permissions.

Recommended action: Add a callout to reference/github-tools.md:

⚠️ toolsets: [all] includes the dependabot toolset, which requires vulnerability-alerts: read (GitHub App–only). Prefer listing specific toolsets if you don't need Dependabot tools.

---

🔴 Open Issues with Documentation Problems

Issue #19703 — .github/agents/ path does not resolve

Title: Agent imports: .github/agents/ path does not resolve — must be under .github/workflows/

Problem: The [custom agents documentation]((github.github.io/redacted) states agent files should live in .github/agents/, but the compiler resolves imports relative to .github/workflows/, causing a "file not found" error for the documented path.

Docs cross-reference: docs/src/content/docs/reference/copilot-custom-agents.md — says .github/agents/ works, but it doesn't.

Classification: ❌ Documentation describes behavior that doesn't match implementation. Either fix the compiler or update the docs to reflect that agents/ must be under .github/workflows/agents/.

---

Issue #19611 — .github/agents imports on Claude/Codex take fragile prompt-assembly path

Title: Bug: .github/agents imports on Claude/Codex take fragile prompt-assembly path; .github/snippets avoids it

Problem: Docs claim .github/agents/*.md imports work for non-Copilot engines by injecting markdown into the prompt. In practice, agent imports trigger special AGENT_CONTENT + PROMPT_TEXT assembly that fails with --print mode, while .github/snippets/ imports use a more robust path.

Docs cross-reference: docs/src/content/docs/reference/imports.md (lines 76–120) and docs/src/content/docs/reference/copilot-custom-agents.md.

Classification: ❌ Docs/implementation mismatch. Related to #19703. Workaround (use .github/snippets/) is undocumented.

---

Issue #22939 — AWF agent cannot reach Postgres started via services:

Title: BUG: AWF agent cannot reach Postgres started via services:

Problem: The services: frontmatter is documented (with a Postgres example in docs/src/content/docs/reference/frontmatter.md), but the docs never clarify whether service containers are reachable from inside the AWF sandbox. A user followed the documented example and found Postgres unreachable — service ports bind to the host, but the agent container's network isolation prevents connection.

Docs cross-reference: docs/src/content/docs/reference/frontmatter.md → ## Service Containers (services:) — documents the field but says nothing about sandbox networking.

Classification: ❌ Documentation gap. The services: section should include a note clarifying whether service containers are accessible from the agent sandbox (and what workaround to use if not — e.g., access via host.docker.internal or loopback).

---

Issue #23212 — gh aw add rewrites \{\\{\#import shared/X.md}} with incorrect cross-repo path

Title: gh aw add rewrites \{\\{\#import shared/X.md}} with incorrect cross-repo path (resolves from repo root instead of .github/workflows/)

Problem: Two bugs in one: (1) gh aw add unconditionally rewrites all local \{\\{\#import shared/X.md}} directives to pinned cross-repo paths, with no way to mark an import as local; (2) when it does rewrite, it uses the wrong base path (repo root instead of .github/workflows/), producing a 404.

Docs cross-reference: docs/src/content/docs/guides/packaging-imports.md covers the packaging pattern but does not document gh aw add's import rewriting behavior or how to keep imports local.

Classification: ❌ Undocumented behavior causing breakage. Docs should explain the rewriting strategy and how to opt out.

---

Issue #1250 — "web-search" not available when using Copilot CLI

Title: "web-search" is reported as not available when using Copilot CLI

Problem: Many sample workflows trigger a warning Engine 'copilot' does not support the web-search tool. The warning is unhelpful — no link to documentation about alternatives (e.g., third-party MCPs).

Docs cross-reference: docs/src/content/docs/guides/mcps.md and docs/src/content/docs/guides/getting-started-mcp.md exist but do not specifically address the "what to do instead of web-search" question.

Classification: ❌ Missing documentation page. A short "Web Search Alternatives" page linking to MCP options (Brave Search MCP, Tavily, etc.) would address the issue. The warning itself should emit a link to this new page.

---

✅ Issues Answerable by Existing Documentation

Issue #20593 — Documentation missing for GH_AW_GITHUB_TOKEN

Title: Documentation missing for GH_AW_GITHUB_TOKEN magic secret

Original problem: PR #17990 removed the auth.mdx guidance for GH_AW_GITHUB_TOKEN, leaving users without clear instructions on when and why it's needed.

Current state: docs/src/content/docs/reference/tokens.md now provides a comprehensive token reference including:

• Full quick-reference table listing GH_AW_GITHUB_TOKEN and its fallback chain
• Dedicated section explaining use as a general-purpose fallback
• Per-use-case documentation (MCP server, agent assignment, plugins, etc.)

Assessment: ✅ This issue appears to be closeable with a pointer to docs/src/content/docs/reference/tokens.md#gh_aw_github_token. Recommend closing #20593 and linking the tokens reference.

---

📊 Day-over-Day Trend

Metric	2026-03-24	2026-03-31	Change
Open doc-problem issues	0	5	⬆️ +5
Issues closeable with doc pointer	0	1	✅ +1
Carry-over gaps	1	1	↔ Stable
Docs testing warnings	2	2	↔ Stable (skip-link target, sitemap 404 in dev)

---

🎯 Recommended Actions

Priority	Action	Target
High	Fix compiler or update docs for .github/agents/ path resolution	#19703, #19611
High	Add sandbox networking note to services: docs section	#22939
Medium	Document gh aw add import rewriting behavior + local-import opt-out	#23212
Medium	Add toolsets: [all] warning to github-tools.md	#22207 carry-over
Low	Create "Web Search Alternatives" MCP guide page	#1250
Low	Close #20593 with pointer to tokens.md#gh_aw_github_token	#20593

---

Generated by Daily Status Report workflow — 2026-03-31 09:30 UTC

Generated by Dev · ◷

• expires on Apr 7, 2026, 9:36 AM UTC