[plan] Fix documentation issues from noob tester audit (discussion #24114)

[github-actions]

Context

This issue tracks actionable improvements identified in the Documentation Noob Test Report (2026-04-02).

Quick Wins (High Impact, Low Effort)

1. Fix sitemap 404

/gh-aw/sitemap-index.xml returns 404. Check the Astro sitemap plugin config in docs/ — ensure @astrojs/sitemap is configured and the sitemap URL is correct in astro.config.*.

2. Clarify COPILOT_GITHUB_TOKEN in Quick Start

In docs/src/content/docs/setup/quick-start.md (or equivalent):

• Add a note explaining what COPILOT_GITHUB_TOKEN is, how it differs from GITHUB_TOKEN, and how to add it as a GitHub Actions secret
• Link to /gh-aw/reference/auth/
• Clarify whether a free or paid GitHub Copilot subscription is required

3. Define "frontmatter" in Quick Start Step 4

Add a one-sentence definition of frontmatter in the Quick Start where it's first mentioned, with a link to the reference docs.

4. Rename or explain "Peli's Agent Factory" in nav

In the docs nav config (e.g., docs/astro.config.* or sidebar config), rename the nav item to something generic like "Examples" or add a subtitle/description so new users understand what it is.

5. Fix "Examples" nav link inconsistency

The top nav "Examples" links to /#gallery (homepage anchor) but there is also /gh-aw/examples/multi-repo/. Either create a proper /examples/ index page or update the nav to point there directly.

Longer-Term Improvements

6. Move GHES content lower on the CLI page

In the CLI commands page (docs/src/content/docs/setup/cli.md or equivalent), move the GitHub Enterprise Server configuration section below beginner content — ideally in a collapsible <details> section.

7. Move the early-access warning higher

The early-access/caution notice should appear earlier on the homepage or Quick Start page so security-conscious developers see it before reading marketing content.

8. Add sample output for gh aw add-wizard in Quick Start

Show what the interactive add-wizard process looks like (terminal output or screenshot) so users know what to expect.

Acceptance Criteria

• Sitemap no longer returns 404
• Quick Start explains COPILOT_GITHUB_TOKEN with a link to auth reference
• "Frontmatter" is defined on first use in Quick Start
• Nav item "Peli's Agent Factory" renamed or described
• Examples nav link points to a proper examples page or index
• CLI page buries GHES content below beginner content
• Early-access warning is more prominent
• add-wizard step shows sample output

Files Likely to Change

• docs/astro.config.* — sitemap config, nav/sidebar config
• docs/src/content/docs/setup/quick-start.md — frontmatter definition, token explanation, wizard output
• docs/src/content/docs/setup/cli.md — reorder GHES content
• docs/src/content/docs/ homepage or landing page — early-access warning placement

Generated by Plan Command for issue #discussion #24114 · ◷

• expires on Apr 4, 2026, 1:34 PM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot coding agent.

The Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · ◷

[github-actions]

This issue was automatically closed because it expired on 2026-04-04T13:34:52.509Z.

Closed by Workflow