FE-1834: Teach Brunch voice agent custom words

[kostandinang]

🌟 What is the purpose of this PR?

Let people teach Brunch names and terms through a default-off Custom words Labs setting. Saved spellings and optional pronunciation hints help the assistant recognize and say those words in Voice conversations.

🔗 Related links

• Stacked on FE-1833: Speak progress while Brunch works #9889.

🚫 Blocked by

• Merge FE-1833: Speak progress while Brunch works #9889 and sync its latest changes before merging this PR.

🔍 What does this change?

• Add a Voice-only Words header button with a book icon and a Custom words dialog for adding, editing, and removing up to 50 entries.
• Store words in this browser, scoped to the principal and conversation; clear them with the conversation. Preserve unsaved edits when another tab deletes the edited word.
• Send spellings to the assistant and both existing voice transcription prompts, and pronunciation hints to the speaking model. Keep the current transcription models and semantic VAD.
• Keep active Voice sessions on their starting hints until restarted, including retries, and retain the echo guard.
• Keep the word list, pronunciation and limits in the website's Voice code, and the spelling bounds Brunch receives in the transport. Brunch core, Petrinaut Core and the stock assistant prompt are unchanged.
• Add a website user guide at apps/petrinaut-website/docs/custom-words.md and a patch changeset for Petrinaut's assistant header controls.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

• Modifies an npm-publishable library and changeset files are included.

📜 Does this require a change to the docs?

• Requires changes to docs which are made as part of this PR.

🕸️ Does this require a change to the Turbo Graph?

• Does not affect the execution graph.

⚠️ Known issues

• One Live Voice turn was verified with captured microphone and speaker audio; legacy Realtime and physical speaker echo were not tested.
• The 50-entry limit is also subject to spelling, pronunciation, aggregate-text, and encoded-header size limits.
• Local frontend checks cannot validate Brunch history without the backend.

🐾 Next steps

Sync the parent branch before marking ready.

🛡 What tests cover this?

• Tests cover validation, browser persistence, cross-tab edits, transport, prompt wiring, session snapshots, and echo filtering.
• Latest targeted run: transport, Brunch core, Petrinaut Core, the Petrinaut assistant panel, apps/brunch-agent and the website's Voice and Brunch demo tests pass.
• Formatting and Markdown lint passed for the latest UI and documentation edits.
• Browser checks covered the Labs label, dialog copy, accessible Words button, and Voice-only visibility.

❓ How to test this?

1. Select Use Brunch and enable Custom words in User settings → Labs.
2. Enter Voice mode, open Words, and add a name with an optional pronunciation.
3. Edit and remove entries; reload to check persistence. Verify the button is hidden in text mode.
4. Start Voice and test the name. Change its hint during the session, then restart Voice to apply it.
5. Clear the conversation and confirm its word list is cleared.

📹 Demo

custom-words-live-demo.mp4

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Oct 2, 2026 10:07pm UTC
petrinaut	Ready	Preview	Oct 2, 2026 10:07pm UTC
petrinaut-docs	Ready	Preview	Oct 2, 2026 10:07pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Oct 2, 2026 10:07pm UTC

[cursor]

PR Summary

Medium Risk
Touches user-message framing, model instructions, and third-party voice APIs; mistakes could leak host metadata into prompts or admit malformed hints, though validation and projection stripping mitigate injection and history pollution.

Overview
Adds an optional, default-off Custom words Labs setting and a Voice-only Words header control (via new headerActions / actionsInputMode on the Petrinaut assistant panel) so users can maintain per-conversation spellings and pronunciation notes in browser storage.

Spellings ride along on Brunch submissions through a v2 contextual user message envelope (words snapshot captured at send time for retries), while Brunch turns them into a cautious system instruction (useWords) and strips the envelope from model context and human-facing transcripts. Voice pins one word list per session: encoded x-petrinaut-voice-words on Live/Realtime/transcription requests, spellings in transcription prompts, pronunciation hints only on speaking instructions, plus shadow prompt-regurgitation filtering tied to the pinned prompt.

Includes validation limits, server-side header decoding with fail-closed 400s, user docs, and broad unit/integration coverage.

^{Reviewed by Cursor Bugbot for commit dc79ebc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9c8d16b. Configure here.}