clarify docs

Author: dsyme

docs/src/content/docs/guides/packaging-imports.md

@@ -2,7 +2,7 @@
 title: Packaging and Imports
 description: Complete guide to adding, updating, and importing workflows from external repositories using workflow specifications and import directives.
 sidebar:
-  order: 6
+  order: 600
 ---
 
 This guide covers the complete workflow for packaging and importing agentic workflows from external repositories, including workflow specifications, CLI commands, and import mechanisms.

docs/src/content/docs/reference/command-triggers.md

@@ -2,7 +2,7 @@
 title: Command Triggers
 description: Learn about command triggers and context text functionality for agentic workflows, including special @mention triggers for interactive automation.
 sidebar:
-  order: 6
+  order: 600
 ---
 
 GitHub Agentic Workflows add the convenience `command:` trigger to create workflows that respond to `/my-bots` in issues and comments.

docs/src/content/docs/reference/concurrency.md

@@ -2,7 +2,7 @@
 title: Concurrency Control
 description: Complete guide to concurrency control in GitHub Agentic Workflows, including agent job concurrency configuration and engine isolation.
 sidebar:
-  order: 6
+  order: 600
 ---
 
 GitHub Agentic Workflows provides sophisticated concurrency control to manage how many AI-powered agent jobs can run simultaneously. This helps prevent resource exhaustion, control costs, and ensure predictable workflow execution.

docs/src/content/docs/reference/custom-safe-outputs.md

@@ -2,7 +2,7 @@
 title: Custom Safe Outputs
 description: Learn how to create custom safe outputs for third-party integrations using safe-jobs and MCP servers.
 sidebar:
-  order: 7
+  order: 700
 ---
 
 Custom safe outputs enable you to extend GitHub Agentic Workflows with your own output processing logic for third-party services like Notion, Slack, Jira, or any custom API. This guide demonstrates how to create reusable, secure integrations using safe-jobs combined with MCP servers.

docs/src/content/docs/reference/engines.md

@@ -1,13 +1,11 @@
 ---
 title: AI Engines
-description: Complete guide to AI engines available in GitHub Agentic Workflows, including Claude, Copilot, Codex, and custom engines with their specific configuration options.
+description: Complete guide to AI engines (coding agents) usable with GitHub Agentic Workflows, including Claude, Copilot, Codex, and custom engines with their specific configuration options.
 sidebar:
-  order: 1
+  order: 350
 ---
 
-GitHub Agentic Workflows support multiple AI engines to interpret and execute natural language instructions. Each engine has unique capabilities and configuration options.
-
-## Agentic Engines
+GitHub Agentic Workflows support multiple AI engines (coding agents) to interpret and execute natural language instructions. Each engine has unique capabilities and configuration options.
 
 ### GitHub Copilot (Default)
 

docs/src/content/docs/reference/frontmatter.md

@@ -2,7 +2,7 @@
 title: Frontmatter Options
 description: Complete guide to all available frontmatter configuration options for GitHub Agentic Workflows, including triggers, permissions, AI engines, and workflow settings.
 sidebar:
-  order: 2
+  order: 200
 ---
 
 The YAML frontmatter supports standard GitHub Actions properties plus additional agentic-specific options:

docs/src/content/docs/reference/include-directives.md

@@ -2,14 +2,12 @@
 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.
 sidebar:
-  order: 4
+  order: 400
 ---
 
 The `imports:` field in frontmatter allows you to modularize and reuse workflow components across multiple workflows.
 
-## Frontmatter Imports
-
-The recommended way to import shared components is using the `imports:` field in the frontmatter:
+Imports can be specified either in frontmatter or in markdown. In frontmatter the `imports:` field is used:
 
 ```aw wrap
 ---
@@ -25,6 +23,20 @@ imports:
 Workflow instructions here...
 ```
 
+In markdown, use the special `{{'#import ...}}` directive:
+
+```aw wrap
+---
+...
+---
+
+# Your Workflow
+
+Workflow instructions here...
+
+{{#import shared/common-tools.md}}
+```
+
 ### Import Path Resolution
 
 - **Relative paths**: Resolved relative to the importing file
@@ -33,35 +45,11 @@ Workflow instructions here...
 
 ## Frontmatter Merging
 
+When importing files, frontmatter fields are merged with the main workflow:
 - **Only `tools:` and `mcp-servers:` frontmatter** is allowed in imported files, other entries give a warning.
 - **Tool merging**: `allowed:` tools are merged across all imported files
 - **MCP server merging**: MCP servers defined in imported files are merged with the main workflow
 
-### Example Tool Merging
-```aw wrap
-# Base workflow
----
-on: issues
-tools:
-  github:
-    allowed: [get_issue]
-imports:
-  - shared/extra-tools.md
----
-```
-
-```aw wrap
-# shared/extra-tools.md
----
-tools:
-  github:
-    allowed: [add_issue_comment, update_issue]
-  edit:
----
-```
-
-**Result**: Final workflow has `github.allowed: [get_issue, add_issue_comment, update_issue]` and Claude Edit tool.
-
 ### Example MCP Server Merging
 
 ```aw wrap
@@ -86,28 +74,6 @@ mcp-servers:
 
 **Result**: Final workflow has the Tavily MCP server configured and available to the AI engine.
 
-## Legacy Directive Syntax (Deprecated)
-
-:::caution[Deprecated]
-The `{{#import}}`, `@import`, and `@include` directive syntax is deprecated. Use the `imports:` field in frontmatter instead.
-
-**Migration example:**
-```diff
-# Old approach
----
-on: issues
----
-- @import shared/extra-tools.md
-
-# New approach
-+ ---
-+ on: issues
-+ imports:
-+   - shared/extra-tools.md
-+ ---
-```
-:::
-
 ## Related Documentation
 
 - [Packaging and Imports](/gh-aw/guides/packaging-imports/) - Complete guide to adding, updating, and importing workflows

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

@@ -2,7 +2,7 @@
 title: Markdown Content
 description: Learn agentic workflow markdown content
 sidebar:
-  order: 3
+  order: 300
 ---
 
 The markdown content is where you write natural language instructions for the AI agent. 

docs/src/content/docs/reference/network.md

@@ -2,7 +2,7 @@
 title: Network Permissions
 description: Control network access for AI engines using ecosystem identifiers and domain allowlists
 sidebar:
-  order: 7
+  order: 700
 ---
 
 Control network access for AI engines using the top-level `network` field. Network permissions provide fine-grained control over which domains and services your agentic workflows can access during execution.

docs/src/content/docs/reference/safe-jobs.md

@@ -2,7 +2,7 @@
 title: Safe Jobs
 description: Learn about safe-jobs feature that enables defining custom post-processing workflows with GitHub Actions job properties and artifact access.
 sidebar:
-  order: 6
+  order: 600
 ---
 
 The `safe-outputs.jobs:` element of your workflow's frontmatter enables you to define custom post-processing jobs that execute after the main agentic workflow completes. Safe-jobs provide a powerful way to create sophisticated automation workflows while maintaining security through controlled job execution.