[BUG] `compilation.strategy` defaulting to `distributed` is unintuitive, under-documented

[tillig]

Describe the bug

In initializing a new, fairly empty repo, I set up apm with some rules I know I'd use in fleshing things out. At the time, I had only one shell script in the repo, in a scripts/ folder, and was going to continue things.

I added my various instructions for things like shell scripts, TypeScript, etc., to apm.yml and did install/compile.

I was not expecting it, but suddenly AGENTS.md and CLAUDE.md showed up in my scripts/ folder.

This is currently only documented in two somewhat out-of-the-way places:

1. In the apm compile docs, as a small note.
2. In the manifest schema docs, noting the configuration setting.

I haven't seen this before because I've always added apm to existing, larger repos that wouldn't necessarily cause this distribution to occur.

Note this also somewhat overlaps with #1138 (use of .claude/rules/ over including instructions right in CLAUDE.md) and #1445 (compilation.strategy is ignored for CLAUDE.md generation).

To Reproduce

Steps to reproduce the behavior:

1. Create some instructions for shell scripts with frontmatter applyTo: *.sh
2. Create some instructions for markdown with frontmatter applyTo: *.md
3. Add an apm.yml that includes both instructions. Add targets for claude, codex, copilot.
4. Create a folder scripts/ and put a shell script in there.
5. apm install
6. apm compile

You will end up with:

.
|-.claude/
|  +-rules/
|    +-markdown.md
|    +-shell.md
|-.github/
|  +-instructions/
|    +-markdown.instructions.md
|    +-shell.instructions.md
|-scripts/
|  +-AGENTS.md # has the *.sh instructions
|  +-CLAUDE.md # has the *.sh instructions
|-AGENTS.md # has the *.md instructions
|-CLAUDE.md # has the *.md instructions

This was unexpected because it was a brand new repo I was in the process of working through. I wouldn't expect the output of apm compile to change where various generated files are. Assuming that's intentional, it also seems that apm compile should have --clean on by default (or perhaps act based on compilation.strategy) because I can't imagine a time where you wouldn't want to clean up orphaned distributed files.

(Again, this ties to #1445 - apm compile --clean doesn't actually clean up orphaned CLAUDE.md files at the moment, which added to the confusion here.)

Expected behavior

I expect:

• Documentation in more places that touch on this, like maybe "Primitives and Targets" since that speaks to the outputs.
• Consistency across commands and the lifecycle. If it's running in distributed mode, both apm install and apm compile should default to managing things in a distributed lifecycle; if it's running in single-file mode, both apm install and apm compile should behave as such. I shouldn't have to "know" to run with --clean when I'm in one lifecycle and not the other. The inconsistency is a UX surprise.
• Deduplication of instructions. If it's in .claude/rules it doesn't make sense to also put it conditionally in CLAUDE.md. If it's in .github/instructions for Copilot, it doesn't make sense to duplicate it in AGENTS.md. (Or, should you choose, always put it in AGENTS.md and don't put it in .github/instructions.) If the principle this behavior is going for is "minimal context" then it's failing on the grounds of the duplication.

---

I'm not entirely sure how this should be fixed or I'd submit PRs for it. It seems like unifying the behavior of the CLI across lifecycle may be a somewhat breaking change. Once the deduplication happens (if it happens?) it seems like the documentation would change, so based on #1138 I'm not sure what to document.

If the team here can provide some guidance, I'd be 100% happy to contribute to the solution.