[FEATURE] Feature request: managed AGENTS.md section updates

[yogurtearl]

Feature request: managed AGENTS.md section updates

At a glance

• Problem: many repos already have hand-written AGENTS.md content they do not want overwritten.
• Why it matters: full-file generation makes incremental adoption harder.
• Example syntax:

agents_md:
  mode: managed_section
  start_marker: "<!-- apm:start -->"
  end_marker: "<!-- apm:end -->"

Is your feature request related to a problem? Please describe.

Yes. Many repos already use AGENTS.md as shared, human-maintained documentation. APM can generate root context, but it does not offer a mode where it updates only the part it owns and leaves the rest of the file alone.

That creates a practical adoption problem:

• teams already have curated top-level guidance
• they want to add APM-managed context
• but they do not want to convert the whole file into a generated artifact

Describe the solution you'd like

Add an opt-in managed section mode for AGENTS.md.

Example syntax:

agents_md:
  mode: managed_section
  start_marker: "<!-- apm:start -->"
  end_marker: "<!-- apm:end -->"
  include:
    - installed_packages
    - pinned_refs
    - regeneration_hint

That could produce a file like:

# Repo guidance

Human-authored content stays here.

<!-- apm:start -->
Generated package summary, pinned refs, and APM-managed instructions.
<!-- apm:end -->

The important behavior is:

• only the managed block is updated
• existing human-written content stays untouched
• the generated block can show useful install metadata

Describe alternatives you've considered

• Treat AGENTS.md as fully generated
• Move human-authored guidance into a different file
• Keep AGENTS.md manual and avoid top-level APM output there

Those options all make rollout more disruptive than it needs to be.

Additional context
This would make APM much easier to introduce into mature repos where AGENTS.md already exists and already matters to humans.