github · pelikhan · Dec 28, 2025 · Dec 27, 2025 · Dec 27, 2025 · Dec 27, 2025
diff --git a/docs/src/content/docs/examples/comment-triggered/chatops.md b/docs/src/content/docs/examples/comment-triggered/chatops.md
@@ -38,7 +38,7 @@ Examine the diff for potential bugs, security vulnerabilities, performance impli
 Create specific review comments on relevant lines of code and add a summary comment with overall observations and recommendations.
 ```
 
-When someone types `/review`, the AI analyzes code changes and posts review comments. The agent runs with read-only permissions while safe outputs handle write operations securely.
+When someone types `/review`, the AI analyzes code changes and posts review comments. The agent runs with read-only permissions while [safe-outputs](/gh-aw/reference/safe-outputs/) (validated GitHub operations) handle write operations securely.
 
 ## Filtering Command Events
 

diff --git a/docs/src/content/docs/examples/issue-pr-events/issueops.md b/docs/src/content/docs/examples/issue-pr-events/issueops.md
@@ -5,7 +5,7 @@ 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.
+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-outputs](/gh-aw/reference/safe-outputs/) (validated GitHub operations) that handle automated responses securely without requiring write permissions for the main AI job.
 
 ## When to Use IssueOps
 

diff --git a/docs/src/content/docs/examples/scheduled/dailyops.md b/docs/src/content/docs/examples/scheduled/dailyops.md
@@ -44,6 +44,8 @@ safe-outputs:
     category: "ideas"
 ```
 
+The [`safe-outputs:`](/gh-aw/reference/safe-outputs/) (validated GitHub operations) configuration lets the AI request discussion creation without requiring write permissions.
+
 ### Discussion Comments
 
 For workflows that post updates to an existing discussion, use `add-comment` with `discussion: true` and a specific `target` discussion number:

diff --git a/docs/src/content/docs/guides/mcps.md b/docs/src/content/docs/guides/mcps.md
@@ -5,11 +5,11 @@ sidebar:
   order: 4
 ---
 
-This guide covers using Model Context Protocol (MCP) servers with GitHub Agentic Workflows.
+This guide covers using [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) servers with GitHub Agentic Workflows.
 
 ## What is MCP?
 
-Model Context Protocol (MCP) is a standardized protocol that allows AI agents to securely connect to external tools, databases, and services. GitHub Agentic Workflows uses MCP to integrate databases and APIs, extend AI capabilities with specialized functionality, maintain standardized security controls, and enable composable workflows by mixing multiple MCP servers.
+[Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP, a standard for AI tool integration) is a standardized protocol that allows AI agents to securely connect to external tools, databases, and services. GitHub Agentic Workflows uses MCP to integrate databases and APIs, extend AI capabilities with specialized functionality, maintain standardized security controls, and enable composable workflows by mixing multiple MCP servers.
 
 ## Quick Start
 

