Define jargon terms on first use in documentation

[Copilot]

New users encounter undefined technical terms (frontmatter, MCP, .lock.yml, safe-outputs) before they're explained, creating unnecessary friction.

Changes

Inline definitions added

• quick-start.md: Define .lock.yml (compiled GitHub Actions workflow file), explain frontmatter structure and safe-outputs security model
• how-it-works.mdx: Define frontmatter (configuration section between --- markers), expand MCP to Model Context Protocol with explanation, clarify .lock.yml compilation
• overview.mdx: Define safe-outputs (security feature enabling write operations without direct permissions)

New glossary reference

• reference/glossary.md: Comprehensive term definitions organized by domain (Core Concepts, Tools & Integration, Security & Outputs, Workflow Components, Development & Compilation, Advanced Features)

Visual Impact

Before: Terms used without context

This creates a pull request that adds `.github/workflows/daily-team-status.md` and the compiled `.lock.yml`.

After: Terms defined inline

This creates a pull request that adds `.github/workflows/daily-team-status.md` and the compiled `.lock.yml` (the generated GitHub Actions workflow file).

Quick Start Page

Glossary Reference

Addresses #4257

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[task] Define jargon terms on first use throughout documentation</issue_title>
<issue_description>## Objective
Define technical terms when they are first introduced to reduce cognitive load for beginners.

Context

Terms like "frontmatter", "MCP", "trial mode", and "workflow lock" are used before being explained, creating confusion for new users.

Related to #4257 (Documentation Noob Test Report)

Approach

1. Identify all jargon terms used in Quick Start and Getting Started sections
2. Add inline definitions or tooltips on first use
3. Consider adding a glossary page for reference

Files to Modify

• docs/src/content/docs/setup/quick-start.mdx
• docs/src/content/docs/concepts/how-it-works.mdx
• docs/src/content/docs/overview.mdx
• Consider adding: docs/src/content/docs/reference/glossary.mdx

Key Terms to Define

On first use, add context:

• frontmatter → "frontmatter (YAML configuration section)"
• MCP → "MCP (Model Context Protocol)"
• trial mode → "trial mode (safe preview without making changes)"
• workflow lock → "workflow lock (.lock.yml compiled output)"

Example Implementation

Before:

The workflow uses frontmatter to configure...

After:

The workflow uses frontmatter (the YAML configuration section between --- markers) to configure...

Or with Astro tooltip component:

The workflow uses (Tooltip text="YAML configuration section between --- markers")frontmatter(/Tooltip) to configure...

Acceptance Criteria

• "frontmatter" is defined on first use in Quick Start
• "MCP" acronym is expanded on first use
• "trial mode" is explained when introduced
• "workflow lock" is defined when mentioned
• Documentation builds without errors
• Consistent pattern for defining terms throughout

Priority

HIGH - Identified as Quick Win #2 with high impact for new users

AI generated by Plan Command for discussion #4257</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [task] Define jargon terms on first use throughout documentation #4260

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull Request Overview

This PR addresses documentation friction for new users by defining technical jargon terms on first use throughout the documentation. The changes add inline definitions for key concepts like frontmatter, .lock.yml, safe-outputs, and MCP, along with a comprehensive new glossary page.

Key Changes:

• Inline definitions added to Quick Start, How It Works, and Overview pages to explain terms when first encountered
• New glossary reference page created with organized term definitions across 6 domains
• Consistent definition patterns applied across all documentation files

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
docs/src/content/docs/setup/quick-start.md	Added inline definition for .lock.yml and comprehensive explanation of frontmatter, natural language instructions, and safe-outputs
docs/src/content/docs/reference/glossary.md	New comprehensive glossary page with 26 term definitions organized by domain (Core Concepts, Tools & Integration, Security & Outputs, Workflow Components, Development & Compilation, Advanced Features)
docs/src/content/docs/introduction/overview.mdx	Added inline definition for safe-outputs explaining it as a security feature
docs/src/content/docs/introduction/how-it-works.mdx	Added inline definitions for frontmatter (configuration section between markers) and MCP (expanded to Model Context Protocol with explanation)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

[nitpick] This paragraph is quite dense and contains three different concept definitions in a single sentence. Consider breaking it into multiple sentences or a bulleted list for better readability:

Suggested revision:

The section between the `---` markers is called **frontmatter**—a YAML configuration section that defines when the workflow runs, what permissions it has, and what tools it can use. 

The section below the frontmatter contains the natural language instructions that tell the AI agent what to do. 

The `safe-outputs` section specifies that this workflow can safely create GitHub discussions without needing write permissions during the AI execution phase.

This improves scannability and makes it easier for new users to absorb each concept individually.

Suggested change

The section between the `---` markers (called frontmatter) contains the YAML configuration that defines when the workflow runs, what permissions it has, and what tools it can use. The section below the frontmatter contains the natural language instructions that tell the AI agent what to do. The `safe-outputs` section specifies that this workflow can safely create GitHub discussions without needing write permissions during the AI execution phase.

The section between the `---` markers is called **frontmatter**—a YAML configuration section that defines when the workflow runs, what permissions it has, and what tools it can use.