[plan] Quick Start: Define 'frontmatter' inline and promote .lock.yml explanation to a callout

[github-actions]

Objective

Add a beginner-friendly inline definition of "frontmatter" and make the .lock.yml explanation visually prominent in the Quick Start guide.

Context

From the Documentation Noob Tester report in discussion #42905:

• Issue 3: The word "frontmatter" appears in Step 4 (Customize) with only an inline link but no explanation. Beginners with no YAML background don't know what it means.
• Issue 4: The critical explanation of .lock.yml is buried in a plain paragraph and easily skipped by skimmers.

Implementation Plan

Changes

1. Define "frontmatter" inline (Step 4)

In Step 4 (Customize), after the first mention of "frontmatter", add a parenthetical:

"(the --- block at the top of the file that controls when and how the workflow runs)"

Keep the existing link to the Reference page.

2. Promote .lock.yml explanation to a callout

Wrap the current plain-paragraph explanation of .lock.yml in a [!NOTE] callout:

> [!NOTE]
> The `.lock.yml` is the compiled GitHub Actions workflow generated from your markdown — it is what actually runs, and it is regenerated automatically, so you never edit it by hand.

Consider also adding a "What just happened?" sub-section after Step 2 that names both new files (.md source and .lock.yml compiled output).

Files to Modify

• docs/src/content/docs/quick-start.mdx (or equivalent Quick Start source file in the docs directory)

Acceptance Criteria

• "frontmatter" has an inline parenthetical explanation on first use in Step 4
• The .lock.yml explanation is wrapped in a [!NOTE] (or equivalent) callout so it is visually distinct
• No existing content is removed — only formatting/presentation is changed

Generated by 📋 Plan Command · 21 AIC · ⌖ 6.73 AIC · ⊞ 4.9K · ◷
_{Comment /plan to run again}

• expires on Jul 4, 2026, 7:12 PM UTC-08:00