diff --git a/docs/src/content/docs/introduction/how-it-works.mdx b/docs/src/content/docs/introduction/how-it-works.mdx
@@ -9,7 +9,7 @@ GitHub Agentic Workflows enable AI [agents](/gh-aw/reference/glossary/#agent) (a
 
 ## Workflow Structure
 
-Each workflow contains YAML frontmatter (the configuration section between `---` markers) 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) (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.
 
 ```aw warp
 ---
@@ -23,11 +23,11 @@ Analyze this issue and provide helpful triage comments...
 
 ## AI Engines
 
-Workflows support **GitHub Copilot** (default), **Claude Code**, and **Codex**. Each [engine](/gh-aw/reference/engines/) interprets natural language instructions and executes them using configured tools and permissions.
+Workflows support **GitHub Copilot** (default), **Claude Code**, and **Codex**. Each [engine](/gh-aw/reference/engines/) (AI model/provider) interprets natural language instructions and executes them using configured tools and permissions.
 
 ## Tools and Model Context Protocol (MCP)
 
-Workflows use [tools](/gh-aw/reference/tools/) through the **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.
+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.
 
 ## Agentic vs. Traditional Workflows
 
@@ -50,6 +50,11 @@ flowchart LR
 
 Workflows run with minimal permissions (no write access by default), use tool allowlists, and process outputs through a [safety layer](/gh-aw/guides/security/) before applying changes. Critical actions can require human approval. For detailed security documentation, see the [Security Architecture](/gh-aw/introduction/architecture/) page.
 
+## Safe Inputs and Safe Outputs
+
+- **[Safe inputs](/gh-aw/reference/safe-inputs/)** (validated user input tools) — Custom MCP tools defined inline to prevent injection attacks
+- **[Safe outputs](/gh-aw/reference/safe-outputs/)** (validated GitHub operations) — Pre-approved actions the AI can request without write permissions
+
 ## 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.
@@ -60,4 +65,4 @@ Enable [Continuous AI](https://githubnext.com/projects/continuous-ai) patterns l
 
 ## 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/) 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/) (validated 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
@@ -9,14 +9,14 @@ sidebar:
 
 **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.
 
-Unlike traditional automation with fixed if-then rules, agentic workflows use AI agents (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 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 (the AI that executes your workflow 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 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.
 
@@ -38,10 +38,10 @@ 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. 
 
-[Compilation](/gh-aw/reference/glossary/#compilation) (the process of 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.
+[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.
 
 The AI agent reads your repository context, understands the issue content, and takes appropriate actions - all defined in natural language rather than complex code.
 
-Workflows use read-only permissions by default, with write operations only allowed through sanitized [`safe-outputs`](/gh-aw/reference/safe-outputs/) (a security feature that enables creating issues, comments, and PRs without giving the AI direct write access). Access can be gated to team members only, ensuring AI agents operate within controlled boundaries.
+Workflows use read-only permissions by default, with write operations only allowed through sanitized [`safe-outputs`](/gh-aw/reference/safe-outputs/) (validated GitHub operations) that enable creating issues, comments, and PRs without giving the AI direct write access. Access can be gated to team members only, ensuring AI agents operate within controlled boundaries.
 
 More sample workflows can be found in the [Agentics collection](https://github.com/githubnext/agentics).
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) (coding agents) 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) (AI model/provider) 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 (MCP) server support and is designed for conversational AI workflows.
+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.
 
 ```yaml wrap
 engine: copilot

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 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) of GitHub Agentic Workflows includes the triggers, permissions, AI engines, 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 (MCP) servers) are specified under the `tools:` key. Custom inline tools can be defined with the `safe-inputs:` 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) 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.
 
 ### Trigger Events (`on:`)
 

diff --git a/docs/src/content/docs/reference/safe-inputs.md b/docs/src/content/docs/reference/safe-inputs.md
@@ -9,7 +9,7 @@ sidebar:
 Safe Inputs is an experimental feature. The API and behavior may change in future releases.
 :::
 
