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
petrinaut	Ready	Preview	Oct 9, 2026 11:04am UTC
petrinaut-docs	Ready	Preview	Oct 9, 2026 11:04am UTC

2 Skipped Deployments

Project	Deployment	Actions	Updated
hash	Ignored	Preview	Oct 9, 2026 11:04am UTC
hashdotdesign-tokens	Ignored	Preview	Oct 9, 2026 11:04am UTC

[cursor]

PR Summary

Medium Risk
Changes how untrusted user vocabulary reaches model instructions, Flue messages, and OpenAI voice endpoints; mitigated by strict validation and stripping envelopes from canonical history, but still expands the prompt-injection surface.

Overview
Adds Custom words for Brunch on the Petrinaut website: a default-off Labs toggle and a Voice-only Words header control (via new optional headerActions / actionsInputMode on the assistant panel) to manage spellings and optional pronunciation notes per browser conversation.

The website persists and validates the list locally, attaches spellings to Brunch chat through a new v2 contextual user-message envelope and transport words snapshot (captured per message for retries), and passes encoded vocabulary to Live/Realtime/transcription voice APIs. Brunch strips that envelope from model history/UI transcripts while useWords turns admitted spellings into a bounded system instruction; pronunciation stays on the speaking side only.

Voice sessions pin hints at connect (including retries) until the session ends or Live restarts after panel close; transcription prompts and echo filtering now use the pinned prompt, including a shadow prompt-regurgitation skip so taught vocabulary is not submitted as user speech.

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

[cursor]

Stale Bugbot comment from a previous run.