CLI: empty-result diagnostics, documented count clamp, structured JSON reads

[r3dbars]

Why

transcripted-cli's context commands had three agent-hostile behaviors found in the agent-surface audit:

• context-recent, context-search, and list-dictations printed nothing and exited 0 when directory resolution landed somewhere empty or wrong — an agent can't tell "no data" from "wrong folder" and confidently reports "you have no meetings".
• --count silently clamps to 1–50 with no mention in help.
• --speaker silently drops all dictation results; and read-meeting/read-dictation --json threw away the structure ContextStore had already parsed, returning just a raw-markdown blob an agent has to re-parse.

Product Impact

• Affects: agent artifacts
• Lane: agent workflow
• Why this matters: silent emptiness is the main way agents give confidently wrong answers about a user's capture history.

What changed

• ContextCommands.swift: empty results now say so — text mode prints No results. Searched: <dirs> to stderr (stdout stays clean for piping); --json emits {"results": [], "searched_directories": [...], "hint": "..."}. context-search with --speaker on non-meeting kinds emits Note: --speaker only matches meetings; dictations skipped. (stderr in text, notes array in JSON). All three --count helps document the 1–50 clamp. Searched-directory reporting is --kind-aware and deduped.
• ContextModels.swift: CLIReadMarkdownDocument gains optional recording/speakers/utterances (meetings) and date/entries (dictations) alongside the unchanged markdown field; new CLIContextResultsDocument wrapper for the empty/notes cases.
• ContextStore.swift: extracted meetingTranscript(fromMarkdown:) and readDictationDocument(...) so reads can return parsed structure; --entry-id narrows entries to the one entry.
• ContextStoreTests.swift: 11 new command-level tests (empty text/JSON shapes, kind-scoped searched dirs, speaker note on both streams, bare-array compatibility preserved for non-empty output, structured read JSON incl. entry narrowing) with an fd-level stderr capture helper mirroring the existing stdout one.
• Tools/TranscriptedCLI/CLAUDE.md: new Output Shapes section + stderr-diagnostics gotcha.

Backward compatibility: non-empty list/search output is still a bare JSON array (unless a note applies), and markdown is unchanged in reads.

How I checked it

• scripts/dev/agent-preflight.sh
• Selected checks from .agents/test-matrix.yml — matrix rule for Tools/TranscriptedCLI/** is swift test --package-path Tools/TranscriptedCLI
• swift test --package-path Tools/TranscriptedCLI — run by Swift CI on macOS at this exact head (f6e6c65), green: https://github.com/r3dbars/transcripted/actions/runs/28621353693 (the Tools package tests step runs all four package suites)
• bash build.sh --no-open / bash run-tests.sh / smokes — also executed green in the same Swift CI run (required merge gate)
• Manual check: all referenced model types and store functions verified present; diff reviewed hunk-by-hunk.

Authoring context: written in a Linux session with no local Swift toolchain; verification is the green macOS Swift CI run above, which enforces the same matrix as local runs.

Risk Review

• Privacy / local-first behavior reviewed — diagnostics print local paths to the local terminal only; nothing leaves the machine
• Storage path or migration impact reviewed — read-only; resolution behavior unchanged
• Public-facing copy stays concrete and matches current product scope
• Release/update impact reviewed — CLI is not distributed in releases
• 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, #1358). Deliberately does not touch TranscriptedCaptureKit — #1362 owns resolver changes.

Agent handoff

COORD_DONE: GREEN | (this PR) | CLI diagnostics + structured JSON reads | none | none | Swift CI green at head f6e6c65 (full matrix incl. CLI package tests) | human review + mark ready + merge

🤖 Generated with Claude Code

https://claude.ai/code/session_01GuGZaFRmNrqfGPpqf7WH4n

[r3dbars]

Merge-room hold: draft plus required Mac Swift proof is missing. Live state checked 2026-07-02: head f6e6c6592fdfd90d0f700494564785dc2bad15ea, base main, mergeStateStatus=CLEAN, repo-hygiene/build-and-test green, hardware-smokes skipped. This touches CLI code/tests; PR body says swift test --package-path Tools/TranscriptedCLI was not run. Smallest next action: run that package test on a Mac, update proof, mark ready, then exact-head review/merge.