Document runtime markdown loading: when recompilation is required vs optional

docs/src/content/docs/guides/editing-workflows.md

@@ -0,0 +1,203 @@
+---
+title: Editing Workflows
+description: Learn when you can edit workflows directly on GitHub.com versus when recompilation is required, and best practices for iterating on agentic workflows.
+sidebar:
+  order: 5
+---
+
+Agentic workflows consist of two distinct parts with different editing requirements: the **YAML frontmatter** (configuration) and the **markdown body** (AI instructions). Understanding when changes require recompilation helps you iterate quickly and efficiently.
+
+See [Authoring Workflows with AI](/gh-aw/setup/agentic-authoring/) for guidance on creating workflows with AI assistance.
+
+## Overview
+
+Workflow files (`.md`) are compiled into GitHub Actions workflow files (`.lock.yml`). The compilation process:
+
+- **Embeds frontmatter** directly into the lock file (changes require recompilation)
+- **Loads the markdown body** at runtime from the source file (changes do NOT require recompilation)
+
+This design allows you to quickly iterate on AI instructions without recompilation while maintaining strict control over security-sensitive configuration.
+
+## Editing Without Recompilation
+
+> [!TIP]
+> You can edit the **markdown body** directly on GitHub.com or in any editor without recompiling. Changes take effect on the next workflow run.
+
+### What You Can Edit
+
+The markdown body is loaded at runtime from the original `.md` file. You can freely edit:
+
+- **AI instructions**: Task descriptions, step-by-step guidance, examples
+- **Context explanations**: Project conventions, background information
+- **Output formatting**: Templates for issues, PRs, comments
+- **Conditional logic**: "If X, then do Y" instructions
+- **Documentation**: Headers, examples, clarifications
+
+### Workflow for Quick Iterations
+
+```bash
+# 1. Edit the markdown body on GitHub.com
+#    Navigate to .github/workflows/my-workflow.md
+#    Click "Edit" and modify instructions
+
+# 2. Commit changes directly to main (or create PR)
+
+# 3. Trigger the workflow
+#    Changes are immediately active - no recompilation needed!
+```
+
+### Example: Adding Instructions
+
+**Before** (in `.github/workflows/issue-triage.md`):
+```markdown
+---
+on:
+  issues:
+    types: [opened]
+---
+
+# Issue Triage
+
+Read issue #${{ github.event.issue.number }} and add appropriate labels.
+```
+
+**After** (edited on GitHub.com):
+```markdown
+---
+on:
+  issues:
+    types: [opened]
+---
+
+# Issue Triage
+
+Read issue #${{ github.event.issue.number }} and add appropriate labels.
+
+## Labeling Criteria
+
+Apply these labels based on content:
+- `bug`: Issues describing incorrect behavior with reproduction steps
+- `enhancement`: Feature requests or improvements
+- `question`: Help requests or clarifications needed
+- `documentation`: Documentation updates or corrections
+
+For priority, consider:
+- `high-priority`: Security issues, critical bugs, blocking issues
+- `medium-priority`: Important features, non-critical bugs
+- `low-priority`: Nice-to-have improvements, minor enhancements
+```
+
+✅ This change takes effect immediately without recompilation.
+
+## Editing With Recompilation Required
+
+> [!WARNING]
+> Changes to the **YAML frontmatter** always require recompilation. These are security-sensitive configuration options.
+
+### What Requires Recompilation
+
+Any changes to the frontmatter configuration between `---` markers:
+
+- **Triggers** (`on:`): Event types, filters, schedules
+- **Permissions** (`permissions:`): Repository access levels
+- **Tools** (`tools:`): Tool configurations, MCP servers, allowed tools
+- **Network** (`network:`): Allowed domains, firewall rules
+- **Safe outputs** (`safe-outputs:`): Output types, threat detection
+- **Safe inputs** (`safe-inputs:`): Input validation rules
+- **Runtimes** (`runtimes:`): Node, Python, Go version overrides
+- **Imports** (`imports:`): Shared configuration files
+- **Custom jobs** (`jobs:`): Additional workflow jobs
+- **Engine** (`engine:`): AI engine selection (copilot, claude, codex)
+- **Timeout** (`timeout-minutes:`): Maximum execution time
+- **Roles** (`roles:`): Permission requirements for actors
+
+### Example: Adding a Tool (Requires Recompilation)
+
+**Before**:
+```yaml
+---
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+---
+```
+
+**After** (must recompile):
+```yaml
+---
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+
+tools:
+  github:
+    toolsets: [issues]
+---
+```
+
+⚠️ Run `gh aw compile my-workflow` before committing this change.
+
+## Expressions and Environment Variables
+
+> [!CAUTION]
+> Adding GitHub Actions expressions (`${{ ... }}`) in the markdown body does NOT require recompilation, but they are subject to security validation.
+
+### Allowed Expressions
+
+You can safely use these expressions in markdown without recompilation:
+
+```markdown
+# Process Issue
+
+Read issue #${{ github.event.issue.number }} in repository ${{ github.repository }}.
+
+Issue title: "${{ github.event.issue.title }}"
+
+Use sanitized content: "${{ needs.activation.outputs.text }}"
+
+Actor: ${{ github.actor }}
+Repository: ${{ github.repository }}
+```
+
+These expressions are evaluated at runtime and validated for security. See [Templating](/gh-aw/reference/templating/) for the complete list of allowed expressions.
+
+### Prohibited Expressions
+
+Arbitrary expressions are blocked for security. This will fail at runtime:
+
+```markdown
+# ❌ WRONG - Will be rejected
+Run this command: ${{ github.event.comment.body }}
+```
+
+Use `needs.activation.outputs.text` for sanitized user input instead.
+
+## Quick Reference
+
+| Change Type | Example | Recompilation? | Edit Location |
+|-------------|---------|----------------|---------------|
+| **AI instructions** | Add task steps | ❌ No | GitHub.com or any editor |
+| **Output templates** | Change issue format | ❌ No | GitHub.com or any editor |
+| **Conditional logic** | "If bug, then..." | ❌ No | GitHub.com or any editor |
+| **GitHub expressions** | Add `${{ github.actor }}` | ❌ No | GitHub.com or any editor |
+| **Tools** | Add GitHub toolset | ✅ Yes | Local + compile |
+| **Permissions** | Add `contents: write` | ✅ Yes | Local + compile |
+| **Triggers** | Add `schedule:` | ✅ Yes | Local + compile |
+| **Network rules** | Add allowed domain | ✅ Yes | Local + compile |
+| **Safe outputs** | Add `create-issue:` | ✅ Yes | Local + compile |
+| **Engine** | Change to Claude | ✅ Yes | Local + compile |
+| **Imports** | Add shared config | ✅ Yes | Local + compile |
+
+## Related Documentation
+
+- [Workflow Structure](/gh-aw/reference/workflow-structure/) - Overall file organization
+- [Frontmatter Reference](/gh-aw/reference/frontmatter/) - All configuration options
+- [Markdown Reference](/gh-aw/reference/markdown/) - Writing effective instructions
+- [Compilation Process](/gh-aw/reference/compilation-process/) - How compilation works
+- [Templating](/gh-aw/reference/templating/) - Expression syntax and substitution

