diff --git a/.github/workflows/trigger-agent-suggestions.yml b/.github/workflows/trigger-agent-suggestions.yml
index 680fa097..ce0354e8 100644
--- a/.github/workflows/trigger-agent-suggestions.yml
+++ b/.github/workflows/trigger-agent-suggestions.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/agent-suggestions/example.yml and run 'make compile' to regenerate.
 name: Trigger Agent Suggestions
 on:
   schedule:
diff --git a/.github/workflows/trigger-breaking-change-detector.yml b/.github/workflows/trigger-breaking-change-detector.yml
index 0b6c2293..19b04c07 100644
--- a/.github/workflows/trigger-breaking-change-detector.yml
+++ b/.github/workflows/trigger-breaking-change-detector.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/breaking-change-detector/example.yml and run 'make compile' to regenerate.
 name: Trigger Breaking Change Detector
 on:
   schedule:
diff --git a/.github/workflows/trigger-bug-exterminator.yml b/.github/workflows/trigger-bug-exterminator.yml
index 66e07e1e..35e2a01f 100644
--- a/.github/workflows/trigger-bug-exterminator.yml
+++ b/.github/workflows/trigger-bug-exterminator.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/bug-exterminator/example.yml and run 'make compile' to regenerate.
 name: Trigger Bug Exterminator
 on:
   schedule:
diff --git a/.github/workflows/trigger-bug-hunter.yml b/.github/workflows/trigger-bug-hunter.yml
index 327e397f..e2facd6f 100644
--- a/.github/workflows/trigger-bug-hunter.yml
+++ b/.github/workflows/trigger-bug-hunter.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/bug-hunter/example.yml and run 'make compile' to regenerate.
 name: Trigger Bug Hunter
 on:
   schedule:
diff --git a/.github/workflows/trigger-code-duplication-detector.yml b/.github/workflows/trigger-code-duplication-detector.yml
index 1b46695a..7c452e55 100644
--- a/.github/workflows/trigger-code-duplication-detector.yml
+++ b/.github/workflows/trigger-code-duplication-detector.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/code-duplication-detector/example.yml and run 'make compile' to regenerate.
 name: Trigger Code Duplication Detector
 on:
   schedule:
diff --git a/.github/workflows/trigger-code-duplication-fixer.yml b/.github/workflows/trigger-code-duplication-fixer.yml
index 824e46e2..4c861b53 100644
--- a/.github/workflows/trigger-code-duplication-fixer.yml
+++ b/.github/workflows/trigger-code-duplication-fixer.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/code-duplication-fixer/example.yml and run 'make compile' to regenerate.
 name: Trigger Code Duplication Fixer
 on:
   schedule:
diff --git a/.github/workflows/trigger-code-simplifier.yml b/.github/workflows/trigger-code-simplifier.yml
index 4a5c5456..4d7db9fb 100644
--- a/.github/workflows/trigger-code-simplifier.yml
+++ b/.github/workflows/trigger-code-simplifier.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/code-simplifier/example.yml and run 'make compile' to regenerate.
 name: Trigger Code Simplifier
 on:
   schedule:
diff --git a/.github/workflows/trigger-docs-patrol.yml b/.github/workflows/trigger-docs-patrol.yml
index d6bac064..efd706e3 100644
--- a/.github/workflows/trigger-docs-patrol.yml
+++ b/.github/workflows/trigger-docs-patrol.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/docs-patrol/example.yml and run 'make compile' to regenerate.
 name: Trigger Docs Patrol
 on:
   schedule:
diff --git a/.github/workflows/trigger-docs-pr-review.yml b/.github/workflows/trigger-docs-pr-review.yml
index 3e147f5e..27b4e358 100644
--- a/.github/workflows/trigger-docs-pr-review.yml
+++ b/.github/workflows/trigger-docs-pr-review.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/docs-pr-review/example.yml and run 'make compile' to regenerate.
 name: Trigger Docs PR Review
 on:
   issue_comment:
