docs: surface compilation.strategy=distributed default (closes #1447) (#1551)

Add a 'Where compiled context files land' section to the
primitives-and-targets concepts page explaining that apm compile
defaults to distributed placement (per-directory AGENTS.md/CLAUDE.md
driven by applyTo: scopes), and a distributed-layout example to the
apm compile reference's Strategy modes section.

Default behavior is unchanged. The strategy default and --clean
default are deliberately out of scope; flipping them is an RFC.

Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Documentation
+
+- Surface the `compilation.strategy: distributed` default in the
+  concepts ramp and `apm compile` reference so users understand why
+  `apm compile` may add `AGENTS.md` / `CLAUDE.md` files in
+  subdirectories driven by `applyTo:` scopes. Adds a new "Where
+  compiled context files land" section to the primitives-and-targets
+  page and a distributed-layout example in the compile reference.
+  Default behavior is unchanged. (closes #1447) -- by @tillig
+  
 ### Fixed
 
 - Linux standalone `apm` binaries no longer fail git shared-cache clones with shared-library symbol lookup errors caused by PyInstaller dynamic-library paths leaking into child processes. (closes #1534)

docs/src/content/docs/concepts/primitives-and-targets.md

@@ -121,6 +121,31 @@ How to read a cell:
 - `plugins / *` -- APM unpacks the plugin at install time into the primitives in the rows above; routing then follows those rows.
 - `MCP servers / *` -- APM writes the harness's standard MCP config. Transitive MCP servers brought in by deep dependencies must be explicitly declared or trusted with `--trust-transitive-mcp` -- effectively `gated` for those, `native` for direct dependencies.
 
+## Where compiled context files land
+
+`apm compile` defaults to **distributed** placement: instead of one
+monolithic `AGENTS.md` / `CLAUDE.md` at the repo root, APM writes a
+focused target file next to each directory that has matching
+instructions. The placement is driven by each instruction's `applyTo:`
+glob in its frontmatter. For example, an instruction with
+`applyTo: "scripts/**"` lands in `scripts/AGENTS.md` rather than the
+root file.
+
+This means a fresh `apm compile` may create new `AGENTS.md` /
+`CLAUDE.md` files in subdirectories you did not previously touch.
+That is intentional -- it follows the **Minimal Context Principle**
+so each agent only loads instructions relevant to the directory it is
+working in. If you prefer one combined file at the project root, run
+`apm compile --single-agents` (or set `compilation.single_file: true`
+in `apm.yml`).
+
+To remove distributed files that are no longer produced (e.g. after
+deleting or rescoping an instruction), run `apm compile --clean`.
+
+For the full strategy reference and flag semantics, see
+[`apm compile`](/apm/reference/cli/compile/#strategy-modes) and
+[manifest schema: `compilation.strategy`](/apm/reference/manifest-schema/).
+
 ## Dev-only primitives
 
 Mark a primitive as dev-only when it is useful to the package author but should not ship to consumers: release checklists, internal debugging agents, test-fixture skills, anything tied to your own infrastructure. Author such primitives outside `.apm/` (typically `dev/`) and reference them under `devDependencies` in `apm.yml`. `apm pack` excludes them; `apm install --dev` deploys them locally.

docs/src/content/docs/reference/cli/compile.md

@@ -207,11 +207,32 @@ There is no `--strategy` flag. Compilation runs in one of two modes:
 - **Distributed (default)** -- writes a tree of focused target files
   (e.g. `AGENTS.md`, `CLAUDE.md`) next to the code they apply to, plus
   per-target subdirectories. This is the recommended mode and follows
-  the Minimal Context Principle.
+  the Minimal Context Principle. Set `compilation.strategy:
+  single-file` (or `compilation.single_file: true`) in `apm.yml` to
+  opt out.
 - **Single-file (`--single-agents`)** -- writes one combined file at
   `--output` (default `AGENTS.md`). Use when a harness or workflow
   requires a single context file.
 
+### Distributed layout example
+
+For a project with two scoped instructions
+(`applyTo: "scripts/**"` and `applyTo: "tests/**"`) plus a generic
+one (no `applyTo:`), `apm compile` writes:
+
+```
+AGENTS.md            # generic instructions only
+scripts/AGENTS.md    # instructions scoped to scripts/**
+tests/AGENTS.md      # instructions scoped to tests/**
+```
+
+Each agent harness then loads only the file nearest the code it is
+working in. If you did not expect new `AGENTS.md` / `CLAUDE.md` files
+in subdirectories, this is the distributed default in effect; see
+[Where compiled context files land](../../../concepts/primitives-and-targets/#where-compiled-context-files-land)
+for the rationale, or pass `--single-agents` for a single-file
+output.
+
 ## Exit codes
 
 | Code | Meaning |