docs/src/content/docs/reference/compilation-process.md

@@ -236,6 +236,9 @@ Pre-activation runs checks sequentially. Any failure sets `activated=false`, pre
 | `gh aw compile --purge` | Remove orphaned `.lock.yml` files |
 | `gh aw compile --output /path/to/output` | Custom output directory |
 
+> [!TIP]
+> Compilation is only required when changing **frontmatter configuration**. The **markdown body** (AI instructions) is loaded at runtime and can be edited without recompilation. See [Editing Workflows](/gh-aw/guides/editing-workflows/) for details.
+
 ## Debugging Compilation
 
 **Enable verbose logging**: `DEBUG=workflow:* gh aw compile my-workflow --verbose` shows job creation, action pin resolutions, tool configurations, and MCP setups.
@@ -273,6 +276,7 @@ Pre-activation runs checks sequentially. Any failure sets `activated=false`, pre
 
 ## Related Documentation
 
+- [Editing Workflows](/gh-aw/guides/editing-workflows/) - When to recompile vs edit directly
 - [Frontmatter Reference](/gh-aw/reference/frontmatter/) - All configuration options
 - [Tools Reference](/gh-aw/reference/tools/) - Tool configuration guide
 - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Output processing

docs/src/content/docs/reference/faq.md

@@ -10,6 +10,14 @@ sidebar:
 
 ## Capabilities
 
