github · Copilot · Sep 11, 2025 · Sep 11, 2025
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -1,36 +1,106 @@
 ---
-title: Welcome to Starlight
-description: Get started building your docs site with Starlight.
+title: GitHub Agentic Workflows
+description: Write agentic workflows in natural language markdown and run them safely in GitHub Actions. From GitHub Next and Microsoft Research.
 template: splash
 hero:
-  tagline: Congrats on setting up a new Starlight project!
+  tagline: Write agentic workflows in natural language markdown, and run them safely in GitHub Actions
   image:
     file: ../../assets/houston.webp
   actions:
-    - text: Example Guide
-      link: /guides/example/
+    - text: Quick Start Guide
+      link: /reference/quick-start/
       icon: right-arrow
-    - text: Read the Starlight docs
-      link: https://starlight.astro.build
+    - text: View on GitHub
+      link: https://github.com/githubnext/gh-aw
       icon: external
       variant: minimal
 ---
 
 import { Card, CardGrid } from '@astrojs/starlight/components';
 
-## Next steps
+## What are GitHub Agentic Workflows?
+
+GitHub Agentic Workflows enable AI agents to perform complex, multi-step tasks in your repository automatically. They combine the power of AI with GitHub's collaboration platform to enable **Continuous AI** — the systematic, automated application of AI to software collaboration.
+
+<CardGrid stagger>
+	<Card title="Natural Language Instructions" icon="pencil">
+		Write workflows in markdown with natural language instructions instead of complex code.
+	</Card>
+	<Card title="AI-Powered Automation" icon="rocket">
+		AI agents understand context, make decisions, and take actions based on repository activity.
+	</Card>
+	<Card title="Secure by Design" icon="shield">
+		Read-only permissions by default with write operations through sanitized safe-outputs.
+	</Card>
+	<Card title="GitHub Actions Integration" icon="github">
+		Built on top of GitHub Actions with familiar triggers, permissions, and workflow syntax.
+	</Card>
+</CardGrid>
+
+## How It Works
+
+Transform natural language workflows into GitHub Actions that are executed by AI agents:
+
+```markdown
+---
+on:
+  issues:
+    types: [opened]
+permissions: read-all 
+safe-outputs:
+  add-issue-comment:
+---
+# Issue Clarifier
+
+Analyze the current issue and ask for additional details if the issue is unclear.
+```
+
+The `gh aw` CLI compiles this into a GitHub Actions workflow that runs an AI agent (Claude, Codex, etc.) whenever a new issue is opened.
+
+## Core Features
+
+<CardGrid>
+	<Card title="🔧 CLI Management" icon="setting">
+		Install, compile, and manage workflows with the `gh aw` CLI extension.
+	</Card>
+	<Card title="🤖 Multiple AI Engines" icon="rocket">
+		Support for Claude, Codex, and custom AI engines with configurable models.
+	</Card>
+	<Card title="🔒 Safe Outputs" icon="shield">
+		Create issues, comments, and PRs without giving workflows write permissions.
+	</Card>
+	<Card title="🔌 MCP Integration" icon="puzzle">
+		Connect to external tools and services via Model Context Protocol.
+	</Card>
+	<Card title="📝 Rich Configuration" icon="list-format">
+		Comprehensive frontmatter options for triggers, permissions, and tools.
+	</Card>
+	<Card title="🎯 Command Triggers" icon="command-palette">
+		Special slash commands and mention triggers for interactive workflows.
+	</Card>
+</CardGrid>
+
+## Ready-to-Use Workflows
+
+Explore sample workflows for common automation tasks:
+
+- **Research & Planning**: Weekly research, team status reports, daily planning, issue triage
+- **Development**: Dependency updates, documentation maintenance, QA tasks, test coverage improvements
+- **Security**: Performance optimization, accessibility reviews, security monitoring
+
+## Get Started
 
 <CardGrid stagger>
