Problem

When initializing APM in a project that already has a hand-written AGENTS.md, running apm install silently overwrites the file with generated content. Any existing content not represented in .apm/ source files is lost without warning, backup, or diff.

What happened

I had a carefully maintained AGENTS.md with ~570 lines of project-specific instructions (backlog-md CLI usage, security rules, skills table, workflow documentation). When I ran apm install to set up srid/agency dependencies, it regenerated AGENTS.md from the minimal .apm/ sources that existed at the time (one workflow.instructions.md + the agency dependency). The result was a ~40-line file that replaced everything.

There was:

• No warning that existing content would be lost
• No backup file created (e.g. AGENTS.md.bak)
• No diff or preview of what would change
• No merge strategy for user content outside .apm/

Reproduction

# 1. Start with an existing hand-written AGENTS.md
echo "# My project agent instructions\n\nImportant custom rules..." > AGENTS.md

# 2. Run apm install for the first time
apm install

# 3. AGENTS.md is now entirely replaced by generated content
# The original content is gone with no trace

Suggested fixes

1. Warn before overwriting — If AGENTS.md exists and is not APM-generated (e.g., missing the <!-- Generated by APM CLI header), print a warning and require --force or --confirm to proceed.

2. Create a backup — Before overwriting, save the existing file as AGENTS.md.bak or AGENTS.md.pre-apm.

3. Preview/diff mode — Add apm install --dry-run or --diff to show what would change without writing.

4. Preserve non-APM sections — Support a convention where content outside of APM-managed delimiters (e.g., <!-- APM:BEGIN --> / <!-- APM:END -->) is preserved.

Documentation request

Please add a prominent warning to the quickstart / getting-started documentation about this behavior. Something like:

⚠️ If you already have an AGENTS.md, run apm install after migrating its content into .apm/instructions/*.md files. Otherwise, apm install will overwrite your existing file. See [migration guide] for details.

Workaround

Migrate all hand-written content into .apm/instructions/*.md files before running apm install. But this is only discoverable after the damage is done.