diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
index 664b68198ad..61fd5452093 100644
--- 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.
+
+
+
+ Write workflows in markdown with natural language instructions instead of complex code.
+
+
+ AI agents understand context, make decisions, and take actions based on repository activity.
+
+
+ Read-only permissions by default with write operations through sanitized safe-outputs.
+
+
+ Built on top of GitHub Actions with familiar triggers, permissions, and workflow syntax.
+
+
+
+## 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
+
+
+
+ Install, compile, and manage workflows with the `gh aw` CLI extension.
+
+
+ Support for Claude, Codex, and custom AI engines with configurable models.
+
+
+ Create issues, comments, and PRs without giving workflows write permissions.
+
+
+ Connect to external tools and services via Model Context Protocol.
+
+
+ Comprehensive frontmatter options for triggers, permissions, and tools.
+
+
+ Special slash commands and mention triggers for interactive workflows.
+
+
+
+## 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
-
- Edit `src/content/docs/index.mdx` to see this page change.
+
+ [Get your first workflow running](/reference/quick-start/) in minutes with our step-by-step guide.
-
- Add Markdown or MDX files to `src/content/docs` to create new pages.
+
+ [Understand the core concepts](/reference/concepts/) behind agentic workflows and AI automation.
-
- Edit your `sidebar` and other config in `astro.config.mjs`.
+
+ [Explore sample workflows](/reference/samples/) for research, development, and automation.
-
- Learn more in [the Starlight Docs](https://starlight.astro.build/).
+
+ [Master the commands](/reference/commands/) for managing workflows with the GitHub CLI.
diff --git a/docs/src/content/docs/reference/command-triggers.md b/docs/src/content/docs/reference/command-triggers.md
index cd082e216dd..fb145bf8155 100644
--- 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
index 6da3fde8121..698efcd8c71 100644
--- 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
index 8cb94572e82..107aedc6fa6 100644
--- 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
index 15a3650a498..b8950903388 100644
--- 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
index 784103fe4fd..6b3dc41ec94 100644
--- 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
index bd51b6f1bb9..734491a6d5b 100644
--- 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
index 245b88fa05c..5728aa61ec5 100644
--- 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
index cf7e3107e70..b3cd7c49d75 100644
--- 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
index 99fa65b104e..458a670a4b2 100644
--- 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
index 7040f0428e1..e3773c374a9 100644
--- 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
index d6cc44b7704..026ff7e3554 100644
--- 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
index 39d45bcff6f..78ab444b718 100644
--- 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
index 2b01295655f..548a31a3203 100644
--- 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
index 2c54a34096c..64fc7f69c64 100644
--- 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
index 9fe57fa7021..04eed49ff15 100644
--- 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.