fix more docs

Author: dsyme

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

@@ -61,7 +61,7 @@ The compiler uses a **breadth-first search (BFS)** algorithm to process imports:
 
 **Processing order** follows BFS traversal:
 
-```
+```text
 Main Workflow
 ├── shared/tools.md        (1st - direct import)
 │   └── shared/base.md     (3rd - nested from tools.md)
@@ -117,84 +117,9 @@ safe-outputs:
 
 See [Imports Reference](/gh-aw/reference/imports/) for complete merge semantics.
 
-## Importing Agents from Repositories
-
-Agent files provide specialized AI instructions and behavior. You can import agents from external repositories to reuse expert-crafted prompts and configurations across teams and projects.
-
-### Creating a Shareable Agent
-
-Store agent files in `.github/agents/` of any repository:
-
-```markdown title="acme-org/ai-agents/.github/agents/code-reviewer.md"
----
-name: Expert Code Reviewer
-description: Specialized agent for comprehensive code review with security focus
-tools:
-  github:
-    toolsets: [pull_requests, repos]
----
-
-# Code Review Instructions
-
-You are an expert code reviewer with deep knowledge of:
-- Security best practices and OWASP guidelines
-- Performance optimization patterns
-- Code maintainability and readability
-- Testing strategies and coverage
-
-When reviewing code:
-1. Identify security vulnerabilities first
-2. Check for performance issues
-3. Ensure code follows team conventions
-4. Suggest specific improvements with examples
-```
-
-### Importing Remote Agents
+## Importing Agent Files
 
-Reference the agent using `owner/repo/path@version` format:
-
-```yaml wrap
----
-on: pull_request
-engine: copilot
-imports:
-  - acme-org/ai-agents/.github/agents/[email protected]
-permissions:
-  contents: read
-  pull-requests: write
----
-
-# PR Review Workflow
-The code reviewer agent will analyze this pull request and provide detailed feedback.
-```
-
-### Agent Versioning
-
-Use semantic versioning for production stability:
-
-```yaml wrap
-imports:
-  - acme-org/ai-agents/.github/agents/[email protected]  # Production
-  - acme-org/ai-agents/.github/agents/performance.md@main         # Latest
-  - acme-org/ai-agents/.github/agents/custom.md@abc123def         # Immutable
-```
-
-### Agent Collections
-
-Organizations can maintain libraries of specialized agents:
-
-```
-acme-org/ai-agents/
-└── .github/
-    └── agents/
-        ├── code-reviewer.md         # General code review
-        ├── security-auditor.md      # Security-focused analysis
-        ├── performance-analyst.md   # Performance optimization
-        ├── accessibility-checker.md # WCAG compliance
-        └── documentation-writer.md  # Technical documentation
-```
-
-Teams import agents based on workflow needs, with all agents benefiting from centralized updates and versioning.
+Agent files provide specialized AI instructions and behavior. See [Importing Copilot Custom Agent Files](/gh-aw/reference/copilot-custom-agents/) for details on creating and importing agent files from external repositories.
 
 ## Example: Modular Workflow with Imports
 
@@ -235,62 +160,6 @@ Perform web research using Tavily and respond to issues.
 
 **Result**: The compiled workflow includes both the Tavily MCP server from the import and the GitHub tools from the main workflow, with network permissions automatically merged to allow access to both `mcp.tavily.com` and GitHub API endpoints.
 
-## Real-World Scenario: Team-Wide Configuration
-
-A development team can create a shared configuration repository with reusable components:
-
-```
-acme-org/workflow-library/
-├── .github/
-│   └── agents/
-│       ├── code-reviewer.md         # Specialized code review agent
-│       ├── security-auditor.md      # Security-focused agent
-│       └── performance-analyst.md   # Performance optimization agent
-├── shared/
-│   ├── tools/
-│   │   ├── github-standard.md       # Standard GitHub API toolsets
-│   │   └── code-analysis.md         # Code quality tools
-│   ├── mcp/
-│   │   ├── tavily.md                # Web search
-│   │   └── database.md              # Database access
-│   └── config/
-│       ├── security-policies.md     # Security constraints
-│       └── notification-setup.md    # Notification settings
-└── workflows/
-    ├── issue-triage.md
-    ├── pr-review.md
-    └── release-automation.md
-```
-
-Individual workflows import required components and agents:
-
-```yaml wrap
----
-on: pull_request
-engine: copilot
-imports:
-  - acme-org/workflow-library/.github/agents/[email protected]
-  - acme-org/workflow-library/shared/tools/[email protected]
-  - acme-org/workflow-library/shared/tools/[email protected]
-  - acme-org/workflow-library/shared/config/[email protected]
-safe-outputs:
-  create-pull-request-review-comment:
-    max: 10
----
-
-# Code Review Agent
-Automated code review with security policy enforcement using shared agent.
-```
-
-**Benefits**:
-
-- **Consistency**: All workflows use same tool configurations and agent behavior
-- **Maintainability**: Update imports once, affects all workflows
-- **Versioning**: Pin to stable versions with semantic tags
-- **Modularity**: Mix and match components and agents as needed
-- **Governance**: Security policies and review standards enforced through imports
-- **Agent Sharing**: Reuse specialized agent instructions across teams and repositories
-
 ## Specification Formats and Validation
 
 Workflow and import specifications require minimum 3 parts (owner/repo/path) for remote imports. Explicit paths must end with `.md`. Versions can be semantic tags (`@v1.0.0`), branches (`@develop`), or commit SHAs. Identifiers use alphanumeric characters with hyphens/underscores (cannot start/end with hyphen).
