docs: improve search & AI-assistant discoverability - #48822
Merged
pelikhan merged 2 commits intoJul 29, 2026
Conversation
…ation Tasks completed: - Task 1: Add self-contained opening paragraphs to homepage, quickstart, creating-workflows, FAQ, and security architecture pages - Task 2: Create 4 engine landing pages (Copilot, Claude, Codex, Gemini) under docs/engines/ + sidebar entries - Task 3: Create 4 use-case pages (issue triage, PR review, release notes, docs automation) under docs/use-cases/ + sidebar entries - Task 4: Create comparison page (gh-aw vs alternatives) - Task 5: Add static llms.txt to docs/public/ - Task 6: Add FAQPage JSON-LD to FAQ page and HowTo JSON-LD to quickstart - Task 7: Update README first paragraph with canonical definition - Task 8: Fix outdated githubnext.github.io link in README; add repo topics guidance to CONTRIBUTING - Task 9: Add Related guides section to quickstart; add engine/use-case feature cards to homepage; add related-guides section to FAQ Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot
AI
changed the title
docs: improve search & AI-assistant discoverability of gh-aw documentation
docs: improve search & AI-assistant discoverability
Jul 29, 2026
Copilot created this pull request from a session on behalf of
pelikhan
July 29, 2026 08:26
View session
pelikhan
reviewed
Jul 29, 2026
| label: 'Reference', | ||
| items: [ | ||
| { label: 'AI Engines', link: '/reference/engines/' }, | ||
| { label: 'Choosing an Approach (Comparison)', link: '/reference/comparison/' }, |
Contributor
Author
There was a problem hiding this comment.
Removed the Choosing an Approach (Comparison) entry from the Reference section of the sidebar.
….json Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Improves documentation discoverability with engine- and use-case-focused landing pages, structured metadata, and clearer project descriptions.
Changes:
- Adds four engine and four automation use-case guides.
- Expands navigation, cross-links, FAQ content, and JSON-LD metadata.
- Refreshes generated references, project descriptions, and maintainer guidance.
Show a summary per file
| File | Description |
|---|---|
README.md |
Updates project definition and workshop link. |
CONTRIBUTING.md |
Documents recommended repository topics. |
docs/astro.config.mjs |
Adds redirects and sidebar entries. |
docs/src/content/docs/index.mdx |
Adds engine and use-case navigation. |
docs/src/content/docs/setup/quick-start.mdx |
Adds definition, JSON-LD, and related guides. |
docs/src/content/docs/setup/creating-workflows.mdx |
Adds a concise workflow definition. |
docs/src/content/docs/reference/faq.md |
Adds FAQs, JSON-LD, and related links. |
docs/src/content/docs/reference/model-tables.md |
Documents the auto model alias. |
docs/src/content/docs/introduction/architecture.mdx |
Expands the security overview. |
docs/src/content/docs/guides/ai-issue-triage.md |
Adds an issue-triage guide. |
docs/src/content/docs/guides/automated-pr-review.md |
Adds an automated review guide. |
docs/src/content/docs/guides/ai-release-notes.md |
Adds a release-notes guide. |
docs/src/content/docs/guides/docs-automation.md |
Adds a documentation automation guide. |
docs/src/content/docs/engines/copilot.md |
Adds Copilot setup guidance. |
docs/src/content/docs/engines/claude.md |
Adds Claude setup guidance. |
docs/src/content/docs/engines/codex.md |
Adds Codex setup guidance. |
docs/src/content/docs/engines/gemini.md |
Adds Gemini setup guidance. |
docs/src/content/docs/agent-factory-status.mdx |
Refreshes listed factory workflows. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (1)
docs/src/content/docs/reference/faq.md:666
- The “No” contradicts the same sentence's statement that runs also consume GitHub Actions compute minutes. Those minutes can be billable beyond the engine cost, so this should say that gh-aw has no license fee while runs can still incur Actions charges.
No. gh-aw itself is free and open source. You pay only your AI provider's standard inference rates (or consume Copilot quota) plus the GitHub Actions compute minutes for the run. See [Billing](/gh-aw/reference/billing/) for a detailed breakdown.
- Files reviewed: 18/18 changed files
- Comments generated: 8
- Review effort level: Medium
Comment on lines
+6
to
+10
| head: | ||
| - tag: script | ||
| attrs: | ||
| type: application/ld+json | ||
| content: | |
|
|
||
| Documentation automation with gh-aw means running an agent on a schedule or after code changes so it can detect drift between code and docs, prepare updates, and propose them as a pull request. gh-aw keeps the agent inside a controlled workflow and uses a safe output to turn proposed documentation changes into a reviewable PR. | ||
|
|
||
| Install the starter with `gh aw add-wizard githubnext/agentics/docs-updater`. |
|
|
||
| AI-generated release notes with gh-aw means running an agent when a release is published, a branch is pushed, or a scheduled reporting window arrives so it can summarize merged work and produce a publishable report. gh-aw handles the GitHub-side output through safe outputs instead of direct write access from the agent. | ||
|
|
||
| Install the starter with `gh aw add-wizard githubnext/agentics/release-notes`. |
|
|
||
| Automated AI pull request review with gh-aw means running an agent on each pull request update so it can inspect the diff, identify likely defects, and return review feedback in GitHub-native review surfaces. The workflow keeps the agent read-only and uses safe outputs for the review summary and inline comments. | ||
|
|
||
| Install the starter with `gh aw add-wizard githubnext/agentics/pr-review`. |
| description: Use gh-aw to review pull requests automatically, post summary feedback, and add inline review comments through safe outputs. | ||
| --- | ||
|
|
||
| Automated AI pull request review with gh-aw means running an agent on each pull request update so it can inspect the diff, identify likely defects, and return review feedback in GitHub-native review surfaces. The workflow keeps the agent read-only and uses safe outputs for the review summary and inline comments. |
| "name": "Does gh-aw add any cost beyond what the AI engine charges?", | ||
| "acceptedAnswer": { | ||
| "@type": "Answer", | ||
| "text": "No. gh-aw itself is free and open source. You pay only your AI provider's standard inference rates (or consume Copilot quota) plus GitHub Actions compute minutes." |
Comment on lines
+15
to
+20
| { | ||
| "@type": "Question", | ||
| "name": "What is GitHub Agentic Workflows?", | ||
| "acceptedAnswer": { | ||
| "@type": "Answer", | ||
| "text": "GitHub Agentic Workflows (gh-aw) is a GitHub CLI extension that compiles Markdown workflow files into hardened GitHub Actions workflows, running AI coding agents — GitHub Copilot, Claude Code, OpenAI Codex, or Google Gemini — with sandboxed execution, read-only defaults, and validated safe outputs." |
Comment on lines
+322
to
+323
| { | ||
| label: 'AI Engines', |
Contributor
|
✅ Test Quality Sentinel completed test quality analysis. No test files were added or modified in PR #48822. This PR contains only documentation changes (markdown files in docs/, README.md, CONTRIBUTING.md, and astro.config.mjs). Test Quality Sentinel analysis not applicable. |
Contributor
|
🎉 This pull request is included in a new release. Release: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The docs lacked targeted landing pages for the most common high-intent queries ("claude code github actions", "ai issue triage github", etc.) and were missing structured data, a canonical definition paragraph, and an llms.txt index.
New pages (13 files)
/engines/{copilot,claude,codex,gemini}/— per-engine landing pages with setup delta (secret name,engine:flag), a minimal workflow example, and an honest "gh-aw vs. native action" comparison note/use-cases/{ai-issue-triage,automated-pr-review,ai-release-notes,docs-automation}/— task-intent pages with complete workflows,gh aw add-wizardinstall commands, and safe-outputs security rationale/reference/comparison/— even-handed decision table across gh-aw,anthropics/claude-code-action, and hand-rolled ActionsExisting page edits
index.mdx,quick-start.mdx,creating-workflows.mdx,faq.md,architecture.mdx): prepended a self-contained 2–3 sentence definition naming all four engines; existing content preserved belowfaq.md): added 5 entries (engine choice, Claude schedule usage, gh-aw vs Actions, cost,FAQPageJSON-LD viahead:frontmatter); added Related guides sectionquick-start.mdx): addedHowToJSON-LD, "Related guides" section linking to all four use-case pagesindex.mdx): added "AI Engines" and "Common Use Cases" feature-card sections with inbound links to new pagesastro.config.mjs): added "AI Engines" and "Use Cases" groups; comparison page added to ReferenceInfrastructure / metadata
docs/public/llms.txt— static index of all 150+ pages with canonical URLs and descriptions for AI crawlersREADME.md— first paragraph now matches canonical definition with all four engine namesREADME.md— fixed stalegithubnext.github.io/gh-aw-workshoplink →github.com/githubnext/gh-aw-workshopCONTRIBUTING.md— added maintainer note listing recommended repository topics (github-actions,ai-agents,claude,copilot, etc.) to set via repo SettingsExternal follow-ups (humans only)
githubnext.comproject page and any third-party posts still referencing old URLs