Add glossary links and inline explanations for technical terms

[Copilot]

Beginners encounter undefined jargon ("agentic", "frontmatter", "MCP", "engine", "safe outputs", "lock.yml") before reaching the glossary. This adds glossary links on first use and inline explanations.

Changes

Glossary links on first use:

• Core terms: agentic, agent, engine, frontmatter, safe outputs, compilation, .lock.yml
• Links added to: homepage, introduction pages, quick start, reference docs

Acronym expansion on first mention:

• MCP → Model Context Protocol (MCP)
• PAT → Personal Access Token (PAT)

Inline explanations (parenthetical):

• agents → (autonomous AI systems that can understand and execute instructions)
• engine → (which AI model/provider to use)
• frontmatter → (YAML configuration section between --- markers)
• safe outputs → (pre-approved GitHub operations)

Enhanced glossary:

• Added tip box explaining how to use glossary links

Example

Before:

Configure your engine and frontmatter with tools for the agent...

After:

Configure your [engine](/gh-aw/reference/glossary/#engine) (which AI to use) 
and [frontmatter](/gh-aw/reference/glossary/#frontmatter) (configuration 
between `---` markers) with tools for the [agent](/gh-aw/reference/glossary/#agent) 
(AI system executing instructions)...

Files modified

• docs/src/content/docs/index.mdx
• docs/src/content/docs/introduction/{overview,how-it-works}.mdx
• docs/src/content/docs/setup/quick-start.md
• docs/src/content/docs/reference/{frontmatter,engines,glossary}.md
• docs/src/content/docs/guides/getting-started-mcp.md

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.12.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.12.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro preview --port 4321 --host 0.0.0.0 0/x64/bin/grep (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>[plan] Improve terminology clarity with inline glossary links</issue_title>
<issue_description>## Objective

Link technical jargon to glossary definitions on first use and consider adding inline tooltips to reduce beginner confusion.

Context

Testing identified multiple terms that confuse beginners:

• "Agentic" (used throughout before being defined)
• "Frontmatter" (used before explaining what it is)
• "MCP" (acronym never expanded on first use)
• "Engine" (not clear this means "which AI to use")
• "Safe outputs" (sounds scary, not explained simply)
• "Lock.yml" (relationship to .md file not immediately clear)

Current State

Terms are defined in the glossary but not linked from pages where they're first introduced.

Approach

1. Audit all documentation pages for jargon terms
2. Add markdown links to glossary on first use of each term
3. Expand acronyms on first use: "Model Context Protocol (MCP)"
4. Consider adding Astro Starlight tooltips or asides for key terms
5. Add brief inline explanations for critical concepts

Example Changes

Before:

Configure your engine and frontmatter...

After:

Configure your [engine](/glossary#engine) (which AI to use) and [frontmatter](/glossary#frontmatter) (configuration at the top of your file)...

Or with Starlight aside:

:::tip[What is frontmatter?]
Frontmatter is the configuration section at the top of your workflow file, between `---` markers.
:::

Files to Modify

Key pages to update:

• docs/src/content/docs/guides/creating-workflows.mdx
• docs/src/content/docs/guides/quickstart.mdx
• docs/src/content/docs/index.mdx
• Any example pages that introduce concepts
• docs/src/content/docs/reference/glossary.mdx (ensure all terms are present)

Acceptance Criteria

• All jargon terms link to glossary on first use
• Acronyms expanded on first mention
• Critical concepts have brief inline explanations
• Glossary contains all terms used in documentation
• Terms are explained in beginner-friendly language

AI generated by Plan Command for discussion #8477

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

• Fixes [plan] Improve terminology clarity with inline glossary links #8490

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.