📚 Documentation Quality — Daily Status Report

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

Summary

✅ Progress Since Last Report

#23832 — "Supported Languages" reference page → CLOSED (2026-04-01)

The gap identified in the 2026-04-01 report was resolved. A supported-languages reference page was created.

docs: improve security architecture explanation in index.mdx (commit #24026)

Security architecture docs were improved in docs/src/content/docs/index.mdx.

docs: condense verbose sections in common-issues.md (commit #24010)

Verbose troubleshooting sections in docs/src/content/docs/reference/common-issues.md were condensed for clarity.

🆕 New Issues Since Last Report

Issue #23950 — Docs: clarify default AWF memory limit

Created: 2026-04-01 | Reporter: @Mossaka | Labels: documentation

Problem: docs/src/content/docs/reference/frontmatter.md → ## memory field states "AWF's default is used when unspecified" but does not state what that default value is. The actual default is 6g (set in gh-aw-firewall/src/docker-manager.ts).

Docs cross-reference: docs/src/content/docs/reference/frontmatter.md — memory: field documentation.

Classification: ❌ Documentation gap — fix is simple: add (default: 6g) to the memory field description.

Issue #23957 — docs: add audit command reference page

Created: 2026-04-01 | Reporter: @Mossaka | Labels: documentation, enhancement, audit, cli | Part of epic: #22735

Problem: The audit feature shipped ~13K LOC with 3 CLI commands (gh aw audit, gh aw audit diff, gh aw audit report) but there are zero dedicated documentation pages in the docs site.

Docs cross-reference: No file docs/src/content/docs/reference/audit.md exists. Closest related files: docs/src/content/docs/reference/ (command references) and pkg/cli/audit.go, pkg/cli/audit_report.go.

Classification: ❌ Missing documentation — a new reference/audit.md page is needed covering all three audit subcommands, flags, output formats, and JSON schemas.

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

Created: 2026-04-01 | Labels: documentation, enhancement, audit, cli | Part of epic: #22735

Problem: The audit commands produce rich structured output (JSON, markdown) consumable programmatically by agents, but no guide shows users how to do this.

Docs cross-reference: No file docs/src/content/docs/guides/audit-with-agent.md exists.

Classification: ❌ Missing documentation — a new guides/audit-with-agent.md page is needed.

Issue #23959 — docs: enhance existing pages with audit cross-references and glossary entries

Created: 2026-04-01 | Labels: documentation, enhancement, audit | Part of epic: #22735

Problem: Several existing pages need updating to mention the audit feature for discoverability:

• reference/glossary.md — needs entries for Audit, Audit diff, Firewall analysis, Behavior fingerprint
• reference/frontmatter.md — needs an audit tip linking to reference/audit.md
• guides/debugging.md — needs an "Analyzing failures with audit" section

Classification: ❌ Documentation gap — spread across multiple existing pages.

⚠️ Carry-Over Documentation Gaps

toolsets: [all] shorthand undocumented — ongoing gap

Status: No doc addition yet. reference/github-tools.md still lacks a warning that toolsets: [all] silently includes the dependabot toolset requiring vulnerability-alerts: read (GitHub App–only).

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 undocumented.

Classification: ❌ Docs/implementation mismatch — unresolved.

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

Problem: docs/src/content/docs/reference/frontmatter.md → ## Service Containers (services:) documents the field 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.

📊 Day-over-Day Trend

🎯 Recommended Actions

Generated by Daily Status Report workflow — 2026-04-02 09:26 UTC

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

Generated by Dev · ◷

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