nexus/docs/plans/2026-04-11-nexus-phase-14-voice-cmdk-globalization.md

Nexus Phase 14 — Voice + ⌘K Globalization

Use superpowers:test-driven-development. Commit atomically.

Goal: Lift the voice capture state out of ChatInput's internal VoiceMicButton into a shared context so the top-strip GlobalMicButton becomes functional from any route, with all speech queued to the Assistant inbox per spec §5.5. Replace the CmdKButton shim (which dispatches synthetic Meta+K keydowns) with a real CommandPaletteContext that exposes an imperative open method, and expand the command palette's search index to cover conversations, projects, issues, agents, recipes, settings, and workshops per spec §10.1.

Source of truth: spec §4.2 (GlobalMicButton states), §5.5 (voice routing from non-Assistant modes), §10.1 (⌘K palette), §10.3 (voice as global affordance), §10.4 (single notification surface).

Branch: nexus/design-system-migration.

---

Ownership boundaries

You may create or modify ONLY:

Path	Action
ui/src/context/VoiceContext.tsx	Create — new context
ui/src/context/VoiceContext.test.tsx	Create
ui/src/context/CommandPaletteContext.tsx	Create — new context
ui/src/context/CommandPaletteContext.test.tsx	Create
ui/src/components/frame/GlobalMicButton.tsx	Modify — wire to VoiceContext
ui/src/components/frame/GlobalMicButton.test.tsx	Modify — add functional tests
ui/src/components/frame/CmdKButton.tsx	Modify — wire to CommandPaletteContext, remove synthetic keydown
ui/src/components/frame/CmdKButton.test.tsx	Modify
ui/src/components/CommandPalette.tsx	Modify — consume CommandPaletteContext, extend search index
ui/src/components/ChatInput.tsx	Modify — lift voice state to VoiceContext
ui/src/pages/PersonalAssistant.tsx	Modify — read voice queue from VoiceContext when navigating to assistant
ui/src/main.tsx or equivalent	Modify — mount the new providers in the provider stack
ui/src/hooks/useKeyboardShortcuts.ts	Modify — fix the pre-existing destructure bug (onSearch missing from destructure) AND wire onSearch to CommandPaletteContext

You MUST NOT touch:

• Any other Phase 8–13 owned files
• ui/src/App.tsx routes
• Backend voice pipeline or STT/TTS endpoints (v1.6 already ships them — consume as-is)
• @/lib/router

---

Scope

1. VoiceContext

Responsibilities:

• Ownership of the current MediaStream | null for the microphone
• Recording state: idle / listening / speaking (matching the GlobalMicButton states)
• Transcription buffer (latest transcript from Whisper STT)
• Queue: when voice is captured from a non-Assistant route, append to a pending queue; when the user navigates to /assistant, drain the queue into a new user message
• Emits a hasQueuedVoice boolean that other components (e.g., the Assistant icon volt dot) can read

Consumers:

• GlobalMicButton — renders idle/listening/speaking per context state; tap cycles through record → stop → queue
• ChatInput inside PersonalAssistant — subscribes to the VoiceContext stream instead of owning its own
• PersonalAssistant — on mount, drains VoiceContext.queue

What lifts out of ChatInput: Currently VoiceMicButton inside ChatInput owns:

• navigator.mediaDevices.getUserMedia call
• MediaStream state
• MediaRecorder and audio chunk buffer
• Whisper transcription invocation
• Silence-detection / auto-send behavior

All of this moves to VoiceContext. ChatInput's internal mic button becomes a thin consumer that reads VoiceContext.state and calls VoiceContext.startListening() / stopListening().

2. CommandPaletteContext

Responsibilities:

