[Code Quality] Fix Quick Start docs: define 'workflow', 'frontmatter', and clarify .lock.yml

[github-actions]

Description

The docs-noob-tester identified several critical documentation gaps that block new users from getting started with gh-aw. The Quick Start page jumps directly into commands without defining what a workflow is, uses undefined jargon (frontmatter), and buries the recommended AI engine choice.

Suggested Changes

1. Add a one-paragraph "What is a gh-aw workflow?" definition box at the top of the Quick Start page before Step 1:

   • "A workflow is a .md file with YAML frontmatter that gets compiled into a GitHub Actions file."

2. Move the Copilot recommendation to the top of the Prerequisites AI engine list (currently buried at the end).

3. Add inline definition of "frontmatter" on first use:

   • Add callout: "New to frontmatter? It's the settings block at the top of a markdown file, between two --- lines."

4. Add a clarifying note: "It's correct and expected to commit your .lock.yml file — it's intentional and needed by GitHub Actions."

Files Affected

• docs/setup/quick-start/ (or equivalent source markdown/mdx)
• docs/setup/cli/ (Most Common Commands table)

Success Criteria

• A first-time user can read the Quick Start without googling "what is frontmatter"
• Copilot is prominently recommended as the default AI engine choice
• Lock file confusion addressed with a clear callout
• All doc build/lint checks pass

Source

Extracted from Documentation Noob Test Report - 2026-07-18 (#46338)

Priority

High — These are documented friction points that block the first 10 minutes of the user onboarding experience.

🔍 Task mining by Discussion Task Miner - Code Quality Improvement Agent · 64.4 AIC · ⌖ 7.63 AIC · ⊞ 7K · ◷

• expires on Jul 18, 2026, 11:25 PM UTC-08:00

[github-actions]

This issue was automatically closed because it expired on 2026-07-19T07:25:08.080Z.

Closed by Workflow