-	<Card title="Update content" icon="pencil">
-		Edit `src/content/docs/index.mdx` to see this page change.
+	<Card title="Quick Start" icon="rocket">
+		[Get your first workflow running](/reference/quick-start/) in minutes with our step-by-step guide.
 	</Card>
-	<Card title="Add new content" icon="add-document">
-		Add Markdown or MDX files to `src/content/docs` to create new pages.
+	<Card title="Learn Concepts" icon="open-book">
+		[Understand the core concepts](/reference/concepts/) behind agentic workflows and AI automation.
 	</Card>
-	<Card title="Configure your site" icon="setting">
-		Edit your `sidebar` and other config in `astro.config.mjs`.
+	<Card title="Browse Samples" icon="document">
+		[Explore sample workflows](/reference/samples/) for research, development, and automation.
 	</Card>
-	<Card title="Read the docs" icon="open-book">
-		Learn more in [the Starlight Docs](https://starlight.astro.build/).
+	<Card title="CLI Reference" icon="terminal">
+		[Master the commands](/reference/commands/) for managing workflows with the GitHub CLI.
 	</Card>
 </CardGrid>
diff --git a/docs/src/content/docs/reference/command-triggers.md b/docs/src/content/docs/reference/command-triggers.md
@@ -1,3 +1,8 @@
+---
+title: Command Triggers
+description: Guide for creating workflows that respond to slash commands and mentions in issues and comments using the special command trigger syntax.
+---
+
 # 🏷️ Command Triggers
 
 This guide covers command triggers and context text functionality for agentic workflows.

diff --git a/docs/src/content/docs/reference/commands.md b/docs/src/content/docs/reference/commands.md
@@ -1,3 +1,8 @@
+---
+title: Workflow Management Commands
+description: Complete CLI reference for managing GitHub Agentic Workflows, including installation, compilation, and workflow lifecycle commands.
+---
+
 # 🛠️ Workflow Management Commands
 
 This guide covers all available commands for managing agentic workflows with the GitHub CLI extension.

diff --git a/docs/src/content/docs/reference/concepts.md b/docs/src/content/docs/reference/concepts.md
@@ -1,3 +1,8 @@
+---
+title: Introduction to GitHub Agentic Workflows
+description: Learn about core concepts, AI engines, and how GitHub Agentic Workflows enable AI agents to automate repository tasks through natural language instructions.
+---
+
 # 📖 Introduction to GitHub Agentic Workflows
 
 Now that you've [got your first workflow running](quick-start.md), let's dive deeper into the concepts and capabilities of GitHub Agentic Workflows.

diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
@@ -1,5 +1,6 @@
 ---
 title: Frontmatter Options for GitHub Agentic Workflows
+description: Complete reference guide for YAML frontmatter configuration options in GitHub Agentic Workflows, including triggers, permissions, AI engine settings, network access, and safe outputs.
 ---
 
 This guide covers all available frontmatter configuration options for GitHub Agentic Workflows.

diff --git a/docs/src/content/docs/reference/include-directives.md b/docs/src/content/docs/reference/include-directives.md
@@ -1,3 +1,8 @@
+---
+title: Include Directives
+description: Modularize and reuse workflow components across multiple workflows with include directives for better organization and maintainability.
+---
+
 # 📝 Include Directives
 
 Include directives allow you to modularize and reuse workflow components across multiple workflows.

diff --git a/docs/src/content/docs/reference/index.md b/docs/src/content/docs/reference/index.md
@@ -1,3 +1,8 @@
+---
+title: GitHub Agentic Workflows Documentation
+description: Complete documentation for writing agentic workflows in natural language markdown and running them in GitHub Actions.
+---
+
 # 📖 GitHub Agentic Workflows Documentation
 
 Write agentic workflows in natural language markdown, and run them in GitHub Actions. From [GitHub Next](https://githubnext.com/).

diff --git a/docs/src/content/docs/reference/mcps.md b/docs/src/content/docs/reference/mcps.md
@@ -1,3 +1,8 @@
+---
+title: Model Context Protocol (MCP) Integration
+description: Complete guide for using MCP servers with GitHub Agentic Workflows to connect to external tools, databases, and services securely.
+---
+
 # 🔌 Model Context Protocol (MCP) Integration Guide
 
 This guide covers using Model Context Protocol (MCP) servers with GitHub Agentic Workflows.

diff --git a/docs/src/content/docs/reference/quick-start.md b/docs/src/content/docs/reference/quick-start.md
@@ -1,3 +1,8 @@
+---
+title: Quick Start Guide
+description: Get your first GitHub Agentic Workflow running in minutes with step-by-step installation and setup instructions.
+---
+
 # 🚀 Quick Start — Get your first workflow running
 
 This guide will get you from zero to a running agentic workflow in minutes. You'll install the extension, add a sample workflow, set up the required secrets, and run it.

diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md
@@ -1,3 +1,8 @@
+---
+title: Safe Output Processing
+description: Security feature for creating GitHub issues, comments, and pull requests without giving agentic workflows write permissions, with complete configuration reference.
+---
+
 # 🔒 Safe Output Processing
 
 One of the primary security features of GitHub Agentic Workflows is "safe output processing", enabling the creation of GitHub issues, comments, pull requests, and other outputs without giving the agentic portion of the workflow write permissions.

diff --git a/docs/src/content/docs/reference/samples.md b/docs/src/content/docs/reference/samples.md
@@ -1,3 +1,8 @@
+---
+title: Sample Workflows
+description: Ready-to-use agentic workflow examples for research, development, and automation tasks including weekly research, dependency updates, and QA workflows.
+---
+
 # Sample Workflows
 
 **Demonstrator Research & Planning Workflows**

diff --git a/docs/src/content/docs/reference/secrets.md b/docs/src/content/docs/reference/secrets.md
@@ -1,3 +1,8 @@
+---
+title: Secrets Management
+description: Guide for managing GitHub tokens, AI API keys, and custom secrets in agentic workflows with automatic provisioning and security best practices.
+---
+
 # 🔐 Secrets Management
 
 Agentic workflows automatically handle several types of secrets and support custom secret references.

diff --git a/docs/src/content/docs/reference/security-notes.md b/docs/src/content/docs/reference/security-notes.md
@@ -1,3 +1,8 @@
+---
+title: Security Notes
+description: Security considerations, constraints, and best practices for GitHub Agentic Workflows including sandboxing, permissions, and emerging security controls.
+---
+
 # Security Notes
 
 > [!CAUTION]

diff --git a/docs/src/content/docs/reference/tools.md b/docs/src/content/docs/reference/tools.md
@@ -1,3 +1,8 @@
+---
+title: Tools Configuration
+description: Reference guide for configuring GitHub API tools and AI capabilities available to agentic workflows, including built-in and custom tools.
+---
+
 # 🔧 Tools Configuration
 
 This guide covers the available tools that can be configured in agentic workflows, including GitHub tools and Claude-specific tools.

diff --git a/docs/src/content/docs/reference/vscode.md b/docs/src/content/docs/reference/vscode.md
@@ -1,3 +1,8 @@
+---
+title: Visual Studio Code Integration
+description: Tools and integrations for improving the developer experience when authoring GitHub Agentic Workflows in VS Code and other IDEs.
+---
+
 # Visual Studio Code Integration
 
 The `gh aw` cli provides a few tools to improve your developer experience in Visual Studio Code (or other IDEs).

diff --git a/docs/src/content/docs/reference/workflow-structure.md b/docs/src/content/docs/reference/workflow-structure.md
@@ -1,3 +1,8 @@
+---
+title: Workflow Structure
+description: Learn how agentic workflows are organized, directory structure, file naming conventions, and compilation process within your repository.
+---
+
 # 📋 Workflow Structure
 
 This guide explains how agentic workflows are organized and structured within your repository.