Add dedicated APM Dependencies reference page

[Copilot]

The dependencies: section in the frontmatter reference undersold APM: no link to the docs site, no explanation of the reproducibility story, missing plugin support, no version-pinning examples, and no mention of the underlying apm pack/apm unpack commands.

Changes

New page: docs/src/content/docs/reference/dependencies.md

Full APM dependencies reference (sidebar order 330) covering:

• APM docs link — https://microsoft.github.io/apm/ in the opening paragraph
• Reproducibility & governance — apm.lock pins packages to exact commit SHAs; lock diffs are PR-reviewable; links to the APM governance guide
• Plugins — primitive list now includes plugins (Claude plugin.json format)
• Expanded package reference formats table — owner/repo, owner/repo/path, owner/repo#ref
• Full examples block — full package, individual primitive, plugin, version-pinned (#v2.0, #main), and git URL with sub-path/ref:

dependencies:
  - microsoft/apm-sample-package
  - github/awesome-copilot/plugins/context-engineering
  - microsoft/apm-sample-package#v2.0
  - git: https://github.com/acme/coding-standards.git
    path: instructions/security
    ref: v2.0

• apm pack / apm unpack named explicitly in the compilation behavior section, with a link to the pack and distribute guide for local debugging
• Reference table collecting all relevant URLs (APM docs, governance, pack guide, gh-aw integration, apm-action)

Updated: frontmatter.md

The dependencies: entry is now a concise summary with a version-pinning example, pointing to the new dedicated page for full details.

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[Copilot]

Pull request overview

Adds a dedicated documentation page for APM dependency management and updates the frontmatter reference to link to it, aiming to better explain formats, reproducibility, and pack/unpack behavior.

Changes:

• Added a new APM Dependencies reference page (reference/dependencies.md) with formats, examples, and related links.
• Updated the dependencies: section in the frontmatter reference to be a shorter summary and to link to the dedicated page.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
docs/src/content/docs/reference/frontmatter.md	Replaces the detailed dependencies: documentation with a concise description, adds a version-pinning example, and links to the new dependencies reference page.
docs/src/content/docs/reference/dependencies.md	New standalone reference page describing dependencies: formats, examples, compilation behavior, and external APM resources.

---

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

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

The docs now show version pinning via owner/repo#ref (e.g. microsoft/apm-sample-package#v2.0), but the compiler’s frontmatter JSON schema currently rejects # in dependencies entries (see pkg/parser/schemas/main_workflow_schema.json where dependencies item pattern is ^[a-zA-Z0-9_-]+/[a-zA-Z0-9_./-]+$). As written, users following this example will fail schema validation at compile time.

Either remove the #ref example/claims here, or update the schema (and any related validation/docs) to explicitly allow #ref for dependency entries.

[Copilot]

This page documents owner/repo#ref dependency references, but the current frontmatter schema disallows # in dependencies entries (see pkg/parser/schemas/main_workflow_schema.json → dependencies item pattern: ^[a-zA-Z0-9_-]+/[a-zA-Z0-9_./-]+$). Users following this format will hit a schema validation error during compilation.

Either adjust the docs to match the schema (no #ref), or update the schema (and ideally add tests) to permit optional #ref suffixes for dependency strings.

[Copilot]

The example shows a dependencies entry as an object (- git: … path: … ref: …), but gh-aw only extracts dependency entries as strings (see extractAPMDependenciesFromFrontmatter in pkg/workflow/frontmatter_extraction_metadata.go) and renders them as - <string> lines for microsoft/apm-action (see GenerateAPMPackStep in pkg/workflow/apm_dependencies.go). This object-form per-item reference won’t compile/work.

Either remove this example, or extend the schema + frontmatter extraction + pack-step generation to support structured dependency objects and map them to whatever input format apm-action expects.

Suggested change

	# Git URL with sub-path and ref (object format)
	- git: https://github.com/acme/coding-standards.git
	path: instructions/security
	ref: v2.0