From aa969fadf6c4f23af963030a7503b9b435eeb271 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 26 May 2026 23:36:14 +0000
Subject: [PATCH 1/2] Initial plan


From d1c793fa8f878f13072b41f7d2be2e3486bf2443 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 26 May 2026 23:43:56 +0000
Subject: [PATCH 2/2] docs: explain .lock.yml in quick start step 2

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
---
 docs/src/content/docs/setup/quick-start.mdx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx
index a182696e95f..64878d0fcff 100644
--- a/docs/src/content/docs/setup/quick-start.mdx
+++ b/docs/src/content/docs/setup/quick-start.mdx
@@ -72,6 +72,8 @@ This will take you through an interactive process to:
 4. **Add the workflow** - Adds the workflow file (`.md`) and its generated GitHub Actions lock file (`.lock.yml`) to `.github/workflows/`.
 5. **Optionally trigger an initial run** - Starts the workflow immediately.
 
+The `.lock.yml` file is the compiled GitHub Actions workflow generated from the `.md` source file. Keep editing the `.md` file; the lock file exists so GitHub Actions has a deterministic, runnable workflow definition. Do not edit `.lock.yml` directly — regenerate it with `gh aw compile` after making workflow changes. See [Lock File Header](/gh-aw/reference/workflow-structure/#lock-file-header).
+
 > [!NOTE]
 > **Setting up `COPILOT_GITHUB_TOKEN`?**
 > 1. [Create a fine-grained PAT](https://github.com/settings/personal-access-tokens/new) under your user account.