githubnext · mnkiefer · Nov 9, 2025 · Nov 9, 2025 · Nov 9, 2025 · Nov 9, 2025
diff --git a/README.md b/README.md
@@ -14,11 +14,11 @@ Write agentic workflows in natural language markdown, and run them safely in Git
 
 ## 🚀 Quick Start
 
-Ready to get your first agentic workflow running? Follow our step-by-step [Quick Start Guide](https://githubnext.github.io/gh-aw/get-started/quick-start/) to install the extension, add a sample workflow, and see it in action.
+Ready to get your first agentic workflow running? Follow our step-by-step [Quick Start Guide](https://githubnext.github.io/gh-aw/setup/quick-start/) to install the extension, add a sample workflow, and see it in action.
 
 ## 📖 Overview
 
-Learn about the concepts behind agentic workflows, explore available workflow types, and understand how AI can automate your repository tasks. See [Concepts](https://githubnext.github.io/gh-aw/get-started/concepts/).
+Learn about the concepts behind agentic workflows, explore available workflow types, and understand how AI can automate your repository tasks. See [How It Works](https://githubnext.github.io/gh-aw/introduction/how-it-works/).
 
 ## 🔧 How It Works
 

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -43,11 +43,12 @@ export default defineConfig({
 				{ icon: 'github', label: 'GitHub', href: 'https://github.com/githubnext/gh-aw' },
 			],
 			tableOfContents: { 
-				minHeadingLevel: 2, 
-				maxHeadingLevel: 3 
-			},
+			minHeadingLevel: 2, 
+			maxHeadingLevel: 4 
+		},
 			pagination: true,
 			expressiveCode: {
+				frames: false,
 				shiki: {
 						langs: /** @type {any[]} */ ([
 							"markdown",
@@ -80,24 +81,68 @@ export default defineConfig({
 			],
 			sidebar: [
 				{
-					label: 'Get Started',
-					autogenerate: { directory: 'get-started' },
+					label: 'Introduction',
+					autogenerate: { directory: 'introduction' },
+				},
+				{
+					label: 'Setup',
+					items: [
+						{ label: 'Quick Start', link: '/setup/quick-start/' },
+						{ label: 'CLI Commands', link: '/setup/cli/' },
+						{ label: 'VS Code Integration', link: '/setup/vscode/' },
+						{ label: 'MCP Server', link: '/setup/mcp-server/' },
+					],
 				},
 				{
 					label: 'Guides',
-					autogenerate: { directory: 'guides' },
+					items: [
+						{ label: 'Creating Workflows', link: '/setup/agentic-authoring/' },
+						{ label: 'Packaging & Distribution', link: '/guides/packaging-imports/' },
+						{ label: 'Security Best Practices', link: '/guides/security/' },
+						{ label: 'Using MCPs', link: '/guides/mcps/' },
+						{ label: 'Custom Safe Outputs', link: '/guides/custom-safe-outputs/' },
+						{ label: 'Threat Detection', link: '/guides/threat-detection/' },
+						{ label: 'Web Search', link: '/guides/web-search/' },
+					],
 				},
 				{
-					label: 'Setup',
-					autogenerate: { directory: 'setup' },
+					label: 'Examples',
+					items: [
+						{ label: 'ChatOps', link: '/examples/comment-triggered/chatops/' },
+						{ label: 'IssueOps', link: '/examples/issue-pr-events/issueops/' },
+						{ label: 'LabelOps', link: '/examples/issue-pr-events/labelops/' },
+						{ label: 'DailyOps', link: '/examples/scheduled/dailyops/' },
+						{ label: 'Research & Planning', link: '/examples/scheduled/research-planning/' },
+						{ label: 'Triage & Analysis', link: '/examples/issue-pr-events/triage-analysis/' },
+						{ label: 'Coding & Development', link: '/examples/issue-pr-events/coding-development/' },
+						{ label: 'Quality & Testing', link: '/examples/issue-pr-events/quality-testing/' },
+					],
 				},
 				{
-					label: 'Workflows',
-					autogenerate: { directory: 'reference' },
+					label: 'Reference',
+					items: [
+						{ label: 'Workflow Structure', link: '/reference/workflow-structure/' },
+						{ label: 'Frontmatter', link: '/reference/frontmatter/' },
+						{ label: 'Frontmatter (Full)', link: '/reference/frontmatter-full/' },
+						{ label: 'Triggers', link: '/reference/triggers/' },
+						{ label: 'Command Triggers', link: '/reference/command-triggers/' },
+						{ label: 'Permissions', link: '/reference/permissions/' },
+						{ label: 'AI Engines', link: '/reference/engines/' },
+						{ label: 'Tools', link: '/reference/tools/' },
+						{ label: 'Safe Outputs', link: '/reference/safe-outputs/' },
+						{ label: 'Custom Safe Outputs', link: '/guides/custom-safe-outputs/' },
+						{ label: 'Imports', link: '/reference/imports/' },
+						{ label: 'Templating', link: '/reference/templating/' },
+						{ label: 'Network Access', link: '/reference/network/' },
+						{ label: 'Cache & Memory', link: '/reference/cache-memory/' },
+						{ label: 'Concurrency', link: '/reference/concurrency/' },
+						{ label: 'Markdown', link: '/reference/markdown/' },
+						{ label: 'Custom Agents', link: '/reference/custom-agents/' },
+					],
 				},
 				{
-					label: 'Applications',
-					autogenerate: { directory: 'samples' },
+					label: 'Troubleshooting',
+					autogenerate: { directory: 'troubleshooting' },
 				},
 				{
 					label: 'Status',

diff --git a/docs/src/components/CustomHead.astro b/docs/src/components/CustomHead.astro
@@ -5,6 +5,8 @@ import Default from '@astrojs/starlight/components/Head.astro';
 
 <Default {...Astro.props}><slot /></Default>
 
+<link rel="icon" type="image/svg+xml" href="/gh-aw/favicon.svg" />
+
 <script is:inline>
   (function() {
     const storedTheme = localStorage.getItem('starlight-theme') || 'auto';

diff --git a/docs/src/components/CustomHeader.astro b/docs/src/components/CustomHeader.astro
@@ -4,10 +4,10 @@ const base = import.meta.env.BASE_URL;
 ---
 
 <div class="custom-header-links">
-	<a href={`${base}get-started/about/`} class="header-link">Docs</a>
-	<a href={`${base}get-started/quick-start/`} class="header-link">Quick Start</a>
-	<a href={`${base}setup/cli/#installation`} class="header-link">Setup</a>
-	<a href={`${base}guides/security`} class="header-link">Guides</a>
+	<a href={`${base}introduction/overview/`} class="header-link">Docs</a>
+	<a href={`${base}setup/quick-start/`} class="header-link">Quick Start</a>
+	<a href={`${base}examples/comment-triggered/chatops/`} class="header-link">Examples</a>
+	<a href={`${base}reference/workflow-structure/`} class="header-link">Reference</a>
 	<a href={`${base}status/`} class="header-link">Status</a>
 </div>
 <Default {...Astro.props} />

diff --git a/docs/src/content/docs/examples/comment-triggered.md b/docs/src/content/docs/examples/comment-triggered.md
@@ -0,0 +1,45 @@
+---
+title: Comment-Triggered Workflows
+description: Interactive workflows triggered by slash commands in issues, PRs, and discussions - ChatOps patterns for human-in-the-loop automation
+sidebar:
+  order: 2
+---
+
+Comment-triggered workflows respond to slash commands typed in GitHub conversations. They enable ChatOps patterns where team members interact with AI agents through natural commands like `/review`, `/deploy`, or `/analyze`.
+
+## When to Use Comment-Triggered Workflows
+
+- **Interactive assistance**: Code review helpers, analysis on demand
+- **Controlled automation**: Human decides when workflow runs
+- **Context-aware responses**: AI acts on specific issue/PR context
+- **Team collaboration**: Shared commands for common tasks
+
+## Patterns in This Section
+
+- **[ChatOps](/gh-aw/examples/comment-triggered/chatops/)** - Build interactive automation with command triggers
+
+## Example Command Triggers
+
+```yaml
+on:
+  command:
+    name: review           # Responds to /review
+    events: [pull_request_comment]
+```
+
+```yaml
+on:
+  command:
+    name: analyze
+    events: [issue_comment, pull_request_comment]
+```
+
+## Quick Start
+
+Add a ChatOps workflow to your repository:
+
+```bash
+gh aw add githubnext/agentics/chatops-example
+```
+
+Then trigger it by commenting `/review` on a pull request!
diff --git a/docs/src/content/docs/guides/chatops.md → ...ocs/examples/comment-triggered/chatops.md b/docs/src/content/docs/guides/chatops.md → ...ocs/examples/comment-triggered/chatops.md
@@ -1,10 +1,19 @@
 ---
 title: ChatOps
-description: A guide to building interactive automation using command triggers and safe outputs for ChatOps-style workflows.
+description: Interactive automation triggered by slash commands (/review, /deploy) in issues and PRs - human-in-the-loop workflows
+sidebar:
+  badge: { text: 'Command-triggered', variant: 'note' }
 ---
 
 ChatOps brings automation into GitHub conversations through command triggers that respond to slash commands in issues, pull requests, and comments. Team members can trigger workflows by typing commands like `/review` or `/deploy` directly in discussions.
 
+## When to Use ChatOps
+
+- **Interactive code reviews** - `/review` to analyze PR changes on demand
+- **On-demand deployments** - `/deploy staging` when you're ready
+- **Assisted analysis** - `/analyze` for specific investigations
+- **Team collaboration** - Shared commands everyone can use
+
 ```aw wrap
 ---
 on:

diff --git a/docs/src/content/docs/examples/issue-pr-events.md b/docs/src/content/docs/examples/issue-pr-events.md
@@ -0,0 +1,53 @@
+---
+title: Issue & PR Event Workflows
+description: Workflows triggered by GitHub events - issues opened, PRs created, labels added - for automated triage, analysis, and code assistance
+sidebar:
+  order: 3
+---
+
+Issue and PR event workflows run automatically when specific GitHub events occur. They're ideal for automated triage, intelligent labeling, code analysis, and quality checks that happen without any manual trigger.
+
+## When to Use Event-Triggered Workflows
+
+- **Immediate response**: Auto-triage new issues, welcome contributors
+- **Automated analysis**: Accessibility audits, security scans
+- **Smart labeling**: Classify issues/PRs based on content
+- **Quality gates**: Run checks when PRs are opened or updated
+
+## Patterns in This Section
+
+- **[IssueOps](/gh-aw/examples/issue-pr-events/issueops/)** - Automate issue triage and management
+- **[LabelOps](/gh-aw/examples/issue-pr-events/labelops/)** - Use labels as workflow triggers
+- **[Triage & Analysis](/gh-aw/examples/issue-pr-events/triage-analysis/)** - Intelligent triage and problem investigation
+- **[Coding & Development](/gh-aw/examples/issue-pr-events/coding-development/)** - PR assistance and code improvements
+- **[Quality & Testing](/gh-aw/examples/issue-pr-events/quality-testing/)** - Automated quality checks
+
+## Example Event Triggers
+
+```yaml
+on:
+  issues:
+    types: [opened, labeled]
+```
+
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize]
+```
+
+```yaml
+on:
+  pull_request_target:
+    types: [labeled]
+    branches: [main]
+```
+
+## Quick Start
+
+Add event-triggered workflows to your repository:
+
+```bash
+gh aw add githubnext/agentics/issue-triage
+gh aw add githubnext/agentics/pr-assistant
+```
diff --git a/...ontent/docs/samples/coding-development.md → ...les/issue-pr-events/coding-development.md b/...ontent/docs/samples/coding-development.md → ...les/issue-pr-events/coding-development.md
@@ -1,12 +1,19 @@
 ---
-title: Coding & Development 
-description: Automated workflows for dependency management, documentation updates, and pull request assistance
+title: Coding & Development
+description: PR assistance, dependency updates, and documentation maintenance - automated development help
 sidebar:
-  order: 300
+  badge: { text: 'Event-triggered', variant: 'success' }
 ---
 
 Coding and development workflows streamline common development tasks through intelligent automation, reducing manual overhead and improving code quality. You can write your own workflows tailored to your specific technology stack and development practices.
 
+## When to Use Coding & Development Workflows
+
+- **PR assistance** - Automated code review suggestions
+- **Dependency updates** - Smart package upgrade proposals
+- **Documentation sync** - Keep docs in sync with code changes
+- **Code generation** - Automated boilerplate or tests
+
 ## Sample Workflows
 
 ### Daily Dependency Updater

diff --git a/docs/src/content/docs/guides/issueops.md → ...docs/examples/issue-pr-events/issueops.md b/docs/src/content/docs/guides/issueops.md → ...docs/examples/issue-pr-events/issueops.md
@@ -1,11 +1,20 @@
 ---
 title: IssueOps
-description: Learn how to implement IssueOps workflows using GitHub Agentic Workflows with issue created triggers and automated comment responses for streamlined issue management.
+description: Automate issue triage, categorization, and responses when issues are opened - fully automated issue management
+sidebar:
+  badge: { text: 'Event-triggered', variant: 'success' }
 ---
 
 IssueOps transforms GitHub issues into powerful automation triggers that automatically analyze, categorize, and respond to issues as they're created. GitHub Agentic Workflows makes IssueOps natural through issue creation triggers and safe comment outputs that handle automated responses securely without requiring write permissions for the main AI job.
 
-## Overview
+## When to Use IssueOps
+
+- **Auto-triage new issues** - Classify and label issues automatically
+- **Smart routing** - Tag relevant team members based on content
+- **Initial responses** - Welcome contributors, ask clarifying questions
+- **Quality checks** - Ensure issues have required information
+
+## How It Works
 
 Through issue triggers, workflows activate automatically when new issues are created in your repository. The AI agent analyzes the issue content, applies your defined logic, and provides intelligent responses through automated comments.
 

diff --git a/docs/src/content/docs/guides/labelops.md → ...docs/examples/issue-pr-events/labelops.md b/docs/src/content/docs/guides/labelops.md → ...docs/examples/issue-pr-events/labelops.md
@@ -1,13 +1,18 @@
 ---
 title: LabelOps
-description: Learn how to use GitHub labels as workflow triggers with AI-powered automation for intelligent issue and pull request management using label filtering.
+description: Workflows triggered by label changes - automate actions when specific labels are added or removed
+sidebar:
+  badge: { text: 'Event-triggered', variant: 'success' }
 ---
 
 LabelOps uses GitHub labels for workflow triggers, metadata, and state markers. GitHub Agentic Workflows supports LabelOps through label-based triggers with filtering, allowing workflows to activate only for specific label changes while maintaining secure, automated responses.
 
-## Overview
+## When to Use LabelOps
 
-LabelOps transforms GitHub labels into workflow triggers, metadata, and state markers. When combined with AI-driven automation, labels enable intelligent, event-driven issue and pull request management that reduces manual effort and accelerates triage.
+- **Priority-based workflows** - Run checks when `priority: high` is added
+- **Stage transitions** - Trigger actions when moving between workflow states
+- **Specialized processing** - Different workflows for different label categories
+- **Team coordination** - Automate handoffs between teams using labels
 
 ## Label Filtering
 
@@ -127,6 +132,6 @@ Schedule periodic label audits to identify duplicates, unused labels, inconsiste
 ## Additional Resources
 
 - [Trigger Events](/gh-aw/reference/triggers/) - Complete trigger configuration including label filtering
-- [IssueOps Guide](/gh-aw/guides/issueops) - Learn about issue-triggered workflows
-- [Safe Outputs Reference](/gh-aw/reference/safe-outputs) - Secure output handling
-- [Frontmatter Reference](/gh-aw/reference/frontmatter) - Complete workflow configuration options
+- [IssueOps Guide](/gh-aw/examples/issue-pr-events/issueops/) - Learn about issue-triggered workflows
+- [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Secure output handling
+- [Frontmatter Reference](/gh-aw/reference/frontmatter/) - Complete workflow configuration options
diff --git a/...c/content/docs/samples/quality-testing.md → ...amples/issue-pr-events/quality-testing.md b/...c/content/docs/samples/quality-testing.md → ...amples/issue-pr-events/quality-testing.md
@@ -1,12 +1,19 @@
 ---
 title: Quality & Testing
-description: Automated workflows for test coverage improvement and performance optimization
+description: Test coverage improvements and performance optimization - automated quality enhancements
 sidebar:
-  order: 400
+  badge: { text: 'Event-triggered', variant: 'success' }
 ---
 
 Quality and testing workflows automate test coverage analysis, performance optimization, and systematic quality improvements.
 
+## When to Use Quality & Testing Workflows
+
+- **Test coverage** - Daily incremental test improvements
+- **Performance checks** - Automated performance regression detection
+- **Quality gates** - Enforce standards on PRs
+- **Systematic improvements** - Gradual quality enhancements
+
 ### Daily Test Coverage Improver
 
 Analyzes test coverage, identifies gaps, and creates PRs with comprehensive tests to systematically improve code quality and reduce bugs. [Learn more](https://github.com/githubnext/agentics/blob/main/docs/daily-test-improver.md)

diff --git a/...c/content/docs/samples/triage-analysis.md → ...amples/issue-pr-events/triage-analysis.md b/...c/content/docs/samples/triage-analysis.md → ...amples/issue-pr-events/triage-analysis.md
@@ -1,12 +1,19 @@
 ---
 title: Triage & Analysis
-description: Intelligent automation for issue management, accessibility reviews, and CI failure investigation
+description: Automated issue triage, accessibility reviews, and CI failure investigation - intelligent problem analysis
 sidebar:
-  order: 200
+  badge: { text: 'Event-triggered', variant: 'success' }
 ---
 
 Triage and analysis workflows provide intelligent automation for managing issues, investigating problems, and ensuring quality standards.
 
+## When to Use Triage & Analysis Workflows
+
+- **Auto-triage issues** - Classify and prioritize incoming issues
+- **Accessibility audits** - Automated a11y checks on PRs
+- **CI failure analysis** - Investigate and explain test failures
+- **Problem investigation** - Deep dive into reported issues
+
 Here are sample workflows from the Agentics collection you can customize for your project:
 
 ### Issue Triage