docs: add apm.yml manifest schema reference for integrators

[danielmeppiel]

Summary

Adds a spec-grade apm.yml manifest schema reference (docs/manifest-schema.md) for external integrators who need to parse or generate APM manifest files.

Motivation

External teams (e.g. GitHub Agentic Workflows) have asked for a declarative, self-contained schema reference to understand the apm.yml format without reading APM source code. This document serves as the canonical specification.

What's included

• Top-level fields — name, version, description, author, license, target, type, scripts
• APM dependency syntax — string shorthand (all URL forms: https, http, ssh, git@), object form, virtual packages (files, subdirectories, collections), canonical normalization rules
• MCP dependency syntax — string shorthand, object form, validation rules
• Compilation configuration — CompilationConfig fields and defaults
• Lockfile specification — apm.lock format and fields
• Integrator contract — requirements for tooling interoperability

Verification

All fields verified against source code:

• src/apm_cli/models/apm_package.py (APMPackage, DependencyReference, MCPDependency)
• src/apm_cli/compilation/agents_compiler.py (CompilationConfig)
• src/apm_cli/deps/lockfile.py (LockedDependency)
• src/apm_cli/compilation/target_detection.py (target enum values)

Also added a link to the new doc from docs/index.md.

[Copilot]

Pull request overview

Adds a new canonical documentation reference for the apm.yml manifest format aimed at external integrators, and links it from the docs index so it’s discoverable.

Changes:

• Added docs/manifest-schema.md describing apm.yml fields, dependency syntaxes, compilation config, and lockfile/integrator expectations.
• Linked the new manifest schema doc from docs/index.md.

Reviewed changes

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

File	Description
docs/manifest-schema.md	Introduces a spec-style reference for apm.yml, including dependency formats and lockfile/integrator contract.
docs/index.md	Adds a navigation link to the new manifest schema document.

Comments suppressed due to low confidence (2)

docs/manifest-schema.md:81

• Top-level target “Default: all” appears incorrect relative to the current target detection logic. If target is unset, the CLI auto-detects based on .github//.claude/ presence and falls back to minimal (AGENTS.md only) when neither folder exists. Please describe the default as “auto-detect” (and document the minimal outcome) rather than a fixed all default.

| | |
|---|---|
| **Type** | `enum<string>` |
| **Required** | No |
| **Default** | `all` |
| **Allowed values** | `vscode` · `agents` · `claude` · `all` |

Controls which output targets are generated during compilation. Unknown values are silently ignored (auto-detection takes over).

docs/manifest-schema.md:373

• Lockfile structure in this spec doesn’t match the actual apm.lock format written by the CLI. In LockFile.to_yaml(), dependencies is serialized as a YAML list of dependency dicts (each containing repo_url, resolved_commit, etc.), not as a map keyed by canonical dependency string. Please update the “Structure” section to reflect the list-based schema and the actual per-item fields/keys used in src/apm_cli/deps/lockfile.py.

```yaml
lockfile_version: "1"
generated_at:     <ISO 8601 timestamp>
apm_version:      <string>
dependencies:
  <canonical-dependency-string>:
    repo_url:        <string>          # Resolved clone URL
    host:            <string>          # Git host (optional, e.g. "gitlab.com")
    resolved_commit: <string>          # Full commit SHA
    resolved_ref:    <string>          # Branch/tag that was resolved
    version:         <string>          # Package version from its apm.yml
    virtual_path:    <string>          # Virtual package path (if applicable)
    is_virtual:      <bool>            # True for virtual (file/subdirectory) packages
    depth:           <int>             # 1 = direct, 2+ = transitive
    resolved_by:     <string>          # Parent dependency (transitive only)
    deployed_files:  <list<string>>    # Workspace-relative paths of installed files

</details>

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

docs/manifest-schema.md:170

• The APM dependency grammar/table currently models the base repo as owner/repo, but the implementation also supports Azure DevOps shorthand with dev.azure.com/org/project/repo and normalizes away an optional _git segment (as shown in the examples). To avoid integrators rejecting ADO manifests, please extend the grammar/field table to describe the ADO org/project/repo base shape (and mention that _git may appear in input but is not part of the canonical form).

Grammar (ABNF-style):

dependency = url_form / shorthand_form
url_form = ("https://" / "http://" / "ssh://git@" / "git@") clone-url
shorthand_form = [host "/"] owner "/" repo ["/" virtual_path] ["#" ref] ["@" alias]

</details>