[DOCS] Voice dictation docs still describe the pre-v2.1.191 generic "not available" message when an organization disables voice, and do not document the new specific restriction message or the managed-policy control surface
Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/voice-dictation
Section/Topic
Requirements section, Troubleshooting section, and the implicit cross-reference from the admin-setup "Managed settings control surfaces" table.
Current Documentation
The Requirements section on https://code.claude.com/docs/en/voice-dictation currently says:
Voice dictation streams your recorded audio to Anthropic's servers for transcription. Audio is not processed locally. The speech-to-text service is only available when you authenticate with a Claude.ai account, and is not available when Claude Code is configured to use an Anthropic API key directly, Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. Voice dictation is also not available when your organization has HIPAA compliance enabled. Transcription does not consume Claude messages or tokens and does not count toward the limits shown in /usage. See data usage for how Anthropic handles your data.
The Troubleshooting section then lists nine failure-mode bullets (current entries include Voice mode requires a Claude.ai account, Microphone access is denied, No audio recording tool found on Linux, Voice mode could not find a working audio recorder in WSL, Voice input is failing repeatedly and has been paused, Nothing happens when holding Space in hold mode, Tapping Space types a space instead of recording in tap mode, No audio detected from microphone, No speech detected, and Transcription is garbled or in the wrong language). None of those bullets describe a "disabled by your organization" or "restricted by managed policy" outcome.
The admin-setup "Managed settings control surfaces" table (around the section that begins "Managed settings can lock down tools, sandbox execution, restrict MCP servers and plugin sources, and control which hooks run") enumerates permission lockdown, managed CLAUDE.md, MCP server control, customization lockdown, and hook restrictions, but does not list voice dictation as a control surface that an organization can disable.
What's Wrong or Missing?
Changelog v2.1.191 says:
Fixed /voice showing a generic not available message when disabled by an organization's policy — it now explains the restriction
After v2.1.191, /voice should produce a message that explains which restriction the organization has applied, instead of the generic "not available" string. The docs have not been updated to reflect that:
A. Requirements section still uses the old generic phrasing
Line 19 of voice-dictation.md still reads "Voice dictation is also not available when your organization has HIPAA compliance enabled." This is the exact "generic not available" wording that the changelog says was changed for the CLI surface. Even after the fix, the docs prose still does not state what users should expect to see or how to recover.
B. Troubleshooting section omits the new specific message
The Troubleshooting bullets on voice-dictation.md (lines 157-166 in the current mirror) include failure modes for Claude.ai auth, microphone permission, missing audio tools, WSL audio, repeated start-up failures, hold-mode key repeat, tap-mode empty-input behavior, mic silence, no speech detected, and wrong-language transcripts. There is no bullet for the case where /voice is blocked because the user's organization has voice disabled via managed policy. Users who hit this new specific message have no documentation entry to look up, and the page lists every other distinct failure mode by name.
C. admin-setup managed-policy control surfaces do not list voice
admin-setup.md enumerates the surfaces admins can lock down with managed settings (permissions, CLAUDE.md, MCP servers, customization, hooks, etc.), but does not list voice dictation. If an admin can now disable /voice for their organization, the admin-facing page does not document the available control or its precedence behavior. This is the gap that produces the new "disabled by organization policy" error in the first place.
Suggested Improvement
Option A (minimum, single page)
In voice-dictation.md, replace the "also not available when your organization has HIPAA compliance enabled" clause with wording that references the new specific message, and add a Troubleshooting bullet for it.
For the Requirements section, change:
Voice dictation is also not available when your organization has HIPAA compliance enabled.
to something like:
When your organization disables voice dictation via managed policy, /voice now prints a message that names the restriction instead of a generic "not available" string. Contact your Claude administrator if you are unsure why voice dictation is disabled.
For the Troubleshooting section, add a bullet alongside the existing nine:
*Voice mode is disabled by your organization: your administrator has turned voice dictation off via managed policy./voicenow explains which restriction applies. Contact your administrator if you believe this is incorrect.
Option B (comprehensive)
Apply Option A plus add a row to the admin-setup.md "Managed settings control surfaces" table:
| Voice dictation | Disable voice dictation for the organization | managed voice.enabled = false (or equivalent) |
and link the new troubleshooting bullet from the "See also" list at the bottom of voice-dictation.md to admin-setup.md.
Impact
Medium - Makes feature difficult to understand
Additional Context
Changelog v2.1.191 entry (the trigger for this report):
Fixed /voice showing a generic not available message when disabled by an organization's policy — it now explains the restriction
Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/voice-dictation | Requirements paragraph and Troubleshooting bullets still describe pre-v2.1.191 behavior |
| https://code.claude.com/docs/en/admin-setup | "Managed settings control surfaces" table does not list voice dictation as a control surface |
Total scope: 2 pages affected.
Version: v2.1.191 (the version that introduced the new specific restriction message in the /voice error output).