Docs: agent-surface consolidation plan (one binary, one index, one format)

[r3dbars]

Why

The agent-surface audit found five overlapping ways to query captures (folder reads, CLI, MCP, sidecar file protocol, loopback preview), three parsers of the same Markdown, two derived indexes, and a four-tier directory resolution order still carrying legacy Draft identity. Consolidating that is too invasive for one unverified change, so this PR lands the plan as a reviewable design doc first.

Product Impact

• Affects: docs only
• Lane: agent workflow
• Why this matters: gives the consolidation work an agreed target and a sequence of small, independently shippable steps instead of a big-bang refactor.

What changed

• New docs/agent-surface-consolidation-plan.md: problem statement grounded in current code (startup index rebuilds, hand-mirrored parsers, resolution drift), target architecture (single transcripted helper binary; app-maintained index read by tools; resolution logic only in CaptureKit with the legacy Draft domain on a deprecation clock; one file format once format_version + style-at-save land; live sidecar exposed through the helper instead of prose-driven file polling), seven migration steps, risks, and per-step verification.

How I checked it

• scripts/dev/agent-preflight.sh
• Selected checks from .agents/test-matrix.yml (docs rule → preflight)
• bash build.sh --no-open — n/a, docs only
• bash run-tests.sh — n/a
• Performance budget — n/a
• bash run-integration-smoke.sh — n/a
• swift test — n/a
• Manual check: every claim about current behavior cross-checked against Tools/TranscriptedMCP (startup reconcile, FileWatcher), Tools/TranscriptedCaptureKit/CaptureLibraryResolver.swift, and the app writers.

Risk Review

• Privacy / local-first behavior reviewed — plan keeps everything local; no new off-device surface
• Storage path or migration impact reviewed — the doc is explicitly about sequencing that migration safely
• Public-facing copy stays concrete and matches current product scope
• Release/update impact reviewed — none yet; step 3+ will need release-flow updates and the doc says so
• Agent PRs link the issue/workpad and stay draft until human review
• UI changes include sanitized .agent-review/visuals/ evidence — n/a
• No private transcripts, audio, tokens, personal paths, or customer data are included

Notes

Part of the agent-surface audit series (#1356, #1357, plus in-flight PRs for the MCP status tool, CLI diagnostics, format spec, and relocation fix). This one is the long-range map; the in-flight PRs are steps 1–2 of it.

Agent handoff

COORD_DONE: GREEN | (this PR) | consolidation design doc added | none | agree/adjust target architecture before step 3+ | agent-preflight.sh | review the plan

🤖 Generated with Claude Code

https://claude.ai/code/session_01GuGZaFRmNrqfGPpqf7WH4n

---

Generated by Claude Code

[r3dbars]

Merge-room hold: not merging while this PR is still draft. Live state checked 2026-07-02: head 14ab3ff2abf18c63a9d2e0058ae72ced8bbe18c7, base main, mergeStateStatus=CLEAN, repo-hygiene/build-and-test green, hardware-smokes skipped. Diff is a docs-only consolidation plan; smallest next action is human agreement on the plan/mark ready, then exact-head merge if still clean.