diff --git a/.github/workflows/trigger-downstream-health.yml b/.github/workflows/trigger-downstream-health.yml
index 1bf1731c..88286aaf 100644
--- a/.github/workflows/trigger-downstream-health.yml
+++ b/.github/workflows/trigger-downstream-health.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/downstream-health/example.yml and run 'make compile' to regenerate.
 name: Trigger Downstream Health
 on:
   schedule:
diff --git a/.github/workflows/trigger-duplicate-issue-detector.yml b/.github/workflows/trigger-duplicate-issue-detector.yml
index 28515493..27b71b45 100644
--- a/.github/workflows/trigger-duplicate-issue-detector.yml
+++ b/.github/workflows/trigger-duplicate-issue-detector.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/duplicate-issue-detector/example.yml and run 'make compile' to regenerate.
 name: Trigger Duplicate Issue Detector
 on:
   issues:
diff --git a/.github/workflows/trigger-issue-triage.yml b/.github/workflows/trigger-issue-triage.yml
index 9ac6b5a6..ede803dd 100644
--- a/.github/workflows/trigger-issue-triage.yml
+++ b/.github/workflows/trigger-issue-triage.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/issue-triage/example.yml and run 'make compile' to regenerate.
 name: Trigger Issue Triage
 on:
   issues:
diff --git a/.github/workflows/trigger-mention-in-issue.yml b/.github/workflows/trigger-mention-in-issue.yml
index 14c41dec..e5fa178a 100644
--- a/.github/workflows/trigger-mention-in-issue.yml
+++ b/.github/workflows/trigger-mention-in-issue.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/mention-in-issue/example.yml and run 'make compile' to regenerate.
 name: Trigger Mention in Issue
 on:
   issue_comment:
diff --git a/.github/workflows/trigger-mention-in-pr.yml b/.github/workflows/trigger-mention-in-pr.yml
index 0aa70d5e..a42b7fef 100644
--- a/.github/workflows/trigger-mention-in-pr.yml
+++ b/.github/workflows/trigger-mention-in-pr.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/mention-in-pr/example.yml and run 'make compile' to regenerate.
 name: Trigger Mention in PR
 on:
   issue_comment:
diff --git a/.github/workflows/trigger-newbie-contributor-fixer.yml b/.github/workflows/trigger-newbie-contributor-fixer.yml
index 294b69e5..6135cbe7 100644
--- a/.github/workflows/trigger-newbie-contributor-fixer.yml
+++ b/.github/workflows/trigger-newbie-contributor-fixer.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/newbie-contributor-fixer/example.yml and run 'make compile' to regenerate.
 name: Trigger Newbie Contributor Fixer
 on:
   schedule:
diff --git a/.github/workflows/trigger-newbie-contributor-patrol.yml b/.github/workflows/trigger-newbie-contributor-patrol.yml
index 7f74a476..3c6b927e 100644
--- a/.github/workflows/trigger-newbie-contributor-patrol.yml
+++ b/.github/workflows/trigger-newbie-contributor-patrol.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/newbie-contributor-patrol/example.yml and run 'make compile' to regenerate.
 name: Trigger Newbie Contributor Patrol
 on:
   schedule:
diff --git a/.github/workflows/trigger-plan.yml b/.github/workflows/trigger-plan.yml
index cad4c00a..972619c2 100644
--- a/.github/workflows/trigger-plan.yml
+++ b/.github/workflows/trigger-plan.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/plan/example.yml and run 'make compile' to regenerate.
 name: Trigger Plan
 on:
   issue_comment:
diff --git a/.github/workflows/trigger-pr-actions-detective.yml b/.github/workflows/trigger-pr-actions-detective.yml
index fddc2f10..ef9bb6b2 100644
--- a/.github/workflows/trigger-pr-actions-detective.yml
+++ b/.github/workflows/trigger-pr-actions-detective.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/pr-actions-detective/example.yml and run 'make compile' to regenerate.
 name: Trigger PR Actions Detective
 on:
   workflow_run:
