📚 Documentation Quality — Daily Status Report

Date: 2026-04-03 | Scope: gh-aw documentation health
Previous report: #24041 (2026-04-02)

Summary

✅ Progress Since Last Report

#23950 — Docs: clarify default AWF memory limit → CLOSED (2026-04-02)

The memory: field in docs/src/content/docs/reference/frontmatter.md now explicitly states the default value is 6g.

#23957 — docs: add audit command reference page → CLOSED (2026-04-02)

docs/src/content/docs/reference/audit.md was created, covering all three audit subcommands (gh aw audit, gh aw audit diff, gh aw audit report), flags, output formats, and JSON schemas.

⚠️ Carry-Over Documentation Gaps

toolsets: [all] shorthand — undocumented permission risk

Status: Still unresolved. docs/src/content/docs/reference/github-tools.md does not warn that toolsets: [all] silently includes the dependabot toolset, which requires vulnerability-alerts: read (GitHub App–only). Users who copy examples using [all] get a cryptic permissions failure.

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 unless you need Dependabot tools.

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

Problem: docs/src/content/docs/reference/copilot-custom-agents.md states agent files should live in .github/agents/, but the compiler resolves imports relative to .github/workflows/, causing "file not found" errors.

Classification: ❌ Docs/implementation mismatch — unresolved.

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

Problem: docs/src/content/docs/reference/imports.md and copilot-custom-agents.md claim agent imports work cross-engine. In practice, the .github/snippets/ workaround is safer but undocumented.

Classification: ❌ Docs/implementation mismatch — unresolved. Related to #19703.

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

Problem: docs/src/content/docs/reference/frontmatter.md documents services: with a Postgres example but never clarifies that service containers are unreachable from inside the agent sandbox.

Classification: ❌ Documentation gap — unresolved.

Issue #23212 — gh aw add rewrites imports with incorrect path

Problem: docs/src/content/docs/guides/packaging-imports.md does not document gh aw add's import-rewriting behavior, the incorrect base path it uses, or how to opt out.

Classification: ❌ Undocumented behavior — unresolved.

Issue #23958 — docs: add guide for consuming audit reports with an agent

Status: Open, assigned to Copilot (part of epic #22735).
Problem: No guide exists showing how to feed gh aw audit --json output into agentic workflows for automated analysis.

Target file: docs/src/content/docs/guides/audit-with-agents.md

Classification: ❌ Missing documentation — in progress.

📋 Open Plan: Noob Tester Audit (#24115)

Issue #24115 tracks 8 actionable improvements identified from the Documentation Noob Test Report. None are yet resolved:

🔎 Issues Answerable by Existing Docs

The documentation survey confirms comprehensive coverage of all major topics. Issues asking "how to configure X" likely already have answers:

Issue #23959 (audit cross-references and glossary entries) is still open — adding those entries to reference/glossary.md, troubleshooting/debugging.md, reference/network.md, reference/mcp-gateway.md, and reference/cost-management.md would significantly improve discoverability.

📊 Day-over-Day Trend

🎯 Recommended Actions

Generated by Daily Status Report workflow — 2026-04-03 09:05 UTC

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Dev · ● 1M · ◷

• expires on Apr 10, 2026, 9:10 AM UTC