Paper cuts batch 2: Esc, setup, agent connect, and wording fixes

[r3dbars]

Requested by Justin · project thread

Before: a stray Esc during a long hands-free dictation silently threw the whole take away. Setup didn't say what Accessibility was for, the Done screen promised shortcuts that couldn't work yet, the agent page dropped the "restart it" step once a row connected, and a lot of small copy was vague (a shortcut labeled "Off", and shaking red errors for things that weren't errors).

After: dictations longer than 5 seconds ask "Press Esc again to discard" before Esc throws them away, and a cancel gets its own soft sound. Setup explains what each permission unlocks and what still works without it, and the agent page keeps telling you to restart the agent. The small wording fixes from the paper-cuts audit are all in too.

Why

This is batch 2 of the paper-cuts audit (/mnt/project-files/paper-cuts/audit.md): items 5, 6, 7, 11-17, 19-21, 26 and 28-30, plus the "Small stuff" wording list.

Product Impact

• Affects: dictation / meetings
• Lane: activation / dictation reliability
• Why this matters: new users stumble in setup, and an accidental Esc can lose minutes of dictation with no warning.

What changed

Esc (item 5)

• Takes of 5 seconds or less still cancel on the first Esc. Longer takes show "Press Esc again to discard" for 3 seconds, and VoiceOver announces it. Held-key repeats are ignored. The prompt works in the mini cursor mode too.
• A new soft two-note cancel sound (Resources/Sounds/dictation-cancelled.wav). It's also used for "No speech heard", so neither sounds like the done chime.
• Copy: the stop button reads "Stop and paste. Esc cancels."
• Note: meeting Discard now plays the cancel sound as well, on purpose.

Setup and permissions (items 6, 12, 16, 17, 19)

• The Accessibility row is renamed "Keyboard shortcuts and paste-back" and says what still works without it.
• The Done screen only promises shortcuts once Accessibility is on, and states the open-at-login default.
• The Welcome screen mentions anonymous stats and crash reports.
• When the mic or calendar is blocked, the row says macOS won't ask again and the button reads "Open Settings".
• The first Accessibility grant during onboarding only shows the macOS prompt; it doesn't also open System Settings on top. The Settings rows still always open the pane.

Agent connect (item 7): connected rows stay visible and say "Restart X to finish connecting".

Update row (item 11): the row now says why it's waiting ("After this recording finishes", "After transcribing finishes", "Finish naming speakers first").

Overlay messages (items 13, 26): notices stay up longer for long text, hold while you hover (capped at 30 s), and only real errors shake. The 5-minute cap save is a calm "Saved" notice.

No speech (items 14, 15): push-to-talk users are told to hold the key while talking. Everyone else is told to check their mic.

Menu bar (items 20, 21): while dictating, the row reads "Stop Dictation". The voice-model subtitle uses plainer copy ("Voice setup failed. Try again", "Downloaded. Loads when you start").

Settings (items 28-30): "Better matching on calls" says it needs a restart, and re-transcribe explains why it's disabled. "Clear all" corrections now asks first.

Small stuff wording: auto-send failures, Paste Last (shows its shortcut, clearer failure text), the model card, System Audio row, storage cleanup, meeting audio wording, diagnostics result, speaker merge (no longer promises an undo it can't do), and the meeting-finishing message.

Skipped here: item 9 (waits for #1801), item 31 and the Option-M prompts (other threads own them), speaker sheet keys and title (overlaps #1795), recovery copy (next to #1801's hunk), and the bigger behavior items (Move for the library folder, duplicate shortcuts, multi-file import, mic-denial skip, email-support diagnostics ID). The Esc undo window after a discard is a follow-up.

How I checked it

• scripts/dev/agent-preflight.sh
• check-build-source-lists.py, check-analytics-emitters.py, check-duplicate-declarations.py pass locally
• bash build.sh --no-open (CI, no Swift toolchain in this session)
• bash run-tests.sh (CI; tests updated for every changed copy/policy)
• Manual check: Esc confirm in both overlay modes, cancel sound volume by ear, onboarding Accessibility first ask

Risk Review

• Privacy / local-first behavior reviewed (no new off-device data)
• Storage path or migration impact reviewed (none; one new UserDefaults flag for the first Accessibility prompt)
• Public-facing copy stays concrete and matches current product scope
• Release/update impact reviewed (goes in 1.1.63)
• No private transcripts, audio, tokens, personal paths, or customer data are included

Notes

Deep review: /mnt/project-files/reviews/next-release/1804.md. S1-S4 and M2-M4, M11, M13, M14 are fixed. M1 is kept on purpose (meeting Discard sound), and M5-M7, M9, M10, M12 are left as-is or as follow-ups.

Agent handoff

COORD_DONE: BRIEF | https://github.com/r3dbars/transcripted/pull/1804 | paper-cuts batch 2 | none | none | preflight + local python checks; CI pending | merge when CI green and re-review clean

🤖 Generated with Claude Code

https://claude.ai/code/session_01XWq97CXXURmxjYLNWtVxXC