Add MCP source/onboarding read packet tool

[Foxfire1st]

Objective

Add a read-only MCP primitive that lets agents read known source files together with their deterministic file-level onboarding, so Intent-phase code inspection naturally carries the closest durable memory without a separate onboarding read.

Local planning artifact:
ar-coordination/tasks/agents-remember-md/260609_source-onboarding-read-packet/task.md

Requirements

• Add a repository-scoped MCP tool for paired source + onboarding reads, provisionally named read_source_packet.
• Accept repo-relative source paths only, resolved through MCP settings and the existing coordination context; do not accept arbitrary roots or absolute caller paths.
• Support batch reads with per-file source range/full-file options and per-file onboarding overrides.
• Treat omitted per-file onboarding as the normal/automatic path: attach the matching file-level onboarding body when a sidecar exists.
• The automatic onboarding body should include everything useful except metadata/header and update history.
• Use the per-file onboarding field only for deviations from the automatic view: requesting specific sections, suppressing onboarding, or including history.
• Avoid an abstract mode field unless implementation proves it is needed.
• Return explicit status for each onboarding lookup: found, missing, disabled, unsupported, or not_requested.
• Preserve route-index semantics: if a source path is inside a covered route but absent from coveredFiles, report missing onboarding rather than probing unrelated memory.
• Add an explicit start-of-work front-door read option/tool for root/route overview context rather than silently attaching broad overview prose to every file packet.
• Register the public MCP response model and keep token metadata on the final payload.
• Update tests, MCP docs, runtime skill guidance, and onboarding for the new read primitive.

Proposed default request shape

{
  "repo_id": "agents-remember-md",
  "files": [
    {
      "path": "mcp/src/agents_remember/mcp/tools/memory.py",
      "source": "full"
    },
    {
      "path": "mcp/src/agents_remember/mcp/server.py",
      "source": {"startLine": 1, "endLine": 180},
      "onboarding": false
    }
  ]
}

The first file is the intended default path: the caller names the source file and receives source plus the matching onboarding body automatically. The second file explicitly suppresses onboarding.

Section-specific override example:

{
  "path": "mcp/src/agents_remember/mcp/tools/memory.py",
  "source": "full",
  "onboarding": {
    "sections": ["logic", "invariants"]
  }
}

Acceptance criteria

• A public MCP tool can return source content plus deterministic file-level onboarding in one call.
• The normal call path does not require the model to specify onboarding options beyond the source path/range.
• onboarding: false suppresses onboarding for a file.
• Section-specific onboarding overrides work for stable file-level headings.
• Path containment prevents reads outside configured repositories/memory roots.
• Public response contract is covered by Pydantic model registry and conformance tests.
• Runtime guidance teaches agents to prefer this tool in the Intent phase when file paths are known.
• Full repo quality checks and memory-quality checks are run before closeout.

Open questions

• Final public tool name: read_source_packet, source_packet, or another shorter explicit name?
• Should overview/front-door reading be a separate tool, or an option on the new source packet tool?
• What max batch size and inline content budgets should v1 enforce?