Add glossary callout to Quick Start for terminology discoverability

[Copilot]

New users encounter critical terminology ("frontmatter", "MCP", "agentic", "compilation", ".lock.yml") in Quick Start without definitions, causing confusion. The glossary exists but lacks discoverability.

Changes

• Added prominent TIP callout at Quick Start top (after warning box) directing users to glossary
• Linked first MCP mention to glossary definition in Step 2

Screenshots

Quick Start with glossary callout:

Target glossary page:

Notes

The glossary already contains comprehensive definitions for all 5+ core concepts. This PR improves discoverability rather than adding new content.

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: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro dev --host 0.0.0.0 (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>[Code Quality] Add Key Concepts glossary page to documentation</issue_title>
<issue_description>## Description

The documentation uses critical terminology like "frontmatter" (8 mentions), "MCP" (7 mentions), and "agentic" without defining them. New users encounter these terms in the Quick Start guide but must infer their meaning from context, creating unnecessary cognitive load.

Background

Identified during the Documentation Noob Test on 2026-01-22. Testing revealed that beginners are confused by undefined jargon, particularly:

• "Frontmatter": Never explained (appears 8 times in Quick Start)
• "MCP": Acronym never expanded to "Model Context Protocol" (7 uses)
• "Agentic": Core concept used throughout but never defined
• "Lock file": .lock.yml purpose unclear to newcomers
• "Compilation": Why .md becomes .lock.yml not explained upfront

Impact:

• High - Beginners confused from the start
• Users spend time searching external resources for basic terminology
• Reduces documentation accessibility for non-technical users

Suggested Changes

Create a new "Key Concepts" glossary page under docs/src/content/docs/reference/:

Required Definitions

# Key Concepts

## Agentic Workflows
AI-powered automations that can make decisions and take actions autonomously based on natural language instructions. Unlike traditional workflows that follow rigid scripts, agentic workflows adapt to context and handle complex tasks with minimal human intervention.

## Frontmatter
The YAML header at the top of a workflow markdown file, enclosed by `---` delimiters. Contains configuration like engine selection, tools, permissions, and triggers.

Example:
\`\`\`yaml
---
engine: copilot
on:
  issues:
    types: [opened]
---
\`\`\`

## MCP (Model Context Protocol)
A protocol for connecting AI agents to external tools and data sources. MCP servers provide capabilities like file access, API integration, and browser automation.

## Lock File (.lock.yml)
The compiled GitHub Actions YAML file generated from your markdown workflow. Contains the complete, security-hardened workflow that GitHub Actions executes. Committed to version control alongside the source `.md` file.

## Compilation
The process of converting a markdown workflow (`.md`) into a GitHub Actions YAML workflow (`.lock.yml`). Validation, security hardening, and schema checking occur during compilation.

Command: `gh aw compile my-workflow.md`

Integration Points

1. Link from first mentions: Add tooltips or inline links to glossary on first use of each term
2. Quick Start enhancement: Add callout box early: "New to these terms? See Key Concepts"
3. Navigation: Add to reference section sidebar

Files Affected

New files:

• docs/src/content/docs/reference/key-concepts.md (new glossary page)

Updated files:

• docs/src/content/docs/setup/quick-start.md (add glossary link)
• docs/astro.config.mjs (add to navigation if needed)

Success Criteria

• Glossary page created with clear definitions for 5+ core terms
• Linked from Quick Start guide (prominent callout)
• Terms link to glossary on first mention in docs
• User testing shows ≥80% understand terminology without external help
• No increase in "what is frontmatter" support questions

Priority

HIGH - Quick win (1-2 hours), high impact for beginners

Estimated effort: 1-2 hours

Source

Extracted from Documentation Noob Test Report discussion githubnext/gh-aw#11228

Analysis quote:

"🔴 Critical Issues

1. Jargon Without Definitions
   "Frontmatter" appears 8 times in Quick Start but is never explained. New users don't know this refers to the YAML header in markdown files.
   "MCP" appears 7 times but the acronym is never expanded to "Model Context Protocol".
   Impact: High - Beginners will be confused from the start"

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 5, 2026, 12:26 PM UTC

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

• Fixes [Code Quality] Add Key Concepts glossary page to documentation #11267

---

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