Skip to content
6 changes: 3 additions & 3 deletions docs/src/content/docs/concepts/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Source: `src/apm_cli/deps/lockfile.py`.
### apm.yml

The package manifest. A YAML file at the package root that declares
`name`, `version`, `dependencies`, `scripts`, `targets` / `target`, and metadata. Both
`name`, `version`, `dependencies`, `scripts`, `targets` (singular `target` is deprecated), and metadata. Both
the unit of authoring and the unit of consumption -- a directory becomes
an APM package the moment it has an `apm.yml`.

Expand Down Expand Up @@ -253,10 +253,10 @@ Source: `src/apm_cli/models/apm_package.py`,

### target

The `targets:` field in `apm.yml` (or legacy `target:`). Names which harnesses the package
The `targets:` field in `apm.yml` (singular `target:` is deprecated). Names which harnesses the package
compiles for (`copilot`, `claude`, `grok-build`, `cursor`, `codex`, `gemini`,
`antigravity`, `opencode`, `windsurf`, `kiro`, `hermes`, `grok-bot`, or
`agent-skills`). `all` is a CLI `--target` value only. Drives which integrator runs and
`agent-skills`; `vscode` is a deprecated alias of `copilot`). `all` is a CLI `--target` value only. Drives which integrator runs and
which directories receive output during `apm install` and `apm compile`.

NOT the harness itself. Target is the declaration; the harness is the
Expand Down
4 changes: 2 additions & 2 deletions docs/src/content/docs/concepts/lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ targets](../primitives-and-targets/) for what each target receives.

**Common surprises**

- Re-running `apm init` in a directory that already has `apm.yml` warns and asks before overwriting it; `-y` overwrites without asking.
- `targets:` must contain at least one target. Omit the field (or leave legacy `target:` blank) when you want auto-detection at compile time.
- Re-running `apm init` in a directory that already has `apm.yml` warns and asks before overwriting it; `-y` overwrites without asking. Existing targets carry over, with deprecated singular `target:` rewritten to `targets:`.
- `targets:` must contain at least one target. Omit the field when you want auto-detection at compile time.

**Read more:** [`apm init` reference](/apm/reference/cli/init/), [package anatomy](/apm/concepts/package-anatomy/).