-The `safe-inputs:` element allows you to define custom MCP (Model Context Protocol) tools directly in your workflow frontmatter using JavaScript, shell scripts, or Python. These tools are generated at runtime and mounted as an MCP server, giving your agent access to custom functionality with controlled secret access.
+The [`safe-inputs:`](/gh-aw/reference/glossary/#safe-inputs) (validated user input tools) element allows you to define custom [MCP](/gh-aw/reference/glossary/#mcp-model-context-protocol) (Model Context Protocol) tools directly in your workflow [frontmatter](/gh-aw/reference/glossary/#frontmatter) using JavaScript, shell scripts, or Python. These tools are generated at runtime and mounted as an MCP server, giving your agent access to custom functionality with controlled secret access.
 
 ## Quick Start
 

diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md
@@ -5,7 +5,7 @@ sidebar:
   order: 800
 ---
 
-The [`safe-outputs:`](/gh-aw/reference/glossary/#safe-outputs) element of your workflow's frontmatter declares that your agentic workflow should conclude with optional automated actions based on the agentic workflow's output. This enables your workflow to write content that is then automatically processed to create GitHub issues, comments, pull requests, or add labels—all without giving the agentic portion of the workflow any write permissions.
+The [`safe-outputs:`](/gh-aw/reference/glossary/#safe-outputs) (validated GitHub operations) element of your workflow's [frontmatter](/gh-aw/reference/glossary/#frontmatter) declares that your agentic workflow should conclude with optional automated actions based on the agentic workflow's output. This enables your workflow to write content that is then automatically processed to create GitHub issues, comments, pull requests, or add labels—all without giving the agentic portion of the workflow any write permissions.
 
 ## Why Safe Outputs?
 

diff --git a/docs/src/content/docs/reference/tools.md b/docs/src/content/docs/reference/tools.md
@@ -67,7 +67,7 @@ tools:
 ### GitHub Toolsets
 
 :::tip[Use Toolsets Instead of Allowed]
-Toolsets provide a stable API across MCP server versions and automatically include new related tools. See [Migration from Allowed to Toolsets](/gh-aw/guides/mcps/#migration-from-allowed-to-toolsets) for guidance.
+[Toolsets](/gh-aw/reference/glossary/#toolsets) (capability collections) provide a stable API across MCP server versions and automatically include new related tools. See [Migration from Allowed to Toolsets](/gh-aw/guides/mcps/#migration-from-allowed-to-toolsets) for guidance.
 :::
 
 Enable specific API groups to improve tool selection and reduce context size:

diff --git a/docs/src/content/docs/setup/agentic-authoring.mdx b/docs/src/content/docs/setup/agentic-authoring.mdx
@@ -20,7 +20,7 @@ gh aw init
 
 This creates:
 - `.github/aw/github-agentic-workflows.instructions.md` - Custom Copilot instructions for better workflow authoring
-- `.github/agents/create-agentic-workflow.agent.md` - Agent for the `/agent create-agentic-workflow` command in Copilot Chat
+- `.github/agents/create-agentic-workflow.agent.md` - [Agent file](/gh-aw/reference/glossary/#agent-files) (custom AI instructions) for the `/agent create-agentic-workflow` command in Copilot Chat
 
 :::tip[VS Code integration]
 Once initialized, GitHub Copilot will automatically use these instructions when you edit workflow files in VS Code. See [VS Code Integration](/gh-aw/setup/vscode/) for more details.

diff --git a/docs/src/content/docs/setup/quick-start.md b/docs/src/content/docs/setup/quick-start.md
@@ -16,7 +16,7 @@ Before installing, ensure you have:
 
 - ✅ **[GitHub CLI](https://cli.github.com/)** v2.0.0+ installed and authenticated (`gh auth login`)
 - ✅ **GitHub account** with admin or write access to a repository
-- ✅ **GitHub Actions** enabled in your repository
+- ✅ **[GitHub Actions](https://docs.github.com/en/actions)** (GitHub's automation platform) enabled in your repository
 - ✅ **Git** installed on your machine
 - ✅ **Operating System:** Linux, macOS, or Windows with WSL
 
@@ -92,7 +92,7 @@ This creates a pull request that adds `.github/workflows/daily-team-status.md` a
 
 ### Step 3 — Add an AI secret
 
-Agentic workflows need to authenticate with an AI service to execute your natural language instructions. By default, they use **GitHub Copilot** as the [coding agent](/gh-aw/reference/glossary/#agent) (the AI that executes your workflow instructions).
+Agentic workflows need to authenticate with an AI service to execute your natural language instructions. By default, they use **GitHub Copilot** as the [coding agent](/gh-aw/reference/glossary/#agent) (the AI system that executes your instructions).
 
 To allow your workflows to use Copilot, you'll create a token and add it as a repository secret.
 
@@ -165,7 +165,9 @@ Once complete, a new issue will be created in your repository with daily news! T
 
 ## Understanding Your First Workflow
 
-The daily team status workflow creates a status report every weekday and posts it as an issue:
+The daily team status workflow creates a status report every weekday and posts it as an issue. The workflow file has two parts:
+- **[Frontmatter](/gh-aw/reference/glossary/#frontmatter)** (YAML configuration section) — The section between `---` markers that configures when the workflow runs and what it can do
+- **Markdown instructions** — Natural language task descriptions for the AI
 
 ```aw wrap
 ---
@@ -198,6 +200,10 @@ Create an upbeat daily status report for the team as a GitHub issue.
 2. Create a new GitHub issue with your findings and insights
 ```
 
+**Key configuration elements:**
+- **[`tools:`](/gh-aw/reference/tools/)** — Capabilities the AI can use (GitHub API access)
+- **[`safe-outputs:`](/gh-aw/reference/safe-outputs/)** (validated GitHub API operations) — Allows creating issues without giving the AI write permissions
+
 ## Customize Your Workflow
 
 Edit the `.md` file and recompile with `gh aw compile`. For AI-assisted customization using GitHub Copilot CLI: