diff --git a/docs/src/content/docs/getting-started/first-package.md b/docs/src/content/docs/getting-started/first-package.md
index 1d62e8169..f92418586 100644
--- a/docs/src/content/docs/getting-started/first-package.md
+++ b/docs/src/content/docs/getting-started/first-package.md
@@ -225,6 +225,9 @@ in the current directory. To target explicitly, see the
 > plain `agents`-protocol hosts). Gemini also receives commands, skills,
 > hooks, and MCP via `apm install`. Copilot, Claude Code, and Cursor read
 > the per-skill directories directly -- no compile step needed.
+> If your project commits those generated files, set `targets:` in `apm.yml`
+> to keep the committed set consistent across machines. See
+> [Pin committed output with targets:](/apm/reference/cli/compile/#pin-committed-output-with-targets).
 
 Now open Copilot or Claude in this project. Ask "draft a PR description for
 my last commit". The `pr-description` skill activates on its own. To get the
diff --git a/docs/src/content/docs/reference/cli/compile.md b/docs/src/content/docs/reference/cli/compile.md
index 6bf479a22..51de31abf 100644
--- a/docs/src/content/docs/reference/cli/compile.md
+++ b/docs/src/content/docs/reference/cli/compile.md
@@ -97,6 +97,39 @@ use `apm install` or `apm deps update` when you want shared
 | `--dry-run` | Show placement decisions without writing files. |
 | `-v, --verbose` | Show source attribution and optimizer analysis. |
 
+## Pin committed output with targets:
+
+`apm compile` generates root context files: `AGENTS.md`, `CLAUDE.md`,
+`GEMINI.md`, `.github/copilot-instructions.md` (see
+[Output layout per target](#output-layout-per-target) below for the
+full per-target breakdown). Teams that commit these files into source
+control face a consistency problem: without `targets:` set in `apm.yml`,
+auto-detection decides which files to produce based on which tool folders
+exist on the current machine. A contributor with only `.claude/` locally
+produces `claude` output only; a developer who also has `.github/`
+triggers the two-or-more-folders rule and gets the full `all` expansion
+-- producing `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`,
+`.github/copilot-instructions.md`, and every other target. The committed
+set silently tracks whoever last ran `apm compile`.
+
+Set `targets:` in `apm.yml` to declare exactly which agent formats the
+project supports. Every run of `apm compile` -- local developer, CI,
+cloud agent -- then writes the same files regardless of which tool
+folders exist on that machine:
+
+```yaml
+# apm.yml
+targets: [claude, cursor]   # compile writes exactly these two sets; nothing else
+```
+
+This makes the committed generated files deterministic for humans,
+cloud agents, and contributors who do not run `apm compile` locally
+and rely on the checked-in artifacts.
+
+Accepted values: `copilot`, `claude`, `cursor`, `opencode`, `codex`,
+`gemini`, `windsurf`, `all`. Full reference:
+[manifest schema -- targets](../../../reference/manifest-schema/#36-target).
+
 ## Examples
 
 Compile for whatever the project is set up for:
diff --git a/docs/src/content/docs/reference/manifest-schema.md b/docs/src/content/docs/reference/manifest-schema.md
index 2d5a027eb..924261784 100644
--- a/docs/src/content/docs/reference/manifest-schema.md
+++ b/docs/src/content/docs/reference/manifest-schema.md
@@ -159,6 +159,16 @@ A plural alias `targets:` (YAML list only) is also accepted and takes precedence
 | `all` | All targets. Cannot be combined with other values in a list. |
 | `minimal` | `AGENTS.md` only at project root. **Auto-detected only**: this value MUST NOT be set explicitly in manifests; it is an internal fallback when no target folder is detected. |
 
+:::tip[Deterministic committed output]
+Teams that commit the files `apm compile` generates face a consistency problem:
+without `targets:` set, auto-detection decides which files to produce based on
+which tool folders exist on the local machine. The committed set silently tracks
+whoever last ran `apm compile`. Setting `targets:` makes the output deterministic
+for every developer, CI runner, and cloud agent that relies on the checked-in
+generated files without running `apm compile` locally. See
+[Pin committed output with targets:](./cli/compile/#pin-committed-output-with-targets).
+:::
+
 ### 3.7. `type`
 
 | | |