Docs: disclose the MCP helper's anonymous usage ping

[r3dbars]

Why

transcripted-mcp sends one anonymous PostHog event per successful tool call (agent_capture_query_observed in AgentCaptureQueryTelemetry.swift). It's well-gated in code — allow-list scrubbing, honors the app analytics toggle, no-ops without an API key — but it was disclosed nowhere a user would look. For a product whose pitch is "read-only, nothing leaves your Mac," an undocumented outbound call per agent query is a trust problem even when the payload is clean.

Product Impact

• Affects: docs only
• Lane: agent workflow
• Why this matters: privacy-first is the product's core differentiator; disclosure has to be as visible as the feature.

What changed

• docs/agent-connect.md: new "Anonymous usage ping" subsection right under the tool list — plain-language description of what's sent (bucketed metadata only), what's never sent (transcript text, queries, titles, names, paths), and that the app's Settings → Privacy analytics switch turns it off.
• Tools/TranscriptedMCP/README.md: new "Telemetry" section with the technical detail — event name, payload buckets, the double gate (analytics toggle + API-key/HTTPS-host requirement), and that source builds send nothing by default.

All claims verified against AgentCaptureQueryTelemetry.swift (analyticsEnabled, observability-anonymous-analytics-enabled, POSTHOG_API_KEY/POSTHOG_HOST/TranscriptedPostHogAPIKey resolution, HTTPS-only host check, allow-list policy).

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, docs only
• Performance budget — n/a
• bash run-integration-smoke.sh — n/a
• swift test — n/a, no code changed
• Manual check: each gating claim traced to the exact code path before writing it down.

Risk Review

• Privacy / local-first behavior reviewed — this PR is the privacy disclosure itself
• Storage path or migration impact reviewed — none
• 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

Stacked on #1356 (base is that branch because both edit adjacent text in agent-connect.md) — merge #1356 first, then retarget this to main (GitHub does this automatically on base-branch merge). Part of the agent-surface audit series.

Agent handoff

COORD_DONE: GREEN | (this PR) | telemetry disclosure in 2 docs | retarget to main after #1356 merges | none | agent-preflight.sh | review + merge after #1356

🤖 Generated with Claude Code

https://claude.ai/code/session_01GuGZaFRmNrqfGPpqf7WH4n

---

Generated by Claude Code

[r3dbars]

Merge-room hold: not merging while draft and stacked on #1356. Live state checked 2026-07-02: head 63fcc71d5bebc6c8db2a57f8e5a8357d7123b128, base claude/agent-fix-1-docs-sync-pbwyng, mergeStateStatus=CLEAN, repo-hygiene/build-and-test green, hardware-smokes skipped. Diff is docs-only telemetry disclosure; smallest next action is merge/retarget #1356 first, then human review/mark ready and exact-head merge.