diff --git a/.github/workflows/trigger-pr-actions-fixer.yml b/.github/workflows/trigger-pr-actions-fixer.yml
index 60389d3b..419bcaee 100644
--- a/.github/workflows/trigger-pr-actions-fixer.yml
+++ b/.github/workflows/trigger-pr-actions-fixer.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/pr-actions-fixer/example.yml and run 'make compile' to regenerate.
 name: Trigger PR Actions Fixer
 on:
   workflow_dispatch:
diff --git a/.github/workflows/trigger-pr-buildkite-detective.yml b/.github/workflows/trigger-pr-buildkite-detective.yml
index a2ce31fe..7c8a2487 100644
--- a/.github/workflows/trigger-pr-buildkite-detective.yml
+++ b/.github/workflows/trigger-pr-buildkite-detective.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/pr-buildkite-detective/example.yml and run 'make compile' to regenerate.
 name: Trigger PR Buildkite Detective
 on:
   workflow_run:
diff --git a/.github/workflows/trigger-pr-review.yml b/.github/workflows/trigger-pr-review.yml
index 14fa0b67..133be228 100644
--- a/.github/workflows/trigger-pr-review.yml
+++ b/.github/workflows/trigger-pr-review.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/pr-review/example.yml and run 'make compile' to regenerate.
 name: Trigger PR Review
 on:
   pull_request:
diff --git a/.github/workflows/trigger-project-summary.yml b/.github/workflows/trigger-project-summary.yml
index 27ec42ea..dea7abda 100644
--- a/.github/workflows/trigger-project-summary.yml
+++ b/.github/workflows/trigger-project-summary.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/project-summary/example.yml and run 'make compile' to regenerate.
 name: Trigger Project Summary
 on:
   schedule:
diff --git a/.github/workflows/trigger-release-update.yml b/.github/workflows/trigger-release-update.yml
index 25091011..89da23e1 100644
--- a/.github/workflows/trigger-release-update.yml
+++ b/.github/workflows/trigger-release-update.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/release-update/example.yml and run 'make compile' to regenerate.
 name: Trigger Release Update Check
 on:
   schedule:
diff --git a/.github/workflows/trigger-small-problem-fixer.yml b/.github/workflows/trigger-small-problem-fixer.yml
index 3b12ac89..c8b87cda 100644
--- a/.github/workflows/trigger-small-problem-fixer.yml
+++ b/.github/workflows/trigger-small-problem-fixer.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/small-problem-fixer/example.yml and run 'make compile' to regenerate.
 name: Trigger Small Problem Fixer
 on:
   schedule:
diff --git a/.github/workflows/trigger-stale-issues.yml b/.github/workflows/trigger-stale-issues.yml
index 155b90f0..33817297 100644
--- a/.github/workflows/trigger-stale-issues.yml
+++ b/.github/workflows/trigger-stale-issues.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/stale-issues/example.yml and run 'make compile' to regenerate.
 name: Trigger Stale Issues
 on:
   schedule:
diff --git a/.github/workflows/trigger-test-improver.yml b/.github/workflows/trigger-test-improver.yml
index e61b59bf..1cc83616 100644
--- a/.github/workflows/trigger-test-improver.yml
+++ b/.github/workflows/trigger-test-improver.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/test-improver/example.yml and run 'make compile' to regenerate.
 name: Trigger Test Improver
 on:
   schedule:
diff --git a/.github/workflows/trigger-text-auditor.yml b/.github/workflows/trigger-text-auditor.yml
index 05bb39eb..8dbe8aa0 100644
--- a/.github/workflows/trigger-text-auditor.yml
+++ b/.github/workflows/trigger-text-auditor.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/text-auditor/example.yml and run 'make compile' to regenerate.
 name: Trigger Text Auditor
 on:
   schedule:
diff --git a/.github/workflows/trigger-text-beautifier.yml b/.github/workflows/trigger-text-beautifier.yml
index a00fc2f6..f7f49499 100644
--- a/.github/workflows/trigger-text-beautifier.yml
+++ b/.github/workflows/trigger-text-beautifier.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/text-beautifier/example.yml and run 'make compile' to regenerate.
 name: Trigger Text Beautifier
 on:
   schedule:
