docs: Separate compile-time and runtime imports documentation

docs/src/content/docs/reference/imports.md

@@ -1,15 +1,21 @@
 ---
 title: Imports
-description: Learn how to modularize and reuse workflow components across multiple workflows using the imports field in frontmatter for better organization and maintainability.
+description: Learn how to modularize and reuse workflow components across multiple workflows using compile-time imports in frontmatter and markdown for better organization and maintainability.
 sidebar:
   order: 325
 ---
 
-Using imports in frontmatter or markdown allows you to modularize and reuse workflow components across multiple workflows.
+Compile-time imports in frontmatter or markdown allow you to modularize and reuse workflow components across multiple workflows. Imports are processed during compilation and merged into the final workflow configuration.
+
+For runtime content inclusion (files/URLs loaded during workflow execution), see [Runtime Imports in Templating](/gh-aw/reference/templating/#runtime-imports).
 
 ## Syntax
 
-Imports can be specified either in frontmatter or in markdown. In frontmatter the `imports:` field is used:
+Compile-time imports can be specified either in frontmatter or in markdown:
+
+### Frontmatter Imports
+
+Use the `imports:` field to declare compile-time imports:
 
 ```aw wrap
 ---
@@ -25,53 +31,33 @@ imports:
 Workflow instructions here...
 ```
 
-In markdown, use the special `{{#import ...}}` directive:
+### Markdown Import Macros
+
+Use the `{{#import}}` and `{{#import?}}` macros for compile-time imports in markdown:
 
 ```aw wrap
 ---
-...
+on: issues
+engine: copilot
 ---
 
 # Your Workflow
 
 Workflow instructions here...
 
 {{#import shared/common-tools.md}}
+{{#import? optional-config.md}}
 ```
 
-### Runtime Import with @ Syntax
-
-The `@` syntax provides runtime imports that are inlined during compilation but can be edited independently without recompilation. This is useful for agent prompts that need frequent updates:
-
-```aw wrap
----
-on: issues
-  types: [opened]
-engine: copilot
----
-
-@./agentics/issue-triage.md
-```
-
-The referenced file (`.github/agentics/issue-triage.md`) contains the agent prompt and is inlined during compilation. Changes to this file take effect immediately on the next workflow run without requiring recompilation. The file must exist or the workflow will fail - there is no optional variant.
-
-**When to use `@` syntax**:
-- Agent prompts that need frequent updates
-- Content that changes independently from workflow configuration
-- Separation of workflow structure from prompt content
-
-**When to use `{{#import}}` macro**:
-- Reusable configuration components (tools, MCP servers, etc.)
-- Optional imports with `{{#import?}}` fallback
-- Complex frontmatter merging requirements
+Both syntaxes process imports during compilation, merging frontmatter configurations and including markdown content into the final workflow.
 
 ## Shared Workflow Components
 
 Workflows without an `on` field are shared workflow components. These files are validated but not compiled into GitHub Actions - they're meant to be imported by other workflows. The compiler skips them with an informative message, allowing you to organize reusable components without generating unnecessary lock files.
 
 ## Path Formats
 
-Import paths support local files (`shared/file.md`, `../file.md`), remote repositories (`owner/repo/file.md@v1.0.0`), and section references (`file.md#SectionName`). Optional imports use `{{#import? file.md}}` syntax in markdown. Runtime imports use `@path/to/file.md` syntax for content that updates without recompilation.
+Import paths support local files (`shared/file.md`, `../file.md`), remote repositories (`owner/repo/file.md@v1.0.0`), and section references (`file.md#SectionName`). Optional imports use `{{#import? file.md}}` syntax in markdown.
 
 Paths are resolved relative to the importing file, with support for nested imports and circular import protection.
 

docs/src/content/docs/reference/templating.md

@@ -9,8 +9,8 @@ Agentic workflows support four simple templating/substitution mechanisms:
 
 * GitHub Actions expressions in frontmatter or markdown
 * Conditional Templating blocks in markdown
-* [Imports](/gh-aw/reference/imports/) in frontmatter or markdown (compile-time)
 * Runtime imports in markdown (runtime file/URL inclusion)
+* [Compile-time imports](/gh-aw/reference/imports/) in frontmatter or markdown (processed during compilation)
 
 ## GitHub Actions Expressions
 
@@ -82,13 +82,38 @@ The template system supports only basic conditionals—no nesting, `else` clause
 
 ## Runtime Imports
 
-Runtime imports allow you to include content from files and URLs directly within your workflow prompts **at runtime** during GitHub Actions execution. This differs from [frontmatter imports](/gh-aw/reference/imports/) which are processed at compile-time.
+Runtime imports allow you to include content from files and URLs directly within your workflow prompts **at runtime** during GitHub Actions execution. This differs from [compile-time imports](/gh-aw/reference/imports/) which are processed during compilation and merge frontmatter configurations.
+
+**Key Differences:**
+
+| Feature | Runtime Imports | Compile-time Imports |
+|---------|----------------|---------------------|
+| **When processed** | During workflow execution | During `gh aw compile` |
+| **Syntax** | `{{#runtime-import}}`, `@./path` | `imports:` field, `{{#import}}` |
+| **Purpose** | Include prompt content from files/URLs | Merge workflow configurations |
+| **Frontmatter merging** | No | Yes (tools, MCP servers, etc.) |
+| **Path restrictions** | `.github` folder only (files) | No restrictions |
+| **Recompilation needed** | No - changes take effect immediately | Yes - must recompile after changes |
+
+**When to use runtime imports:**
+- Agent prompts that need frequent updates
+- Content that changes independently from workflow configuration
+- Including external documentation or guidelines
+- Separation of workflow structure from prompt content
+
+**When to use compile-time imports:**
+- Reusable configuration components (tools, MCP servers, etc.)
+- Frontmatter merging requirements
+- Remote repository imports with versioning
+- Shared workflow components
 
 **Security Note:** File imports are **restricted to the `.github` folder** in your repository. This ensures workflow configurations cannot access arbitrary files in your codebase.
 
+### Syntax Options
+
 Runtime imports support two syntaxes:
-- **Macro syntax:** `{{#runtime-import filepath}}`
-- **Inline syntax:** `@./path` or `@../path` (convenient shorthand)
+- **Macro syntax:** `{{#runtime-import filepath}}` and `{{#runtime-import? filepath}}` (optional)
+- **Inline syntax:** `@./path` or `@../path` (convenient shorthand, no optional variant)
 
 Both syntaxes support:
 - Line range extraction (e.g., `:10-20` for lines 10-20)
@@ -387,4 +412,4 @@ Failed to fetch URL https://example.com/file.txt: HTTP 404
 - [Markdown](/gh-aw/reference/markdown/) - Writing effective agentic markdown
 - [Workflow Structure](/gh-aw/reference/workflow-structure/) - Overall workflow organization
 - [Frontmatter](/gh-aw/reference/frontmatter/) - YAML configuration
-- [Imports](/gh-aw/reference/imports/) - Compile-time imports in frontmatter
+- [Compile-time Imports](/gh-aw/reference/imports/) - Imports processed during compilation with frontmatter merging