• open: boolean, setOpen(next: boolean), toggle()
• Keyboard listener for Cmd+K / Ctrl+K registered once at the provider level (replaces the existing one inside CommandPalette.tsx's useEffect)

Consumers:

• CmdKButton — calls setOpen(true) on click. No more synthetic keydown dispatch.
• CommandPalette — reads open from context, setOpen(false) to close
• useKeyboardShortcuts.onSearch — calls setOpen(true) instead of synthetic keydown

Extending the search index (spec §10.1):

• Conversations (by title, by recent message text snippet)
• Projects (by name)
• Issues (by title, by project)
• Agents (by name, by role)
• Recipes (by name, by tag — stubbed if recipe API doesn't exist yet; that's a v1.8 feature)
• Settings (by section name — map the 8 Phase 13 section titles to /instance/settings/general#<section> anchors)
• Studio workshops (by name — map the 9 WorkshopSlugs to /content-studio/<slug>)
• Commands: New project, New conversation, Re-run onboarding, etc.

Grouped with uppercase 1.4px-tracked category headers. Selected result has a 2px volt left border + pale-yellow text. Keyboard nav: arrow keys + enter + escape.

3. Fix useKeyboardShortcuts.ts:12-17 destructure bug

Phase 6/11 reviews flagged that onSearch is referenced at line 25 but never destructured at lines 12–17. Fix: add onSearch to the destructure. Once fixed, wire it to commandPalette.setOpen(true) through a context consumer (the shortcut hook itself may not consume contexts directly — escalate and resolve).

4. IconRail dot wiring — keep Phase 11's integration

The volt dot on the Assistant icon (from Phase 11's useGateIndicator) already exists and works. Phase 14 optionally extends it to also light up when there's queued voice (VoiceContext.hasQueuedVoice). If you add this, make the aria-label more precise: "Assistant (pending gates and queued voice)" or split into two overlays.

---

Implementation notes

Provider stack order

<QueryClientProvider>
  <ThemeProvider>
    <DialogProvider>
      <CompanyProvider>
        <VoiceProvider>              <-- NEW (Phase 14)
          <CommandPaletteProvider>   <-- NEW (Phase 14)
            <Router>
              <App />

VoiceContext must be above CompanyContext because voice state is user-level, not company-level. CommandPaletteContext is above Router because the shortcut handler is global.

CmdKButton shim removal

Before:

const handleClick = () => {
  const event = new KeyboardEvent("keydown", { key: "k", metaKey: true, bubbles: true });
  document.dispatchEvent(event);
};

After:

const { setOpen } = useCommandPalette();
const handleClick = () => setOpen(true);

Delete the shim comment block at the top of the file; replace with a note that Phase 14 landed the real wiring.

GlobalMicButton real wiring

Before (Phase 8 scaffold):

export function GlobalMicButton({ state = "idle", onClick }: GlobalMicButtonProps) {

After:

export function GlobalMicButton() {
  const { state, toggleListening } = useVoice();
  // render idle/listening/speaking based on state
}

Remove the state prop and onClick prop — they were Phase 8 scaffolding for when no real voice pipeline was available. Tests need updating.

---

Acceptance criteria

1. Tapping the GlobalMicButton from ANY route starts listening and transitions through states
2. Speech captured on non-Assistant routes queues to VoiceContext.queue and surfaces as queued-voice indicator
3. Navigating to /assistant drains the queue into a new user message that streams through the existing chat pipeline
4. Cmd+K / Ctrl+K from anywhere opens the command palette via context, not synthetic keydown
5. Clicking the CmdKButton opens the palette via context
6. The palette searches across conversations, projects, issues, agents, settings sections, and workshops (recipes stubbed if no API)
7. useKeyboardShortcuts.onSearch is wired correctly (destructure bug fixed)
8. ChatInput's internal voice button consumes VoiceContext instead of owning its own state
9. All new tests pass; all existing frame tests still pass
10. Typecheck clean on Phase 14 files

---

Report format

• Status
• Commit SHAs
• Files created / modified
• Tests added / passing
• Voice pipeline integration notes — where did the getUserMedia and MediaRecorder calls end up? What backend endpoints are consumed?
• Command palette search extensions — which sources are live and which are stubbed?
• IconRail dot extension — did you extend it for queued voice, or only gates?
• Concerns, deviations, self-review