diff --git a/.github/workflows/trigger-update-pr-body.yml b/.github/workflows/trigger-update-pr-body.yml
index 654d0618..1dd7052b 100644
--- a/.github/workflows/trigger-update-pr-body.yml
+++ b/.github/workflows/trigger-update-pr-body.yml
@@ -1,3 +1,5 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/update-pr-body/example.yml and run 'make compile' to regenerate.
 name: Trigger Update PR Body
 on:
   pull_request:
diff --git a/gh-agent-workflows/DEVELOPING.md b/gh-agent-workflows/DEVELOPING.md
index 2faa438b..c8376290 100644
--- a/gh-agent-workflows/DEVELOPING.md
+++ b/gh-agent-workflows/DEVELOPING.md
@@ -142,7 +142,9 @@ Trigger `example.yml` files are copied from `gh-agent-workflows/*/` by `scripts/
 1. Edit workflows in `.github/workflows/gh-aw-*.md`, triggers in `gh-agent-workflows/*/example.yml`, or fragments in `.github/workflows/gh-aw-fragments/`
 2. Run `make compile` (syncs triggers, then compiles)
 3. Verify 0 errors, 0 warnings
-4. Commit all source files, trigger files, and generated `.lock.yml` files
+4. Commit source files (`gh-aw-*.md`, `example.yml`, fragments) and the generated `.lock.yml` and `trigger-*.yml` files
+
+> **Do not edit `.lock.yml` files directly.** They are compiled output generated by `make compile` from the corresponding `.md` workflow source. Any manual edits will be overwritten on the next compile.
 
 ```bash
 make compile          # sync + compile
@@ -198,6 +200,8 @@ Consumer repos call the compiled `.lock.yml` via `uses:` in a plain YAML workflo
 
 Each non-internal workflow has a corresponding `example.yml` in `gh-agent-workflows/<name>/` that defines the actual event triggers and calls the compiled `.lock.yml`. These are plain YAML (not compiled by gh-aw) and are copied to `.github/workflows/trigger-<name>.yml` by `scripts/dogfood.sh` for dogfooding when the workflow is not listed in `EXCLUDED_WORKFLOWS` (see `scripts/dogfood.sh` for the current list).
 
+> **Do not edit `trigger-*.yml` files directly.** They are auto-generated by `scripts/dogfood.sh` (run via `make compile`) and any manual changes will be overwritten. To change a trigger, edit `gh-agent-workflows/<name>/example.yml` (or `dogfood-with.yml` for dogfood-only overrides) and run `make compile`.
+
 Consumer repos copy a workflow's `example.yml` into their `.github/workflows/` directory and customize the `with:` inputs. The `uses:` path already points to the remote compiled workflow.
 
 ### Dogfood overrides
diff --git a/scripts/dogfood.sh b/scripts/dogfood.sh
index 120c48a9..a74bcec5 100755
--- a/scripts/dogfood.sh
+++ b/scripts/dogfood.sh
@@ -46,8 +46,11 @@ for f in gh-agent-workflows/*/example.yml; do
     continue
   fi
   target=".github/workflows/trigger-$dir.yml"
-  sed 's|uses: elastic/ai-github-actions/\(.*\)@v0|uses: ./\1|; s|^name: |name: Trigger |' "$f" \
-    > "$target"
+  {
+    echo "# This file is auto-generated by scripts/dogfood.sh. Do not edit directly."
+    echo "# Edit gh-agent-workflows/$dir/example.yml and run 'make compile' to regenerate."
+    sed 's|uses: elastic/ai-github-actions/\(.*\)@v0|uses: ./\1|; s|^name: |name: Trigger |' "$f"
+  } > "$target"
 
   # Inject dogfood-with.yml overrides into the generated trigger.
   overrides="gh-agent-workflows/$dir/dogfood-with.yml"