Skip to content

Refresh docs to match what shipped - #21

Open
bradburch wants to merge 1 commit into
mainfrom
docs-refresh-post-merge
Open

Refresh docs to match what shipped#21
bradburch wants to merge 1 commit into
mainfrom
docs-refresh-post-merge

Conversation

@bradburch

Copy link
Copy Markdown
Owner

Brings CLAUDE.md, README.md, and docs/local-llm.md in line with #18, #19, and #20.

Wrong, not just stale

Three CLAUDE.md claims would have actively misled a future session:

Claim Reality
"CoachingLLM has two implementations" Three — and only the Anthropic one can enforce a JSON schema; the other two share one prose contract (formatAppendix states the rules, decodeCoaching enforces them)
System audio via ScreenCaptureKit A CoreAudio process tap. SCK is precisely what recorded an entire Continuity call as digital silence
Deployment floor 14.0 14.2 since CoreAudio taps, in Package.swift and LSMinimumSystemVersion

The capture section now also records the two tap invariants that are easy to undo by accident: the aggregate device deliberately has no output sub-device, and padSilenceToNow exists because a tap delivers nothing while output is idle — remove it and every "them" segment after a gap lands early in the merge.

What actually cost time this session

  • The documented AppleScript for opening the main window silently no-ops without a preceding activate — it reports success and leaves the window count at 0. The snippet in CLAUDE.md was incomplete.
  • entire contents doesn't just return empty on the Settings pane, it errors (-1700). Counting the Form's section groups works as a structural probe. screencapture is not a fallback — the shell lacks Screen Recording.
  • Comparing mic vs sys RMS across the recordings directory is the fastest capture diagnostic, and it separates "capture is broken" from "this call type is excluded" in one pass. audioop was removed in Python 3.13, so the obvious one-liner doesn't work.
  • Never run make-app.sh while a recording is live — it overwrites the running executable.
  • A Finder-launched .app inherits a minimal PATH, so spawning a helper binary needs absolute-path search; /usr/bin/env resolves in a shell and fails in the bundle.

Added a third entry to "green tests prove less here than usual": capture that runs, writes correctly-sized files, and records silence. Every mocked recorder test passed while SCK wrote zeros.

One new rule, the converse of an existing one

CLAUDE.md already says don't split what shares a contract. This adds don't narrow what already serves two callers — that bug shipped twice this session: a shared query filtered for one of its two callers (dropping mock interviews from export), and a second reader added to one file descriptor (racing the streaming drain).

User-facing

README and docs/local-llm.md describe all three providers. The subscription path's tradeoffs — ~15–20k overhead tokens per debrief, rate limits, unsupported integration — are stated in local-llm.md, since that's the page someone lands on when they're trying to avoid API cost and comparing options.

201/201 unit tests pass (docs-only change; run as a sanity check).

🤖 Generated with Claude Code

…LM clients

Several CLAUDE.md claims were not merely stale but wrong, which is worse than
missing — a future session would have acted on them:

- "CoachingLLM has two implementations" (three now, and only the Anthropic one
  can enforce a JSON schema; the other two share one prose contract)
- system audio described as ScreenCaptureKit, which is exactly the thing that
  recorded an entire Continuity call as silence
- deployment floor still 14.0 (14.2 since CoreAudio taps)

Also records what actually cost time this session:

- the documented AppleScript for opening the main window silently no-ops
  without a preceding `activate` — it reports success and leaves 0 windows
- `entire contents` doesn't just return empty on the Settings pane, it errors;
  counting the Form's section groups works, and `screencapture` is not a
  fallback because the shell lacks Screen Recording
- comparing mic vs sys RMS across the recordings directory is the fastest
  capture diagnostic, and `audioop` is gone in Python 3.13
- never run make-app.sh while a recording is live; it overwrites the running
  executable
- a Finder-launched .app has a minimal PATH, so spawning a helper binary needs
  absolute-path search rather than /usr/bin/env

Adds the converse of the existing "don't split what shares a contract" rule:
don't narrow something that already serves two callers. That bug shipped twice
this session — a shared query filtered for one caller, and a second reader on
one file descriptor.

README and docs/local-llm.md now describe all three coaching providers, with
the subscription path's tradeoffs stated where someone comparing costs will
actually see them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant