docs: surface compilation.strategy=distributed default in concepts and compile reference (closes #1447)

[danielmeppiel]

TL;DR

Pure docs PR. Surfaces the compilation.strategy: distributed default in the two pages where users would actually look for it: the primitives-and-targets concepts ramp and the apm compile reference's Strategy modes section. No behavior change.

Closes #1447.

Why

#1447 reports legitimate UX surprise. The user observed:

when I ran [apm compile] it generated AGENTS.md and CLAUDE.md files in random subfolders that, frankly, shocked me [...] To find that compilation.strategy isn't set means the default is distributed, which it certainly seems to be.

The default IS distributed (src/apm_cli/compilation/agents_compiler.py:79) and that is intentional -- it follows the Minimal Context Principle so each agent harness only loads instructions relevant to the directory it is working in. But the default was effectively undocumented in the discoverable surfaces (concepts page, compile reference Strategy modes), buried only in a manifest-schema row and a parenthetical compile note.

This PR fixes the docs gap so the next user doesn't get the same shock.

Scope (deliberately narrow)

Per strategic-alignment review on #1447 (verdict: aligned-with-reservations, P4 UX floor), this PR is docs only:

1. Default-strategy and --clean default questions are out of scope. Flipping compilation.strategy from distributed to single-file, or flipping --clean to true by default, would be a silent behavior change that loses trust. Those belong in a separate RFC-style issue with a CHANGELOG BREAKING entry. Not this PR.
2. The Claude-duplication piece the user also flagged is already fixed-at-head via [BUG] compilation.strategy: single-file is ignored for CLAUDE.md output #1445 (agents_compiler.py:568-590 skips CLAUDE.md instructions when .claude/rules/*.md already exists).
3. Copilot-dedup parity -- on inspection, the analogous skip is missing for the AGENTS.md path when .github/instructions/ exists. Filed as perf/dedup: parity for Copilot AGENTS.md vs .github/instructions/ (sibling of #1445) #1550 for a separate, properly-scoped PR with full TDD; not folded here.

What changed

• docs/src/content/docs/concepts/primitives-and-targets.md: new "Where compiled context files land" section. Explains distributed placement is driven by applyTo: globs, that subdirectory AGENTS.md / CLAUDE.md files are intentional, and links forward to the compile reference and manifest schema. Mentions --single-agents and --clean as escape hatches.
• docs/src/content/docs/reference/cli/compile.md: expanded the existing Strategy modes section with a concrete distributed-layout example (root + scripts/AGENTS.md + tests/AGENTS.md) and a back-link to the concepts section so the user who lands on the reference page from the issue gets the full rationale.
• CHANGELOG.md: ### Documentation entry under [Unreleased], attributed to @tillig.

How to test

cd docs
npm install   # if not already
npm run dev

Then in the local docs site:

1. Navigate to Concepts -> Primitives and Targets, scroll to the new "Where compiled context files land" section. Verify the cross-links to apm compile and the manifest schema resolve.
2. Navigate to Reference -> apm compile, scroll to Strategy modes. Verify the new "Distributed layout example" code block renders and the back-link to the concepts section resolves.
3. grep -nP '[^[:print:][:space:]]' docs/src/content/docs/concepts/primitives-and-targets.md docs/src/content/docs/reference/cli/compile.md returns nothing (ASCII-only contract).

Out of scope (explicit)

• No .py changes. Lint contract not engaged.
• No new in-CLI warning when distributed mode places files in subdirs. Considered, deferred: a one-time ASCII info line could help, but adding it without telemetry on whether users currently want it risks adding noise to the most-run command. Capture as future RFC if the pattern recurs.
• No change to compilation.strategy default.
• No change to --clean default.

Tracking

• [BUG] compilation.strategy defaulting to distributed is unintuitive, under-documented #1447 -- closed by this PR.
• [BUG] compilation.strategy: single-file is ignored for CLAUDE.md output #1445 -- already shipped; referenced in the strategic-alignment notes above.
• perf/dedup: parity for Copilot AGENTS.md vs .github/instructions/ (sibling of #1445) #1550 -- new, filed during this work; covers the missing Copilot-side dedup parity. Not folded here.

[Copilot]

Pull request overview

Docs-only PR to reduce UX surprise by explicitly documenting that apm compile defaults to compilation.strategy: distributed, and showing what “distributed” output looks like in practice.

Changes:

• Document the distributed-by-default compilation strategy and its rationale (Minimal Context Principle) in the concepts ramp.
• Expand apm compile reference docs with a concrete distributed layout example and a cross-link to the concepts explanation.
• Add a Keep-a-Changelog entry under [Unreleased] for the documentation change.

Show a summary per file

File	Description
docs/src/content/docs/reference/cli/compile.md	Expands “Strategy modes” with the distributed default opt-out and a distributed layout example + cross-link.
docs/src/content/docs/concepts/primitives-and-targets.md	Adds a new section explaining where compiled context files land and why distributed placement creates subdir outputs.
CHANGELOG.md	Adds an Unreleased Documentation entry describing the docs updates.

Copilot's findings

• Files reviewed: 3/3 changed files
• Comments generated: 3