github · pelikhan · Jan 1, 2026 · Jan 1, 2026 · Jan 1, 2026 · Jan 1, 2026
diff --git a/docs/src/content/docs/guides/getting-started-mcp.md b/docs/src/content/docs/guides/getting-started-mcp.md
@@ -5,11 +5,11 @@ sidebar:
   order: 2
 ---
 
-This guide walks you through integrating Model Context Protocol (MCP) servers with GitHub Agentic Workflows, from your first configuration to advanced patterns.
+This guide walks you through integrating [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) servers with GitHub Agentic Workflows, from your first configuration to advanced patterns.
 
 ## What is MCP?
 
-Model Context Protocol (MCP) is a standardized protocol that enables AI agents to connect to external tools, databases, and APIs. MCP servers act as specialized adapters, giving agents access to GitHub, web search, databases, and third-party services like Notion, Slack, and Datadog.
+[Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) is a standardized protocol that enables AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems) to connect to external tools, databases, and APIs. [MCP servers](/gh-aw/reference/glossary/#mcp-server) act as specialized adapters, giving agents access to GitHub, web search, databases, and third-party services like Notion, Slack, and Datadog.
 
 ## Quick Start
 
@@ -37,7 +37,7 @@ tools:
 Analyze the issue and provide a summary of similar existing issues.
 ```
 
-The `toolsets: [default]` configuration gives your agent access to repository, issue, and pull request tools.
+The `toolsets: [default]` configuration gives your [agent](/gh-aw/reference/glossary/#agent) (the AI system executing the workflow) access to repository, issue, and pull request tools.
 
 ### Step 2: Compile and Test
 
@@ -53,7 +53,7 @@ Verify the MCP configuration:
 gh aw mcp inspect my-workflow
 ```
 
-You now have a working MCP integration. The agent can read issues, search repositories, and access pull request information.
+You now have a working MCP integration. The [agent](/gh-aw/reference/glossary/#agent) can read issues, search repositories, and access pull request information.
 
 ## Configuration Patterns
 

diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -44,15 +44,15 @@ import FeatureGrid from '../../components/FeatureGrid.astro';
 
 ## What is GitHub Agentic Workflows?
 
-GitHub Agentic Workflows transforms how you automate your repository. Instead of writing complex YAML configurations, you describe your automation goals in plain markdown. AI agents then execute these workflows safely with built-in security controls, making intelligent decisions based on context.
+GitHub Agentic Workflows transforms how you automate your repository. Instead of writing complex YAML configurations, you describe your automation goals in plain markdown. AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems that can understand and execute instructions) then execute these workflows safely with built-in security controls, making intelligent decisions based on context.
 
 **Perfect for:**
 - 🤖 **Issue triage** - Automatically categorize, label, and respond to new issues
 - 🔍 **PR reviews** - Get AI-powered code reviews and suggestions
 - 🔧 **Repository maintenance** - Automate dependency updates, documentation, and cleanup tasks
 
 **Security built-in:**  
-Workflows run with read-only permissions by default. Write operations require explicit approval through sanitized safe-outputs, with sandboxed execution, tool allowlisting, and network isolation ensuring AI agents operate safely within controlled boundaries.
+Workflows run with read-only permissions by default. Write operations require explicit approval through sanitized [safe outputs](/gh-aw/reference/glossary/#safe-outputs) (pre-approved GitHub operations), with sandboxed execution, tool allowlisting, and network isolation ensuring AI agents operate safely within controlled boundaries.
 
 ## Key Features
 

diff --git a/docs/src/content/docs/introduction/how-it-works.mdx b/docs/src/content/docs/introduction/how-it-works.mdx
@@ -5,11 +5,11 @@ sidebar:
   order: 2
 ---
 
-GitHub Agentic Workflows enable AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems that can make decisions) to perform complex, multi-step tasks automatically with your team. Built on [GitHub Actions](https://docs.github.com/en/actions), they use [**GitHub Copilot**](/gh-aw/reference/engines/#github-copilot-cli) (or experimental engines like Claude and Codex) to interpret natural language instructions and enable [Continuous AI](https://githubnext.com/projects/continuous-ai) — systematic, automated application of AI to software collaboration.
+GitHub Agentic Workflows enable AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems that can make decisions) to perform complex, multi-step tasks automatically with your team. Built on [GitHub Actions](https://docs.github.com/en/actions), they use [**GitHub Copilot**](/gh-aw/reference/engines/#github-copilot-cli) (or experimental [engines](/gh-aw/reference/glossary/#engine), which are AI models/providers like Claude and Codex) to interpret natural language instructions and enable [Continuous AI](https://githubnext.com/projects/continuous-ai) — systematic, automated application of AI to software collaboration.
 
 ## Workflow Structure
 
-Each workflow contains [frontmatter](/gh-aw/reference/glossary/#frontmatter) (YAML configuration section) and markdown instructions. The frontmatter defines [triggers](/gh-aw/reference/triggers/), [permissions](/gh-aw/reference/permissions/), and [tools](/gh-aw/reference/tools/), while the markdown contains natural language task descriptions. This declarative structure enables reliable, secure agentic programming by sandboxing AI capabilities and triggering at the right moments.
+Each workflow contains [frontmatter](/gh-aw/reference/glossary/#frontmatter) (the YAML configuration section between `---` markers) and markdown instructions. The frontmatter defines [triggers](/gh-aw/reference/triggers/) (when the workflow runs), [permissions](/gh-aw/reference/permissions/) (what it can access), and [tools](/gh-aw/reference/tools/) (what capabilities the AI has), while the markdown contains natural language task descriptions. This declarative structure enables reliable, secure agentic programming by sandboxing AI capabilities and triggering at the right moments.
 
 ```aw warp
 ---
@@ -27,13 +27,13 @@ Workflows support **GitHub Copilot** (default), **Claude Code**, and **Codex**.
 
 ## Tools and Model Context Protocol (MCP)
 
-Workflows use [tools](/gh-aw/reference/tools/) through the **[Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol)** (MCP, a standard for AI tool integration) — a standardized protocol for connecting AI agents to external tools and services — for GitHub operations, external APIs, file operations, and custom integrations.
+Workflows use [tools](/gh-aw/reference/tools/) through the **[Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol)** (MCP, a standardized protocol for connecting AI agents to external tools and services) for GitHub operations, external APIs, file operations, and custom integrations.
 
 ## Agentic vs. Traditional Workflows
 
 **Traditional workflows** execute pre-programmed steps with fixed if/then logic. They do exactly what you tell them, every time, in the same way.
 
-**[Agentic workflows](/gh-aw/reference/glossary/#agentic)** use AI to understand context, make decisions, and generate content by interpreting natural language instructions flexibly. They combine deterministic GitHub Actions infrastructure with AI-driven decision-making, adapting their behavior based on the specific situation they encounter.
+**[Agentic workflows](/gh-aw/reference/glossary/#agentic)** (workflows that have agency—the ability to make autonomous decisions) use AI to understand context, make decisions, and generate content by interpreting natural language instructions flexibly. They combine deterministic GitHub Actions infrastructure with AI-driven decision-making, adapting their behavior based on the specific situation they encounter.
 
 ## Security Design
 
@@ -57,12 +57,12 @@ Workflows run with minimal permissions (no write access by default), use tool al
 
 ## Compilation
 
-Use `gh aw compile` to generate `.lock.yml` files (compiled GitHub Actions workflow files) from workflow `.md` files. The `.md` file is the editable source of truth, while `.lock.yml` is the compiled GitHub Actions workflow with security hardening. Commit both files.
+Use `gh aw compile` to generate [`.lock.yml` files](/gh-aw/reference/glossary/#workflow-lock-file-lockyml) (compiled GitHub Actions workflow files) from workflow `.md` files. The `.md` file is the editable source of truth, while `.lock.yml` is the compiled GitHub Actions workflow with security hardening. Commit both files.
 
 ## Continuous AI Patterns
 
 Enable [Continuous AI](https://githubnext.com/projects/continuous-ai) patterns like keeping documentation current, improving code quality incrementally, intelligently triaging issues and PRs, and automating code review.
 
 ## Best Practices
 
-Start simple and iterate with clear, specific instructions. Test workflows using `gh aw compile --watch` and `gh aw run`, monitor costs with `gh aw logs`, and review AI-generated content before merging. Use [`safe outputs`](/gh-aw/reference/safe-outputs/) (validated GitHub operations) for controlled creation of issues, comments, and PRs.
+Start simple and iterate with clear, specific instructions. Test workflows using `gh aw compile --watch` and `gh aw run`, monitor costs with `gh aw logs`, and review AI-generated content before merging. Use [`safe outputs`](/gh-aw/reference/safe-outputs/) (pre-approved GitHub operations) for controlled creation of issues, comments, and PRs.
diff --git a/docs/src/content/docs/introduction/overview.mdx b/docs/src/content/docs/introduction/overview.mdx
@@ -7,16 +7,16 @@ sidebar:
 
 ## What are Agentic Workflows?
 
-**Agentic workflows** are AI-powered automation that can understand context, make decisions, and take meaningful actions—all from natural language instructions you write in markdown.
+**[Agentic workflows](/gh-aw/reference/glossary/#agentic-workflow)** (AI-powered workflows that can make decisions and adapt to situations) are AI-powered automation that can understand context, make decisions, and take meaningful actions—all from natural language instructions you write in markdown.
 
-Unlike traditional automation with fixed if-then rules, agentic workflows use AI [agents](/gh-aw/reference/glossary/#agent) (AI systems that execute instructions) like GitHub Copilot to:
+Unlike traditional automation with fixed if-then rules, agentic workflows use AI [agents](/gh-aw/reference/glossary/#agent) (AI systems that execute your instructions) like GitHub Copilot to:
 - **Understand context**: Read your repository, issues, and pull requests to grasp the current situation
 - **Make decisions**: Choose appropriate actions based on the context, not just predefined conditions
 - **Adapt behavior**: Respond flexibly to different scenarios without requiring explicit programming for each case
 
 ## Natural Language to GitHub Actions
 
-Imagine describing your automation needs in plain language instead of wrestling with complex YAML syntax and API calls. GitHub Agentic Workflows makes this possible by transforming natural language markdown files into [GitHub Actions](https://github.com/features/actions) that are executed by AI [agents](/gh-aw/reference/glossary/#agent) (AI systems that execute instructions).
+Imagine describing your automation needs in plain language instead of wrestling with complex YAML syntax and API calls. GitHub Agentic Workflows makes this possible by transforming natural language markdown files into [GitHub Actions](https://github.com/features/actions) that are executed by AI [agents](/gh-aw/reference/glossary/#agent) (AI systems that execute your instructions).
 
 Instead of writing intricate scripts to handle issue triage, code reviews, or release management, you simply describe what you want to happen. The AI agent understands your repository context, interprets the situation, and takes appropriate actions—all from a few lines of markdown.
 
@@ -36,7 +36,7 @@ safe-outputs:
 Analyze the current issue and ask for additional details if the issue is unclear.
 ```
 
-The `gh aw compile` command transforms this markdown into a secure [GitHub Actions Workflow](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows#about-workflows) (`.lock.yml` file) that runs an AI agent in a containerized environment whenever a new issue is opened. 
+The `gh aw compile` command transforms this markdown into a secure [GitHub Actions Workflow](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows#about-workflows) ([`.lock.yml` file](/gh-aw/reference/glossary/#workflow-lock-file-lockyml), the compiled workflow that GitHub Actions runs) that runs an AI agent in a containerized environment whenever a new issue is opened. 
 
 [Compilation](/gh-aw/reference/glossary/#compilation) (converting markdown to GitHub Actions YAML) validates your configuration, applies security hardening, and generates the final workflow file that GitHub Actions can execute. Think of it like compiling code—you write human-friendly markdown, the compiler produces machine-ready YAML.
 

diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
@@ -5,15 +5,15 @@ sidebar:
   order: 600
 ---
 
-GitHub Agentic Workflows support multiple AI [engines](/gh-aw/reference/glossary/#engine) (AI model/provider) to interpret and execute natural language instructions. Each engine has unique capabilities and configuration options.
+GitHub Agentic Workflows support multiple AI [engines](/gh-aw/reference/glossary/#engine) (which AI model/provider to use) to interpret and execute natural language instructions. Each engine has unique capabilities and configuration options.
 
 :::note[Experimental Engines]
 Claude and Codex engines are available but marked as experimental. They are not documented here but can still be used by setting `engine: claude` or `engine: codex` in your workflow frontmatter. For production workflows, we recommend using the GitHub Copilot CLI engine.
 :::
 
 ### GitHub Copilot CLI
 
-GitHub Copilot is the default and recommended AI engine for most workflows. The [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) provides [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) server support and is designed for conversational AI workflows.
+GitHub Copilot is the default and recommended AI [engine](/gh-aw/reference/glossary/#engine) (which AI model/provider to use) for most workflows. The [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) provides [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP, the standardized protocol for connecting AI agents to tools) server support and is designed for conversational AI workflows.
 
 ```yaml wrap
 engine: copilot
@@ -33,7 +33,7 @@ Configuration options: `model` (gpt-5 or claude-sonnet-4), `version` (CLI versio
 
 #### Required Secrets
 
-**`COPILOT_GITHUB_TOKEN`**: GitHub Personal Access Token (PAT) with "Copilot Requests" permission. **`GH_AW_GITHUB_TOKEN`** (optional): Required for [GitHub Tools Remote Mode](/gh-aw/reference/tools/#modes-and-restrictions).
+**`COPILOT_GITHUB_TOKEN`**: GitHub [Personal Access Token](/gh-aw/reference/glossary/#personal-access-token-pat) (PAT, a token that authenticates you to GitHub's APIs) with "Copilot Requests" permission. **`GH_AW_GITHUB_TOKEN`** (optional): Required for [GitHub Tools Remote Mode](/gh-aw/reference/tools/#modes-and-restrictions).
 
 #### Authenticating with a Personal Access Token (PAT)
 

diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
@@ -5,7 +5,7 @@ sidebar:
   order: 200
 ---
 
-The [frontmatter](/gh-aw/reference/glossary/#frontmatter) (YAML configuration section) of GitHub Agentic Workflows includes the triggers, permissions, AI engines, and workflow settings. For example:
+The [frontmatter](/gh-aw/reference/glossary/#frontmatter) (YAML configuration section between `---` markers) of GitHub Agentic Workflows includes the triggers, permissions, AI [engines](/gh-aw/reference/glossary/#engine) (which AI model/provider to use), and workflow settings. For example:
 
 ```yaml wrap
 ---
@@ -24,7 +24,7 @@ tools:
 
 The frontmatter combines standard GitHub Actions properties (`on`, `permissions`, `run-name`, `runs-on`, `timeout-minutes`, `concurrency`, `env`, `environment`, `container`, `services`, `if`, `steps`, `cache`) with GitHub Agentic Workflows-specific elements (`description`, `source`, `github-token`, `imports`, `engine`, `strict`, `roles`, `features`, `safe-inputs`, `safe-outputs`, `network`, `tools`).
 
-Tool configurations (such as `bash`, `edit`, `github`, `web-fetch`, `web-search`, `playwright`, `cache-memory`, and custom [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) servers) are specified under the `tools:` key. Custom inline tools can be defined with the [`safe-inputs:`](/gh-aw/reference/safe-inputs/) (validated user input tools) key. See [Tools](/gh-aw/reference/tools/) and [Safe Inputs](/gh-aw/reference/safe-inputs/) for complete documentation.
+Tool configurations (such as `bash`, `edit`, `github`, `web-fetch`, `web-search`, `playwright`, `cache-memory`, and custom [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) [servers](/gh-aw/reference/glossary/#mcp-server)) are specified under the `tools:` key. Custom inline tools can be defined with the [`safe-inputs:`](/gh-aw/reference/safe-inputs/) (custom tools defined inline) key. See [Tools](/gh-aw/reference/tools/) and [Safe Inputs](/gh-aw/reference/safe-inputs/) for complete documentation.
 
 ### Trigger Events (`on:`)
 

diff --git a/docs/src/content/docs/reference/glossary.md b/docs/src/content/docs/reference/glossary.md
@@ -7,6 +7,10 @@ sidebar:
 
 This glossary provides definitions for key technical terms and concepts used in GitHub Agentic Workflows.
 
+:::tip[New to GitHub Agentic Workflows?]
+Technical terms throughout the documentation link to their definitions here. Click any glossary link to understand unfamiliar concepts. Bookmark this page for quick reference!
+:::
+
 ## Core Concepts
 
 ### Agentic
@@ -125,9 +129,12 @@ safe-outputs:
 ## Workflow Components
 
 ### Engine
-The AI system that powers the agentic workflow. GitHub Agentic Workflows supports multiple engines:
+
+The AI system that powers the [agentic workflow](#agentic-workflow). GitHub Agentic Workflows supports multiple engines:
 - **GitHub Copilot** (default): Uses GitHub's coding assistant
 
+An engine is essentially "which AI to use"—think of it as choosing between different AI assistants (like Copilot, Claude, or others) to execute your workflow instructions.
+
 ### Triggers
 Events that cause a workflow to run. Defined in the `on:` section of frontmatter. Includes issue events (`issues:`), pull request events (`pull_request:`), scheduled runs (`schedule:`), manual runs (`workflow_dispatch:`), and comment commands (`slash_command:`).