+### Can I edit workflows directly on GitHub.com without recompiling?
+
+Yes! The **markdown body** (AI instructions) is loaded at runtime and can be edited directly on GitHub.com or in any editor. Changes take effect on the next workflow run without recompilation.
+
+However, **frontmatter configuration** (tools, permissions, triggers, network rules) is embedded in the compiled workflow and requires recompilation when changed. Run `gh aw compile my-workflow` after editing frontmatter.
+
+See [Editing Workflows](/gh-aw/guides/editing-workflows/) for complete guidance on when recompilation is needed.
+
 ### What's the difference between agentic workflows and regular GitHub Actions workflows?
 
 Agentic workflows are a special type of GitHub Actions workflow that use AI agentic processing to interpret natural language instructions and make decisions. Key differences include

docs/src/content/docs/reference/markdown.md

@@ -5,7 +5,7 @@ sidebar:
   order: 300
 ---
 
-The markdown is the most important part of your agentic workflow, and should describe its intended operation. The markdown follows the frontmatter. For example:
+The markdown body is the most important part of your agentic workflow, containing natural language instructions for the AI agent. The markdown follows the frontmatter and is loaded at runtime, allowing you to edit instructions directly on GitHub.com without recompilation. For example:
 
 ```aw wrap
 ---
@@ -91,8 +91,16 @@ Avoid over-complexity (keep instructions focused), assuming knowledge (explain p
 
 Agentic markdown supports GitHub Actions expression substitutions and conditional templating for content. See [Templating and Substitutions](/gh-aw/reference/templating/) for details.
 
+## Editing and Iteration
+
+> [!TIP]
+> The markdown body is loaded at runtime from the original `.md` file. You can edit instructions directly on GitHub.com and changes take effect immediately without recompiling the workflow.
+
+This design enables rapid iteration on AI instructions while maintaining strict compilation requirements for security-sensitive frontmatter configuration. See [Editing Workflows](/gh-aw/guides/editing-workflows/) for complete guidance on when recompilation is needed versus when you can edit directly.
+
 ## Related Documentation
 
+- [Editing Workflows](/gh-aw/guides/editing-workflows/) - When to recompile vs edit directly
 - [Workflow Structure](/gh-aw/reference/workflow-structure/) - Overall workflow file organization
 - [Frontmatter](/gh-aw/reference/frontmatter/) - YAML configuration options
 - [Security Notes](/gh-aw/guides/security/) - Comprehensive security guidance

docs/src/content/docs/reference/workflow-structure.md

@@ -49,6 +49,13 @@ When you run the `compile` command you generate the lock file.
 gh aw compile
 ```
 
+## Editing Workflows
+
+> [!TIP]
+> The **markdown body** is loaded at runtime and can be edited directly on GitHub.com without recompilation. Only **frontmatter changes** require recompilation.
+
+See [Editing Workflows](/gh-aw/guides/editing-workflows/) for complete guidance on when recompilation is needed.
+
 ## Best Practices
 
 - Use descriptive names: `issue-responder.md`, `pr-reviewer.md`
@@ -59,6 +66,7 @@ gh aw compile
 
 ## Related Documentation
 
+- [Editing Workflows](/gh-aw/guides/editing-workflows/) - When to recompile vs edit directly
 - [Frontmatter](/gh-aw/reference/frontmatter/) - Configuration options for workflows
 - [Markdown](/gh-aw/reference/markdown/) - The main markdown content of workflows
 - [Imports](/gh-aw/reference/imports/) - Modularizing workflows with includes