Move compilation explanation before command in Quick Start

[Copilot]

Users were executing gh aw add before understanding why they'd see two files (.md and .lock.yml) in the PR, causing mid-flow confusion.

Changes

Reordered Step 2 to explain compilation concept before command execution:

• Added "Understanding the files" subsection explaining the two-file system upfront
• Moved compilation explanation from after command to before it
• Added translation analogy: "Think of compilation like translating: Markdown → YAML"
• Updated command description to reference "both files" now that they're pre-explained

Before/After Flow

Before:

### Step 2
Run command → See two files in PR → "Why two files?" explanation

After:

### Step 2
Explanation: two files (.md + .lock.yml) → Clear analogy → Run command

Users now understand what they'll see before they see it.

Fixes #4468

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>[task] Move "Why Compile?" explanation before compilation command in Quick Start</issue_title>
<issue_description>## Objective
Reorder the Quick Start guide to explain the compilation concept BEFORE users run the command, preventing mid-flow confusion.

Context

Currently in Step 2, users execute gh aw add which creates a .lock.yml file, but the "Why Compile?" explanation comes after. This causes confusion when users see the PR with two files. Part of discussion #4466.

Approach

1. Move the "Why Compile?" section to appear BEFORE the gh aw add command
2. Add clear analogy: "Think of compilation like translating: Markdown → YAML"
3. Explain the two-file system upfront
4. Keep the technical details in the existing explanation

Suggested Structure

### Step 2 — Add a sample workflow

**Understanding the files:** Agentic workflows use two files:
- `.md` file - What you write (human-friendly markdown)
- `.lock.yml` file - What GitHub Actions runs (auto-generated)

Think of compilation like translating: Markdown → YAML

Now let's add a sample workflow...

[Command follows here]

Files to Modify

• docs/src/content/docs/setup/quick-start.mdx

Acceptance Criteria

• "Why Compile?" explanation appears before the command
• Two-file system explained clearly
• Analogy helps non-technical users understand
• Flow reads naturally without jumping around
• No duplicate content created

Estimated Impact

• Time: 15 minutes
• Eliminates mid-flow confusion for new users
  Related to 📚 Documentation Noob Test Report - November 21, 2025 #4466

AI generated by Plan Command for discussion #4466</issue_description>

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

• Fixes [task] Move "Why Compile?" explanation before compilation command in Quick Start #4488

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.