Voice input: project-aware vocabulary hints for speech-to-text #27752

Summary

Voice input is my primary way of communicating with T3 Code, but speech-to-text (STT) consistently mangles project-specific proper nouns. I propose that T3 Code maintain a list of vocabulary terms and pass them as recognition hints to each client's speech engine wherever the platform supports hinting.

Note on terminology: this concerns STT/dictation (speech → text), not TTS.

Real-world failures (my actual dictation)

General vocabulary survives fine. It is precisely the project and local vocabulary — the words I say most — that gets destroyed.

Why this belongs in T3 Code, not the STT engine

1. T3 Code knows the input source. It knows a composer draft came from dictation versus typing. Hints should apply only to transcription sessions — never to typed input, autocomplete, or the agent model.
2. T3 Code knows the project. Speech is highly context-bound. A generic engine has world knowledge; only T3 Code knows that in this repo "Bun" is a runtime. The same user in an anatomy project means bone, literally — hinting "Bun" there would be wrong. Per-project scoping prevents that cross-contamination.
3. The vocabulary is shareable. A committed terms file means every contributor's dictation gets the project's terms right from day one.

Platform opportunities

• iOS 26: the current implementation uses SpeechTranscriber, which does not accept vocabulary hints. DictationTranscriber does, via AnalysisContext.contextualStrings (and custom language models); the legacy SFSpeechRecognizer path offers SFSpeechRecognitionRequest.contextualStrings. This may require evaluating a module change for short-form composer dictation.
• macOS desktop: system dictation offers no app-supplied hints — should degrade gracefully as a no-op.
• Other clients/engines: each client maps the term list to its best native mechanism (e.g. Whisper-style prompt/keyterm biasing if a cloud or local engine is ever added), or no-ops where unsupported.

Hints are a bias, not a guarantee — capped (~100 phrases on Apple), and not a deterministic replacement. That is fine; even partial improvement removes most of the correction overhead.

Proposed design

The emphasis should be project-local and repo-committable, with an optional user-global list as a secondary source.

• Committed project terms: T3 Code already discovers .t3code/vcs.json from a project (walking up from nested workspaces). A sibling file such as .t3code/speech.json — or a plain one-term-per-line text file — would fit that existing pattern and let a repo share its dictation vocabulary with every contributor.
• Auto-generated candidates: an "Improve dictation terms" action could propose terms from the project name, dependency/package names, and the main tech stack. The user reviews and edits the list before it is saved/committed. Candidates must respect the platform hint cap (~100 on Apple), prioritizing explicitly added terms over generated ones.
• Optional global terms: a user-level list in Settings for terms that follow the person across projects (e.g. local place names). Merged with project terms, deduplicated, with project terms taking priority when the cap forces a choice.
• Scope: terms apply only to the active project's dictation sessions.
• Privacy: hints stay on-device and go only to the local transcription engine.

Alternatives considered

• External dictation apps with a custom dictionary: works, but the app-switching friction is why I use T3 Code's built-in mic.
• Post-hoc correction by the agent (glossary in agent memory): helps after the fact, per-agent, and the mangled text still lands in the composer.
• OS-level dictionaries: no project scope and no effect on T3 Code's transcription path.

Acceptance criteria

• A project can commit a terms file (e.g. under .t3code/) that T3 Code picks up automatically for that project's dictation.
• T3 Code can generate candidate terms from the project (name, dependencies, stack) for the user to review, capped to the platform hint limit.
• A user can optionally define global dictation terms in Settings.
• Dictation in a project is measurably biased toward its terms on at least one supporting client (iOS).
• Typed input, other projects, and unsupported platforms are completely unaffected.