docs: document import path resolution modes (relative, repo-root-relative, cross-repo)

[Copilot]

Users didn't know that .github/agents/ imports required the .github/-prefix syntax, that repo-root-relative paths existed, or that cross-repo imports were already supported.

docs/reference/imports.md

Replaced the one-liner "Path Formats" section with a full Path Resolution section covering all three modes:

imports:
  # 1. Relative — resolved from .github/workflows/ (backward-compatible)
  - shared/mcp/tavily.md
  # 2. Repo-root-relative — paths starting with .github/ or /
  - .github/agents/my-expert-agent.md
  # 3. Cross-repo — fetched from GitHub at compile time
  - acme-org/shared-workflows/shared/reporting.md@v1.0.0

Includes: security constraints (/-prefixed paths restricted to .github/ and .agents/), backward-compatibility note, section references, and optional imports.

pkg/parser/schemas/main_workflow_schema.json

Updated description strings for the imports field, array, string item, path, and uses properties to surface all three resolution modes in IDE autocomplete and schema validation messages.

[Copilot]

Pull request overview

Updates the imports reference documentation and workflow JSON schema descriptions to clearly document how import paths are resolved (relative, repo-root-relative, and cross-repo).

Changes:

• Expanded docs/reference/imports.md to a detailed “Path Resolution” section describing the three supported import path modes and related constraints.
• Updated pkg/parser/schemas/main_workflow_schema.json imports descriptions so IDE/schema validation messages surface the supported path formats.

Show a summary per file

File	Description
docs/src/content/docs/reference/imports.md	Replaces the brief “Path Formats” note with a fuller “Path Resolution” explanation and examples for each mode.
pkg/parser/schemas/main_workflow_schema.json	Enhances imports field descriptions to document relative, repo-root-relative, and cross-repo formats in schema tooling.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (1)

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

• This sentence says repo-root-relative imports are “required” for importing from .github/agents/, but the previous example demonstrates that a relative path like ../agents/helper.md also works from the default .github/workflows/ directory. Consider rewording to avoid implying hard requirement (e.g., “recommended / stable / preferred”, or specify the exact cases where it’s required).

This form is required when workflows in different directories need to import the same shared file using a stable path, and is the supported way to import files from the `.github/agents/` directory.

• Files reviewed: 2/2 changed files
• Comments generated: 2

[Copilot]

The repo-root-relative description here is not always accurate when compiling workflows from a directory that is not under a .github/ ancestor (e.g., gh aw compile --dir custom/workflows). In that case ResolveIncludePath falls back to plain relative resolution (and /.github/... can be rejected as escaping the security scope), so .github/... and /... won’t necessarily resolve from the repo root. Please clarify the prerequisite/behavior (e.g., that repo-root-relative resolution is based on locating a .github/ ancestor to infer repo root).

This issue also appears on line 189 of the same file.

[Copilot]

This schema description states that paths starting with .github/ or / are resolved from the repository root, but in parser.ResolveIncludePath repo-root-relative resolution is only applied when a .github ancestor can be found from the provided baseDir; otherwise .github/... falls back to plain relative resolution and /... may be rejected by the security-scope check. Please tighten the wording to match the actual resolution rules so IDE/tooling messages don’t overpromise behavior.

See below for a potential fix:

      "description": "Workflow specifications to import. Supports array form (list of paths) or object form with 'aw' (agentic workflow paths) and 'apm-packages' (APM packages) subfields. Path resolution: (1) relative paths (e.g., 'shared/file.md') are resolved relative to the workflow's directory; (2) paths starting with '.github/' or '/' are only treated as repository-root-anchored when repository root context can be determined from the workflow location, and may otherwise be resolved relative to the workflow directory or rejected by path-scope checks; (3) paths matching 'owner/repo/path@ref' are fetched from GitHub at compile time (cross-repo).",
      "oneOf": [
        {
          "type": "array",
          "description": "Array of workflow specifications to import. Three path formats are supported: relative paths ('shared/file.md'), paths beginning with '.github/' or '/' that are treated as repository-root-anchored only when repository root context can be determined, and cross-repo paths ('owner/repo/path@ref'). Any markdown files under .github/agents directory are treated as custom agent files and only one agent file is allowed per workflow.",
          "items": {
            "oneOf": [
              {
                "type": "string",
                "description": "Import path. Use 'shared/file.md' for paths relative to the workflow directory, '.github/agents/my-agent.md' or '/path/from/repo/root' only when repository root context can be determined, or 'owner/repo/path@ref' for cross-repo imports. Markdown files under .github/agents/ are treated as agent configuration files."