Expand Down
4 changes: 2 additions & 2 deletions docs/src/content/docs/concepts/primitives-and-targets.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ GitHub Copilot CLI canvas extensions: a directory bundle whose entry file is `ex

## Target catalogue

Each target is identified by a slug used in `apm.yml`'s `targets:` field or on the `--target` flag. `apm.yml` accepts the canonical targets (`copilot`, `claude`, `grok-build`, `cursor`, `opencode`, `codex`, `gemini`, `antigravity`, `windsurf`, `kiro`, `agent-skills`, `hermes`, `grok-bot`). `agent-skills`, `antigravity`, `hermes`, and `grok-bot` can be selected explicitly or listed in `apm.yml`, but they are not auto-detected or included in `all`. The output directory is where APM writes deployed primitives; at project scope, skills for `copilot`, `cursor`, `codex`, `gemini`, `opencode`, and `windsurf` land in the shared `.agents/skills/`.
Each target is identified by a slug used in `apm.yml`'s `targets:` field or on the `--target` flag. `apm.yml` accepts the canonical targets (`copilot`, `claude`, `grok-build`, `cursor`, `opencode`, `codex`, `gemini`, `antigravity`, `windsurf`, `kiro`, `agent-skills`, `hermes`, `grok-bot`). `vscode` is a deprecated alias of `copilot`. `intellij` is never recorded in `apm.yml`; use `copilot` for GitHub Copilot in JetBrains IDEs. `agent-skills`, `antigravity`, `hermes`, and `grok-bot` can be selected explicitly or listed in `apm.yml`, but they are not auto-detected or included in `all`. The output directory is where APM writes deployed primitives; at project scope, skills for `copilot`, `cursor`, `codex`, `gemini`, `opencode`, and `windsurf` land in the shared `.agents/skills/`.

| Slug | Output directory | Compile family |
|---|---|---|
Expand All @@ -97,7 +97,7 @@ Each target is identified by a slug used in `apm.yml`'s `targets:` field or on t

Notes per target:

- **copilot** -- GitHub Copilot (CLI + IDE). User scope: instructions, prompts, agents, and hooks deploy under `~/.copilot/` (instructions as `~/.copilot/instructions/**/*.instructions.md`, mirroring the project-scope layout); skills go to `~/.agents/skills/`; a dependency canvas deploys to `~/.copilot/extensions/`.
- **copilot** -- GitHub Copilot (CLI + IDE). Project MCP servers go to root `.mcp.json`, shared with Claude Code (which ignores Copilot's `tools` allow-list). User scope: instructions, prompts, agents, and hooks deploy under `~/.copilot/` (instructions as `~/.copilot/instructions/**/*.instructions.md`, mirroring the project-scope layout); skills go to `~/.agents/skills/`; a dependency canvas deploys to `~/.copilot/extensions/`.
- **claude** -- Claude Code. Full user-scope support. Hooks merge into `.claude/settings.json` rather than living as separate files.
- **grok-build** -- Grok Build. Rules, agents, commands, and skills use `.grok/`; compiled instructions also produce `AGENTS.md`.
- **cursor** -- Cursor IDE. Rules use the `.mdc` extension. Full user-scope support; instructions deploy to `~/.cursor/rules/*.mdc`, which local Cursor 2.1+ clients include in context (see [Cursor user scope](../../reference/targets-matrix/#cursor)).
Expand Down
15 changes: 11 additions & 4 deletions docs/src/content/docs/consumer/install-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,9 @@ devDependencies:
apm install
```

Supported reference forms: `owner/repo` shorthand (with optional
`#ref` for a tag, branch, or commit), full HTTPS or SSH git URLs,
Supported reference forms: `owner/repo` shorthand (on the manifest's
[`default_host`](../../reference/manifest-schema/#315-default_host) when set,
with optional `#ref` for a tag, branch, or commit), full HTTPS or SSH git URLs,
virtual subdirectory paths into a monorepo, single-file references,
and local paths starting with `./`, `../`, or `/`. For private hosts
and tokens, see [Authentication](../authentication/).
Expand Down Expand Up @@ -177,12 +178,15 @@ same bytes. Commit the lockfile.

:::note[Lockfile replay]
Plain `apm install` and `apm install --frozen` replay locked commits for
unchanged dependencies, including transitive packages, and reuse matching
unchanged dependencies, including transitive packages and marketplace entries
(without contacting the marketplace, except for a package whose locked MCP or
LSP servers have no `apm_modules/` copy), and reuse matching
[cached package content](../../reference/cli/cache/) when available. This keeps
mutable branches and tags pinned to their recorded commits.

Run [`apm update`](../../reference/cli/update/) or `apm install --refresh` to
establish current upstream mutable refs. `apm outdated` checks the same current
establish current upstream mutable refs; both revalidate marketplaces and fail
rather than use stale cached data. `apm outdated` checks the same current
state without changing the lockfile. See the
[lockfile specification](../../reference/lockfile-spec/) for the replay
contract.
Expand Down Expand Up @@ -281,6 +285,9 @@ and the full flag reference, or run `apm install --help`.
- **Drift between `apm_modules/` and the lockfile.** Run
`apm audit --ci` locally to reproduce the CI gate; see
[Update and refresh](../update-and-refresh/) to recover.
- **Lockfile written by a newer APM.** APM refuses to change or replay it,
naming both versions. Upgrade APM; there is no override. See
[Lockfile written by a newer APM](../../troubleshooting/install-failures/#lockfile-written-by-a-newer-apm).
- **Skipped symlinked agent source.** `apm install` warns and skips agent
files or directories that are symlinks (for example
`.apm/agents -> ../agents`). Fix by shipping real files and directories in
Expand Down
12 changes: 6 additions & 6 deletions docs/src/content/docs/enterprise/apm-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,10 +136,10 @@ dependencies:

mcp:
transport:
allow: [http, stdio] # explicit allow list: blocks sse and streamable-http
allow: [http, stdio] # http = streamable-http; blocks sse
```

Three rules: only contoso and microsoft packages are allowed, untrusted-org is blocked outright, and MCP transports are restricted to `http` and `stdio`. With no `mcp.transport.allow` set, all transports are permitted by default; the example above shows how to restrict.
Three rules: only contoso and microsoft packages are allowed, untrusted-org is blocked outright, and MCP transports are restricted to `http` and `stdio`, judged on the transport install writes (see [`transport.allow`](../policy-reference/#transportallow)). With no `mcp.transport.allow` set, all transports are permitted by default; the example above shows how to restrict.

> **Note on transitive MCPs:** the `mcp.trust_transitive` policy field is currently parsed but not enforced -- consent is a pinned [`apm approve`](../../reference/cli/approve/#pinned-approvals) grant in `apm.yml`, or the one-run `--trust-transitive-mcp` flag (defaults to deny). See [Governance Guide section 5a](../governance-guide/#5a-what-does-not-enforce-policy) for the full list of parsed-but-not-enforced fields.

Expand Down Expand Up @@ -186,7 +186,7 @@ For setup, see [Enforce in CI](../enforce-in-ci/).

## Tighten-only inheritance

A repo can have its own `apm-policy.yml` that **extends** the org policy. Children can only **tighten** rules, never relax them. This means a repo can be more restrictive than the org, but cannot widen what the org has allowed.
A repo can have its own `apm-policy.yml` that **extends** the org policy (discovery finds only the org policy; pass a repo file to `apm audit --ci --policy`). Children can only **tighten** rules, never relax them. This means a repo can be more restrictive than the org, but cannot widen what the org has allowed.

The merge rules in plain English:

Expand Down Expand Up @@ -222,8 +222,8 @@ dependencies:
`apm install` halts before any file is written. The CLI emits a single-line violation followed by a remediation hint:

```
[x] Policy violation: untrusted-org/random-skills -- denied by pattern: untrusted-org/**
Run `apm audit --ci --policy org` for the full report.
[x] Policy violation: github.com/untrusted-org/random-skills -- denied by pattern: untrusted-org/**
Blocked by org policy at org:<org>/.github-private (dependency-denylist) -- remove `github.com/untrusted-org/random-skills` from apm.yml, contact admin to update policy, or use `--no-policy` for one-off bypass
```

Exit code is non-zero so CI fails. Run `apm audit --ci --policy org` (in CI or locally) for the full SARIF report including which policy file in the inheritance chain produced the rule.
Expand Down Expand Up @@ -276,7 +276,7 @@ apm policy status --policy-source contoso/governance # any owner/repo
apm audit --ci --policy ./apm-policy.yml
```

`apm install` has no `--policy` flag — discovery runs automatically from your git remote. Use `--no-cache` to force a fresh fetch.
`apm install` has no `--policy` flag -- discovery runs automatically from your git remote. Add `--no-cache` to `apm policy status` or `apm audit` to force a fresh fetch.

### 3. The schema in one screen

Expand Down
27 changes: 13 additions & 14 deletions docs/src/content/docs/enterprise/governance-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ The scope matrix below is the contract. Every row maps a security or operational
| Registry source policy | `registry_source.require`, `.allow_non_registry` | `registry-source` | Yes | Yes |
| MCP server allowlist | `mcp.allow` | `mcp-allowlist` | Yes (direct + transitive) | Yes |
| MCP server denylist | `mcp.deny` | `mcp-denylist` | Yes (direct + transitive) | Yes |
| MCP transport allowlist | `mcp.transport.allow` | `mcp-transport` | Yes | Yes |
| MCP transport allowlist | `mcp.transport.allow` | `mcp-transport` | Yes (transport install writes; also `apm update`) | Yes |
| Self-defined MCP control | `mcp.self_defined` | `mcp-self-defined` | Yes | Yes |
| Compilation target allowlist | `compilation.target.allow` / `.enforce` | `compilation-target` | Yes (post-targets phase, effective selection) | Yes (targets declared in `apm.yml`) |
| Compilation strategy | `compilation.strategy.enforce` | `compilation-strategy` | `[i] audit-only` | Yes |
Expand Down Expand Up @@ -183,7 +183,7 @@ Policies can extend other policies up to 5 levels deep (`MAX_CHAIN_DEPTH = 5`, e

```mermaid
graph TD
Hub["enterprise-hub-org/.github/<br/>apm-policy.yml<br/>broad allow lists,<br/>enforcement: warn"] --> Org["contoso/.github/<br/>apm-policy.yml<br/>extends: enterprise-hub-org<br/>adds deny + tightens<br/>enforcement: block"]
Hub["enterprise-hub-org/.github/<br/>apm-policy.yml<br/>broad allow lists,<br/>enforcement: warn"] --> Org["contoso/.github/<br/>apm-policy.yml<br/>extends: enterprise-hub-org/.github<br/>adds deny + tightens<br/>enforcement: block"]
Org --> Repo["contoso/web-app/<br/>apm.yml policy stanza<br/>policy.hash pin,<br/>fetch_failure_default: block"]
Hub --> Merge["[*] merge_policies()<br/>tighten-only:<br/>allow=intersect, deny=union,<br/>enforcement=max(...),<br/>max_depth=min(...),<br/>require_pinned_constraint=OR"]
Org --> Merge
Expand Down Expand Up @@ -222,7 +222,7 @@ mcp:
```yaml
name: "Contoso engineering"
version: "1.0.0"
extends: "enterprise-hub-org"
extends: "enterprise-hub-org/.github"
enforcement: block
dependencies:
deny:
Expand All @@ -236,9 +236,9 @@ mcp:
**Repo** -- `contoso/web-app/apm.yml`:

```yaml
packages:
- name: contoso/web-standards
version: "^1.0"
dependencies:
apm:
- contoso/web-standards#v1.0.0
policy:
hash: "sha256:abc123..." # pin the fetched org policy
fetch_failure_default: block # fail-closed if discovery fails
Expand All @@ -255,11 +255,11 @@ policy:
| `mcp.transport.allow` | `stdio` | Org narrowed `[stdio, http]` to `[stdio]`. Intersect rule. |
| `mcp.self_defined` | `deny` | Org escalated. |

**Counter-example: a child cannot relax a parent.** If `contoso/web-app/apm.yml` tried to override the org's `block` back down to `warn`:
**Counter-example: a child cannot relax a parent.** If a team policy that extends the org policy tried to set the org's `block` back down to `warn`:

```yaml
policy:
enforcement: warn # rejected: org policy is block; child cannot relax
extends: "contoso/.github"
enforcement: warn # dropped: org policy is block; child cannot relax
```

The merge rule for `enforcement` is `max(parent, child)` ordered `warn < block`, so the org's `block` wins. The child's `warn` is silently dropped from the effective policy. The same applies to allow-list widening (intersect rule) and deny-list removal (union rule): tightening flows down, relaxation does not.
Expand Down Expand Up @@ -306,7 +306,7 @@ When `apm install` returns exit code 0 and the effective org policy is in `enfor

- Every APM dependency declared in `apm.yml` matches `dependencies.allow` and is not matched by `dependencies.deny`.
- Every package in `dependencies.require` is present and at the required version (with one nuance: `require_resolution: project-wins` downgrades version mismatches to warnings, by design).
- Every direct MCP server matches `mcp.allow`, is not matched by `mcp.deny`, uses an allowed transport, and respects the `mcp.self_defined` rule.
- Every direct MCP server matches `mcp.allow`, is not matched by `mcp.deny`, uses an allowed transport (the one install writes; a registry server APM cannot resolve fails), and respects the `mcp.self_defined` rule.
- Every transitive MCP server discovered from APM packages was re-checked against the same `mcp.*` rules in a second pass.
- The effective target selection (`--target`, `apm.yml`, `apm config target`, or auto-detection) includes `compilation.target.enforce` when it is set; otherwise every selected target is in `compilation.target.allow`. `enforce` takes precedence, so `allow` is not checked when both are set. Targets compare after aliases resolve (`vscode` is `copilot`).
- The fetched policy file matched any `policy.hash` pin in `apm.yml`. If the hash did not match, install failed closed regardless of `fetch_failure_default` -- hash-mismatch is unconditionally fail-closed in non-dry-run install paths. (`apm install --dry-run` logs the mismatch but does not exit non-zero -- see section 14 gap.)
Expand Down Expand Up @@ -354,7 +354,7 @@ Workarounds when the network is unreliable:
| Network failure (`cache_miss_fetch_fail`) | Fail-OPEN, log warning, install proceeds with no policy | `policy.fetch_failure_default: block` in `apm.yml` | [policy-reference#95-network-failure-semantics](../policy-reference/#95-network-failure-semantics) |
| Cached stale (past effective `cache.ttl`, within the 7-day ceiling; refresh failed) | Warn and proceed with cached policy | `fetch_failure: block` set in the cached org policy itself | [policy-reference#95-network-failure-semantics](../policy-reference/#95-network-failure-semantics) |
| Malformed YAML (`malformed`) (org policy file) | Fail-OPEN by default | `policy.fetch_failure_default: block` | `policy/parser.py` |
| **No policy resolved (`no_git_remote` / `absent` / `empty`)** | **Fail-OPEN, log warning** | `policy.fetch_failure_default: block` in `apm.yml` -- applies to BOTH `apm install` and `apm audit --ci` | [policy-reference#951-no-policy-outcomes](../policy-reference/#951-no-policy-outcomes-no_git_remote--absent--empty) |
| **No policy resolved (`no_git_remote` / `absent` / `empty`)** | **Fail-OPEN**; `apm audit --ci` warns, `apm install` warns on `empty` and shows the others only with `--verbose` | `policy.fetch_failure_default: block` in `apm.yml` -- applies to BOTH `apm install` and `apm audit --ci` | [policy-reference#951-no-policy-outcomes](../policy-reference/#951-no-policy-outcomes-no_git_remote--absent--empty) |
| Hash-mismatch (project pin vs fetched) | **Always fail-CLOSED** | n/a (cannot be relaxed) | [policy-reference#95-network-failure-semantics](../policy-reference/#95-network-failure-semantics) |
| Garbage response | Fail-OPEN by default | `policy.fetch_failure_default: block` | [policy-reference#95-network-failure-semantics](../policy-reference/#95-network-failure-semantics) |
| **Explicit `apm audit --ci --policy <path\|url\|owner/repo>` cannot be loaded** (missing file, unreachable, malformed, garbage, not found) | **Always fail-CLOSED** (`[x]`, exit 1) | n/a -- `policy.fetch_failure_default` does not apply; `--policy org` keeps discovery semantics | [policy-reference#95-network-failure-semantics](../policy-reference/#95-network-failure-semantics) |
Expand Down Expand Up @@ -413,7 +413,7 @@ jobs:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: { python-version: "3.12" }
- run: pip install apm-cli==X.Y.Z # REPLACE: pin to current version, see /installation
- run: pip install apm-cli==X.Y.Z # REPLACE: pin to current version, see /installation; audit refuses a lockfile from a newer APM
- run: apm install
- run: apm audit --ci -f sarif --output apm-audit.sarif
- uses: github/codeql-action/upload-sarif@v3
Expand Down Expand Up @@ -574,7 +574,6 @@ mcp:
compilation:
target:
allow: ["copilot", "claude"]
enforce: true
```

**Hub + org + repo (100+ repos)** -- enterprise hub with broad allows, org extending and tightening, repos pinning the hash:
Expand All @@ -588,7 +587,7 @@ dependencies:
allow: ["microsoft/*", "contoso/*", "partner-corp/*"]

# contoso/.github-private/apm-policy.yml
extends: "enterprise-hub-org"
extends: "enterprise-hub-org/.github-private"
enforcement: block
dependencies:
deny: ["untrusted-org/*"]
Expand Down
Loading