docs: Separate compile-time and runtime imports documentation

[Copilot]

The imports documentation mixed two distinct mechanisms—compile-time imports (processed during gh aw compile) and runtime imports (processed during workflow execution)—creating confusion about when to use each.

Changes

reference/imports.md - Compile-time only

• Removed runtime import (@ syntax) section
• Added explicit "compile-time" terminology throughout
• Link to templating.md for runtime imports
• Covers: imports: field, {{#import}}, {{#import?}}

reference/templating.md - Runtime imports enhanced

• Added comparison table (runtime vs compile-time)
• Added "when to use" guidance for each type
• Clarified that @./path is runtime, not compile-time
• Covers: {{#runtime-import}}, {{#runtime-import?}}, @./path

Key Distinction

Feature	Runtime	Compile-time
Processed	During workflow execution	During gh aw compile
Syntax	{{#runtime-import}}, @./path	imports:, {{#import}}
Purpose	Include prompt content	Merge frontmatter configs
Recompile needed	No	Yes

Documentation-only change, no behavior changes.

Original prompt

Clean up the docs so “imports” are clearly split:

Compile-time imports only in reference/imports.md (imports: + {{#import}}/{{#import?}}).
Runtime imports only under templating ({{#runtime-import}}/{{#runtime-import?}} + @...).
Move/rename sections as needed, update links/examples/wording to avoid mixing the two. Docs-only change; no behavior changes. Output a diff + short summary.

---

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

[mnkiefer]

@dsyme FYI, this would make a clearer distinction between compile vs. runtime imports. Does this work for you?

[pelikhan]

Maybe we simplify things and only support @?

[mnkiefer]

Maybe we simplify things and only support @?

That would work for me 👍🏼 @dsyme what are your thoughts?

[dsyme]

I don't mind syntax. But I think having both makes sense as "@" may run into trouble if spaces are in names, or weird unicode characters etc

[dsyme]

Actually I think it's important to say "runtime", also there should be alignment with static imports. I think "@" is way too subtle

Right now we have

{{#import shared/common-tools.md}}
{{#runtime-import coding-standards.md}}
@./security-checklist.md

I think we should just have the first two to be honest. It's really a big security matter to review for runtime imports and assess who can change them isn't it? Don't we have to make this explicit?

But I don't think we should only have @ as it's important to at least be able to be explicit.

As an aside do we really trust our code to find only truly intentional "@"? What if there's an "@./" in the middle of some markdown etc?

Also the business about the ".github" directory needs to be checked. Static imports and runtime imports sho0uld use identical resolution. Things like "All file paths are resolved within the .github folder, so @./file.md refers to .github/file.md in your repository" make me feel the two are not aligned.

Speaking of which I'm unclear, do runtime imports require the repo to have been checked out in the Actions VM or do they do a GitHub fetch from main?

[mnkiefer]

But I don't think we should only have @ as it's important to at least be able to be explicit.

I agree

Speaking of which I'm unclear, do runtime imports require the repo to have been checked out in the Actions VM or do they do a GitHub fetch from main?

As far as I understand, it loads the imported file/module from the runner’s filesystem at job runtime (from whatever is present in the workspace after checkout/other steps). It does not go to GitHub and fetch main by itself.

@pelikhan What's the final verdict here? ☺️

[pelikhan]

Ok let's remove "@"

[pelikhan]

I will start a PR to remove it and make file path resolution more precise (full relative repo path, must be .github)

[pelikhan]

#10313

[mnkiefer]

• Closing in favor of Remove @ inline syntax for runtime imports, keep only {{#runtime-import}} macro #10313

[pelikhan]

@dsyme note the "@" is the syntax that copilot uses to import files... so it will happen through us or the agent