@@ -300,20 +169,13 @@ Workflow and import specifications require minimum 3 parts (owner/repo/path) for
 - Repository: `owner/repo[@version]`
 - Short workflow: `owner/repo/workflow[@version]` (adds `workflows/` prefix and `.md`)
 - Explicit workflow: `owner/repo/path/to/workflow.md[@version]`
-- Agent import: `owner/repo/.github/agents/agent-name.md[@version]`
+- Agent file import: `owner/repo/.github/agents/agent-name.md[@version]`
 - Shared import: `owner/repo/shared/tools/config.md[@version]`
 - GitHub URL: `https://github.com/owner/repo/blob/main/workflows/ci-doctor.md`
 - Raw URL: `https://raw.githubusercontent.com/owner/repo/refs/heads/main/workflows/ci-doctor.md`
 
 ## Best Practices
 
-Use semantic versioning for stable workflows and agents, branches for development, and commit SHAs for immutability. Organize reusable components in `shared/` directories and agent files in `.github/agents/` with descriptive names. Review updates with `--verbose` before applying, test on branches, and keep local modifications minimal to reduce merge conflicts.
-
-When sharing agents across teams:
-
-- Use semantic versioning for production agents (`@v1.0.0`)
-- Document agent capabilities and requirements in frontmatter
-- Test agent updates in non-production workflows first
-- Maintain backwards compatibility within major versions
+Use semantic versioning for stable workflows and agent files, branches for development, and commit SHAs for immutability. Organize reusable components in `shared/` directories and agent files in `.github/agents/` with descriptive names. Review updates with `--verbose` before applying, test on branches, and keep local modifications minimal to reduce merge conflicts.
 
-**Related:** [CLI Commands](/gh-aw/setup/cli/) | [Workflow Structure](/gh-aw/reference/workflow-structure/) | [Frontmatter](/gh-aw/reference/frontmatter/) | [Imports](/gh-aw/reference/imports/) | [Custom Agents](/gh-aw/reference/copilot-custom-agents/)
+**Related:** [CLI Commands](/gh-aw/setup/cli/) | [Workflow Structure](/gh-aw/reference/workflow-structure/) | [Frontmatter](/gh-aw/reference/frontmatter/) | [Imports](/gh-aw/reference/imports/) | [Custom Agent Files](/gh-aw/reference/copilot-custom-agents/)

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

@@ -22,9 +22,7 @@ tools:
 
 ## Frontmatter Elements
 
-The frontmatter combines standard GitHub Actions properties (`on`, `permissions`, `run-name`, `runs-on`, `timeout-minutes`, `concurrency`, `env`, `environment`, `container`, `services`, `if`, `steps`, `cache`) with GitHub Agentic Workflows-specific elements (`description`, `source`, `imports`, `engine`, `strict`, `roles`, `features`, `plugins`, `runtimes`, `safe-inputs`, `safe-outputs`, `network`, `tools`).
-
-Tool configurations (such as `bash`, `edit`, `github`, `web-fetch`, `web-search`, `playwright`, `cache-memory`, and custom [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) [servers](/gh-aw/reference/glossary/#mcp-server)) are specified under the `tools:` key. Custom inline tools can be defined with the [`safe-inputs:`](/gh-aw/reference/safe-inputs/) (custom tools defined inline) key. See [Tools](/gh-aw/reference/tools/) and [Safe Inputs](/gh-aw/reference/safe-inputs/) for complete documentation.
+Below is a comprehensive reference to all available frontmatter fields for GitHub Agentic Workflows.
 
 ### Trigger Events (`on:`)