Docs: sync agent-surface docs with actual behavior

[r3dbars]

Why

An audit of the agent-facing surface found four places where the docs describe behavior the code doesn't have (or omit behavior it does have). Agents and users reading these docs get wrong expectations: a tool list missing 3 of 12 tools, a README file example that doesn't match real output, a stale package file map that omits the telemetry module, and relocation wording that implies captures are migrated when they aren't.

Product Impact

• Affects: docs only
• Lane: agent workflow
• Why this matters: these four docs are the first things a user or agent reads when wiring Transcripted into Claude/Codex/Cursor; drift here turns directly into wrong agent behavior and support confusion.

What changed

• docs/agent-connect.md: capability list now shows all 12 MCP tools — list_action_items, list_decisions, digest were missing — with a note that the rollup tools only return rows for meetings with saved summaries (links docs/cross-meeting-tools.md).
• README.md: the meeting example now matches MeetingTranscriptStyler.renderBody output ( • separators, 32 min, 14 sec duration, no thousands separator, turns count, channel-qualified [System/Sarah] / [Mic/You] labels); the dictation example now matches DictationTranscriptWriter.dailySection (title in the ## heading, metadata lines), marked as trimmed.
• Tools/TranscriptedMCP/CLAUDE.md: file counts corrected (10 source + 10 test files, not 9/8), and the file index gains the previously missing AgentCaptureQueryTelemetry.swift, AgentCaptureQueryTelemetryTests.swift, and ToolHandlersTests.swift rows.
• docs/storage-paths.md: changing transcriptSaveLocation only affects where new captures are written; existing files are not migrated. The old wording said meetings and dictations "move under the selected folder", which TranscriptedStoragePreferences.setCaptureLibraryURL does not do.

How I checked it

• scripts/dev/agent-preflight.sh
• Selected checks from .agents/test-matrix.yml for the files changed (docs rule → preflight)
• bash build.sh --no-open — n/a, docs only
• bash run-tests.sh — n/a, docs only
• Performance budget — n/a, docs only
• bash run-integration-smoke.sh — n/a
• swift test — n/a (preflight suggests the MCP package test because its CLAUDE.md changed; no code changed, and this environment has no Swift toolchain — worth a run on a Mac if desired)
• Manual check: every claim verified against the writers/parsers (MeetingTranscriptStyler.swift, DictationTranscriptWriter.swift, AgentCaptureQueryTelemetry.swift, TranscriptedStoragePaths.swift) before editing.

Risk Review

• Privacy / local-first behavior reviewed — the new file-index row discloses the MCP telemetry module accurately (bucketed metadata only, analytics opt-out honored, no-op without an API key)
• Storage path or migration impact reviewed — wording only; no behavior change
• Public-facing copy stays concrete and matches current product scope
• Release/update impact reviewed — none
• 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

First of a series of one-fix-per-PR changes from an agent-surface UX audit. Follow-ups will cover telemetry disclosure in user docs, an MCP status tool + self-describing empty results, read-path pagination, CLI diagnostics, a capture-format spec with format_version, and relocation migration.

Agent handoff

COORD_DONE: GREEN | (this PR) | synced 4 docs with verified behavior | none | none | agent-preflight.sh | review + merge

🤖 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 3ab759ecb1c73ac5ca6d5e98d86f841d4e42a069, base main, mergeStateStatus=CLEAN, repo-hygiene/build-and-test green, hardware-smokes skipped. Diff is docs-only and appears low risk; smallest next action is human review/mark ready, then exact-head merge.