[plan] Improve terminology clarity with inline glossary links

[github-actions]

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

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster