Add glossary definitions for technical jargon throughout documentation

[Copilot]

Technical terms ("agentic", "frontmatter", "YAML", "safe outputs") were used throughout docs without definition, assuming prior knowledge. The "agentic" definition used the word to define itself.

Changes

Homepage (index.mdx)

• Lead with self-explanatory definition: "Agentic means the AI can think and decide for itself"
• Removed circular definition that used "agentic" to explain "agentic"

Quick Start (quick-start.md)

• Added YAML basics callout before first YAML example:

  tools:          # Key with nested items below
    github:       # Nested key (indented 2 spaces)
      - repos     # List item (dash + 2 spaces)

• Enhanced frontmatter explanation: "section at the top of the markdown file that contains configuration in YAML format"
• Improved safe outputs with security context: "prevents the AI from making unexpected changes—workflow processes these requests in separate, permission-controlled jobs where humans can review what happened"

All definitions now use beginner-friendly language without assumed knowledge.

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.11.1/x64/bin/node 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>[plan] Add glossary definitions for technical jargon</issue_title>
<issue_description>## Objective

Add clear definitions for technical terms ("agentic", "frontmatter", "YAML", "safe outputs") on first use throughout the documentation.

Problem

Terms like "agentic", "frontmatter", and "YAML" are used throughout the docs without definition, assuming prior knowledge. The explanation of "agentic" uses the word to define itself, and YAML syntax is shown without explaining what YAML is.

Approach

1. Improve the "agentic" definition on the homepage to be self-explanatory:

**Agentic means the AI can think and decide for itself.** Unlike traditional automation that follows exact steps you program, agentic workflows give the AI a goal and let it figure out how to achieve it—like asking a smart assistant to "organize my issues" instead of writing code for every possible scenario.

2. Add a YAML basics callout in the Quick Start guide:

:::tip[YAML Basics for Beginners]
The configuration section uses YAML syntax:
- `key: value` — Sets a configuration option
- `- item` — Creates a list item
- Indentation matters (use 2 spaces, not tabs)
- Learn more: [YAML Tutorial]((redacted))
:::

3. Add frontmatter explanation where first mentioned:

**Frontmatter** is a section at the top of a markdown file (between `---` markers) that contains configuration in YAML format. It's commonly used in static site generators and documentation tools.

4. Consider adding a glossary page at /docs/src/content/docs/reference/glossary.mdx

Files to Modify

• docs/src/content/docs/index.mdx - Improve "agentic" definition
• docs/src/content/docs/setup/quick-start.mdx - Add YAML and frontmatter explanations
• docs/src/content/docs/reference/glossary.mdx - Create glossary page (optional)

Acceptance Criteria

• "Agentic" explained without using the word to define itself
• YAML basics callout added before first YAML example
• Frontmatter defined on first use
• Safe outputs explanation improved with security context
• Definitions use beginner-friendly language
• No assumed prior knowledge

Reference

From noob test report: Confusing Areas #1, #2, #3, #4
Related to #6505

AI generated by Plan Command for discussion #6502

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

• Fixes [plan] Add glossary definitions for technical jargon #6509

---

💡 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.