pi-voicekit 0.1.3 → 0.2.0

package/README.md

@@ -6,32 +6,30 @@
 > Not affiliated with the original author. Old name: `pi-listen`.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/banner.png" alt="pi-listen — Voice input for the Pi coding agent" width="100%" />
+  <img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/brand/banner-en.png" alt="pi-voicekit — Voice input and output for the Pi coding agent" width="100%" />
 </p>
 
-**Hold-to-talk voice input for [Pi](https://github.com/earendil-works/pi-coding-agent).** Cloud streaming via Deepgram or fully offline with local models.
+**Voice in and voice out for [Pi](https://github.com/earendil-works/pi-coding-agent).**
+Hold-to-talk STT — Deepgram streaming (cloud) or 21 offline models — plus TTS that
+speaks the agent's replies (Kitten, Kokoro, Piper, or Deepgram Aura).
 
 [![npm version](https://img.shields.io/npm/v/pi-voicekit.svg)](https://www.npmjs.com/package/pi-voicekit)
 [![license](https://img.shields.io/npm/l/pi-voicekit.svg)](https://github.com/CyFeng16/pi-voicekit/blob/main/LICENSE)
 [![original author](https://img.shields.io/badge/original_author-@baanditeagle-1DA1F2?logo=x&logoColor=white)](https://x.com/baanditeagle)
 
-> **v7.0.0 — World-class TTS UX** — pick models from `/voice-settings` Speak
-> tab (no more JSON editing), auto-download on selection with progress, voice
-> picker for every backend, first-run onboarding with smart-default
-> recommendation by your system locale, and `ttsAutoSpeak: true` finally
-> works — auto-speaks the agent's responses with code-block stripping and
-> rate limiting. Diagnostic command `/voice-speak-info` shows everything.
-> Resume-on-interrupt downloads. Plus all v6 features (14 local models from
-> 25 MB Kitten Nano up, Deepgram Aura cloud, region-strict language matching,
-> sentence-aware chunking). [Full changelog →](CHANGELOG.md)
+> **v0.1.3 — current release** — audio capture prefers `ffmpeg` when
+> `PULSE_SERVER` is set (SSH audio tunnel / remote PulseAudio), so remote
+> microphones record reliably. Voice in **and** voice out: 21 offline STT models,
+> 20 local TTS voices plus Deepgram Aura, driven by one `/voice-settings` panel
+> with 6 tabs. The 0.1.x line is documented in the [changelog](CHANGELOG.md).
 
 ---
 
 ## See How It Works
 
 <p align="center">
-  <a href="https://github.com/CyFeng16/pi-voicekit/blob/main/assets/pi-listen.mp4">
-    <img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/banner.png" alt="Watch demo video" width="600" />
+  <a href="https://github.com/CyFeng16/pi-voicekit/blob/main/assets/demo/pi-voicekit-demo.mp4">
+    <img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/brand/banner-en.png" alt="Watch demo video" width="600" />
   </a>
   <br>
   <em>Click to watch the demo video</em>
@@ -50,16 +48,16 @@ pi install npm:pi-voicekit
 
 ### 2. Choose your backend
 
-pi-listen supports two transcription backends:
+pi-voicekit supports two transcription backends:
 
-|                  | Deepgram (cloud)                                         | Local models (offline)                              |
+|                  | Deepgram (cloud)                                         | Local models (offline recognition)                  |
 | ---------------- | -------------------------------------------------------- | --------------------------------------------------- |
 | **How it works** | Live streaming — text appears as you speak               | Batch mode — transcribes after you finish recording |
 | **Setup**        | API key required                                         | No API key, models auto-download on first use       |
-| **Internet**     | Required                                                 | Not required after model download                   |
+| **Internet**     | Required                                                 | Not required after model download for recognition; the polish step may use the network |
 | **Latency**      | Real-time interim results                                | 2–10 seconds after recording stops                  |
 | **Languages**    | 56+ with live streaming                                  | Depends on model (1–57 languages)                   |
-| **Cost**         | $200 free credit (lasts 6–12 months for most developers) | Free forever                                        |
+| **Cost**         | $200 free credit (lasts 6–12 months for most developers) | Recognition is free; the polish step may cost money |
 
 Run `/voice-settings` inside Pi to choose your backend and configure everything from one panel.
 
@@ -71,7 +69,7 @@ Sign up at [dpgr.am/pi-voice](https://dpgr.am/pi-voice) — $200 free credit, no
 export DEEPGRAM_API_KEY="your-key-here"    # add to ~/.zshrc or ~/.bashrc
 ```
 
-#### Option B: Local models (fully offline)
+#### Option B: Local models (offline recognition)
 
 No setup needed — run `/voice-settings`, switch backend to Local, and select a model. It downloads automatically.
 
@@ -79,7 +77,7 @@ No setup needed — run `/voice-settings`, switch backend to Local, and select a
 
 ### 3. Open Pi
 
-On first launch, pi-listen checks your setup and tells you what's ready:
+On first launch, pi-voicekit checks your setup and tells you what's ready:
 
 - Backend configured (Deepgram key or local model)
 - Audio capture tool detected (sox, ffmpeg, or arecord)
@@ -87,7 +85,7 @@ On first launch, pi-listen checks your setup and tells you what's ready:
 
 ### Audio capture
 
-pi-listen auto-detects your audio tool. No manual install needed if you already have sox or ffmpeg.
+pi-voicekit auto-detects your audio tool. No manual install needed if you already have sox or ffmpeg.
 
 | Priority | Tool            | Platforms             | Install                                                      |
 | -------- | --------------- | --------------------- | ------------------------------------------------------------ |
@@ -95,36 +93,57 @@ pi-listen auto-detects your audio tool. No manual install needed if you already
 | 2        | **ffmpeg**      | macOS, Linux, Windows | `brew install ffmpeg` / `apt install ffmpeg`                 |
 | 3        | **arecord**     | Linux only            | Pre-installed (ALSA)                                         |
 
+> When `PULSE_SERVER` is set (SSH audio tunnel or remote PulseAudio) the order
+> becomes **ffmpeg → sox → arecord** — network Pulse sources need ffmpeg.
+
 ---
 
 ## Settings Panel
 
-All configuration lives in one place: `/voice-settings`. Four tabs cover everything you need.
+All configuration lives in one place: `/voice-settings`. Six tabs cover everything you need.
 
 ### General — backend, language, scope
 
-<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/settings-general.png" alt="General settings — backend, model, language, scope, voice toggle" width="600" />
+<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/screenshots/settings-general.png" alt="General settings — backend, model, language, scope, voice toggle" width="600" />
 
 Toggle between Deepgram (cloud, live streaming) and Local (offline, batch mode). Change language, scope, and enable/disable voice — all with keyboard shortcuts.
 
 ### Models — browse, search, install
 
-<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/settings-models.png" alt="Models tab — browse 21 models with accuracy/speed ratings" width="600" />
+<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/screenshots/settings-models.png" alt="Models tab — browse 21 models with accuracy/speed ratings" width="600" />
 
 Browse 21 models from Parakeet, Whisper, Moonshine, SenseVoice, GigaAM, Paraformer, and Qwen3. Each model shows accuracy and speed ratings (●●●●○/●●●●○), fitness badges, and download status. Fuzzy search to find models fast. Press Enter to activate and download.
 
 ### Downloaded — manage installed models
 
-<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/settings-downloaded.png" alt="Downloaded tab — manage installed models, activate or delete" width="600" />
+<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/screenshots/settings-downloaded.png" alt="Downloaded tab — manage installed models, activate or delete" width="600" />
 
 See what's installed, total disk usage, and which model is active. Press Enter to activate, `x` to delete. Models from [Handy](https://github.com/cjpais/handy) are auto-detected and can be imported without re-downloading.
 
+### Speak — TTS models and voices
+
+Pick a TTS backend (local sherpa-onnx or Deepgram Aura), browse 20 local voices
+from ~13 MB, download on selection, and choose a voice per backend. Auto-speak of
+agent replies is toggled here.
+
 ### Device — hardware profile and dependencies
 
-<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/settings-device.png" alt="Device tab — hardware profile, dependencies, disk space" width="600" />
+<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/screenshots/settings-device.png" alt="Device tab — hardware profile, dependencies, disk space" width="600" />
 
 See your hardware profile (RAM, CPU, GPU), dependency status (sherpa-onnx runtime), available disk space, and total downloaded models. Model recommendations are based on this profile.
 
+### Polish — transcript cleanup
+
+Optional post-ASR cleanup, on by default. Toggle it, pick the model, set how many
+recent conversation turns accompany the transcript (0–10), and cap how long one
+pass may take (`1000`–`30000` ms). The last row shows the most recent polished
+dictation as a `RAW` / `POLISHED` pair. `/voice-polish last` prints the newest
+dictation a pass ran on — including one whose result was discarded — with its
+`STATUS`, `RAW`, and `WRITTEN` text, or says that nothing was written.
+
+`/voice-polish` takes `on`, `off`, `model`, `turns <0-10>`, `last` and `restore`;
+run it with no argument for the current status.
+
 ---
 
 ## Usage
@@ -133,7 +152,7 @@ See your hardware profile (RAM, CPU, GPU), dependency status (sherpa-onnx runtim
 
 | Action               | Key                  | Notes                                                                   |
 | -------------------- | -------------------- | ----------------------------------------------------------------------- |
-| **Record to editor** | Hold `SPACE` (≥1.2s) | Release to finalize. Pre-records during warmup so you don't miss words. |
+| **Record to editor** | Hold `SPACE` (≥0.7s) | Release to finalize. Pre-records during warmup so you don't miss words. |
 | **Toggle recording** | `Ctrl+Shift+V`       | Works in all terminals — press to start, press again to stop.           |
 | **Clear editor**     | `Escape` × 2         | Double-tap within 500ms to clear all text.                              |
 
@@ -150,10 +169,16 @@ See your hardware profile (RAM, CPU, GPU), dependency status (sherpa-onnx runtim
 | ------------------------ | --------------------------------------------------------- |
 | `/voice-settings`        | Settings panel — backend, models, language, scope, device |
 | `/voice-models`          | Settings panel (Models tab)                               |
+| `/voice-setup`           | Run the first-run setup wizard                            |
+| `/voice-language`        | Open the settings panel to change language                |
 | `/voice-speak <text>`    | Speak text out loud (TTS)                                 |
 | `/voice-speak-test`      | Speak a sample sentence                                   |
 | `/voice-speak-toggle`    | Enable / disable TTS                                      |
-| `/voice-autosubmit` `[on | off]`                                                     | Toggle: STT text auto-sent to the agent |
+| `/voice-stream`          | Toggle Deepgram streaming TTS (cloud)                     |
+| `/voice-speak-stop`      | Stop in-flight TTS playback                               |
+| `/voice-autosubmit`      | Toggle: STT text auto-sent to the agent (`on`/`off`)      |
+| `/voice-polish [sub]`    | Transcript polish: on, off, model, turns, last, restore   |
+| `/voice-hold-delay`      | Set hold-to-talk delay (200-3000 ms, default 700)         |
 | `/voice-speak-models`    | Browse / install TTS voice models                         |
 | `/voice-speak-info`      | Diagnose TTS state                                        |
 | `/voice-help`            | Keyboard + command reference (or press `F1`)              |
@@ -245,10 +270,11 @@ Models from [Handy](https://github.com/cjpais/handy) (`~/Library/Application Sup
 | **Device-aware recommendations** | Scores models against your hardware. Only best-in-class models get [recommended].        |
 | **Enterprise download pipeline** | Pre-checks (disk, network, permissions), live progress with speed/ETA, post-verification |
 | **Handy integration**            | Auto-detects models from Handy app, imports via symlink                                  |
-| **Audio fallback chain**         | Tries sox, ffmpeg, arecord in order                                                      |
+| **Audio fallback chain**         | Tries sox → ffmpeg → arecord in order — ffmpeg first when `PULSE_SERVER` is set          |
 | **Pre-recording**                | Audio capture starts during warmup — you never miss the first word                       |
 | **Tail recording**               | Keeps recording 1.5s after release so your last word isn't clipped                       |
-| **Live streaming**               | Deepgram Nova 3 WebSocket — interim transcripts as you speak                             |
+| **Live streaming**               | Deepgram Nova 3 WebSocket (Nova 2 for Chinese locales) — live interim transcripts        |
+| **Transcript polish**            | Optional post-ASR cleanup — every dictation makes one extra model call; the last N conversation turns (default 2) are sent with it, and no conversation context at all when the turn count is zero. Disable with `/voice-polish off` |
 | **56+ languages**                | Deepgram: 56+ with live streaming. Local: up to 57 depending on model.                   |
 | **Continuous dictation**         | `/voice dictate` for long-form input without holding keys                                |
 | **Typing cooldown**              | Space holds within 400ms of typing are ignored                                           |
@@ -260,15 +286,52 @@ Models from [Handy](https://github.com/cjpais/handy) (`~/Library/Application Sup
 ## Architecture
 
 ```
-extensions/voice.ts                Main extension — state machine, recording, UI, settings panel
-extensions/voice/config.ts         Config loading, saving, migration
-extensions/voice/onboarding.ts     First-run wizard, language picker
-extensions/voice/deepgram.ts       Deepgram URL builder, API key resolver
-extensions/voice/local.ts          Model catalog (21 models), in-process transcription
-extensions/voice/device.ts         Device profiling — RAM, GPU, CPU, container detection
-extensions/voice/model-download.ts Download manager — resume, progress, verification, Handy import
-extensions/voice/sherpa-engine.ts   sherpa-onnx bindings — recognizer lifecycle, inference
-extensions/voice/settings-panel.ts  Settings panel — Component interface, overlay, 4 tabs
+# core
+extensions/voice.ts                         Main extension — state machine, recording, UI, command surface
+extensions/voice/config.ts                  Config loading, saving, migration
+extensions/voice/onboarding.ts              First-run wizard, language picker
+extensions/voice/audio-tool.ts              Capture tool detection (sox / ffmpeg / arecord)
+extensions/voice/hold-to-talk.ts            Hold detection, Kitty and non-Kitty terminals
+extensions/voice/release-controller.ts      Recording lifecycle, release handling
+
+# speech-to-text
+extensions/voice/deepgram.ts                Deepgram URL builder, API key resolver
+extensions/voice/local.ts                   Model catalog (21 models), in-process transcription
+extensions/voice/sherpa-engine.ts           sherpa-onnx bindings — recognizer lifecycle, inference
+extensions/voice/sherpa-loader.ts           Lazy native module loading
+extensions/voice/model-download.ts          Download manager — resume, progress, verification, Handy import
+extensions/voice/device.ts                  Device profiling — RAM, GPU, CPU, container detection
+
+# transcript post-processing
+extensions/voice/post-process.ts            Polish pass — fail-open guardrails, model resolution, bounded call
+extensions/voice/post-process-context.ts    Context assembly — recent turns and character caps
+extensions/voice/post-process-prompt.ts     Fixed polish prompt and request shape
+
+# text-to-speech
+extensions/voice/speak.ts                   Speak entry point, auto-speak wiring
+extensions/voice/tts-engine.ts              sherpa-onnx TTS synthesis
+extensions/voice/tts-deepgram.ts            Deepgram Aura voices (cloud)
+extensions/voice/tts-local-models.ts        Local TTS catalog — 20 voices (Kitten, Kokoro, Piper)
+extensions/voice/tts-playback.ts            Playback, buffering, player detection
+extensions/voice/tts-text-filter.ts         Code-block stripping, sentence prep
+extensions/voice/tts-onboarding.ts          TTS onboarding flow
+extensions/voice/tts-onboarding-overlay.ts  TTS onboarding overlay
+extensions/voice/tts-install-progress.ts    Model install progress widget
+extensions/voice/tts-playback-indicator.ts  Speaking indicator widget
+
+# settings and UI
+extensions/voice/settings-panel.ts          Settings panel — overlay, 6 tabs
+extensions/voice/ui-picker.ts               Generic list picker
+extensions/voice/ui-help-overlay.ts         Keyboard and command reference
+extensions/voice/ui-aura.ts                 Visual primitives (Liquid Braille, Aurora)
+extensions/voice/ui-widget-base.ts          Widget registry and base class
+extensions/voice/ui-render-ticker.ts        Shared render ticker
+extensions/voice/ui-icons.ts                Glyph and icon set
+extensions/voice/ui-width.ts                CJK-aware visual width helpers
+extensions/voice/ui-locale-labels.ts        Native language and voice labels
+
+# types
+extensions/voice/sherpa-onnx-node.d.ts      Type declarations for the optional native module
 ```
 
 ---
@@ -285,13 +348,13 @@ Settings stored in Pi's settings files under the `voice` key:
 ```json
 {
 	"voice": {
-		"version": 2,
+		"version": 3,
 		"enabled": true,
 		"language": "en",
 		"backend": "local",
 		"localModel": "parakeet-v3",
 		"scope": "global",
-		"onboarding": { "completed": true, "schemaVersion": 2 }
+		"onboarding": { "completed": true, "schemaVersion": 3 }
 	}
 }
 ```
@@ -300,6 +363,45 @@ Settings stored in Pi's settings files under the `voice` key:
 into `~/.pi/agent/settings.json`. If you paste a key during onboarding, that is
 an explicit save and it still goes to `~/.env.secrets` or `~/.zshrc`.
 
+Hold-to-talk delay defaults to **700 ms** (`/voice-hold-delay` accepts 200–3000 ms).
+
+### Transcript polish
+
+Transcript polish is on by default: every dictation runs one extra model call. When
+the selected model is a cloud provider, the text that leaves your machine is:
+
+- the transcript of the dictation;
+- the last N conversation turns of user and assistant text, where N is
+  `postProcessContextTurns` (default `2`; `0` sends no conversation context);
+- nothing else. The compaction summary is deliberately not sent: it is a digest built from
+  earlier messages, so it can carry residues of thinking and tool output, and it measured no
+  gain over the turns alone.
+
+One measured behaviour is worth knowing: a model that thinks before it answers may normalise a
+spoken operator into its symbol — `select star` comes back as `select *`. The information is
+unchanged, there is no setting for it, and `/voice-polish off` is the way to keep the words verbatim.
+
+Assistant text can contain anything the conversation contained — file paths,
+identifiers, values the agent echoed. The character limits bound how much is sent,
+not how sensitive it is. With the local backend, nothing else leaves your machine,
+and audio never does: recognition runs on this machine with no API key. Turn the
+feature off with `/voice-polish off` or the Polish tab's Enabled row.
+
+| Setting                   | Scope              | Default     | Notes                                                   |
+| ------------------------- | ------------------ | ----------- | ------------------------------------------------------- |
+| `postProcessEnabled`      | global only        | `true`      | Master switch. A project `voice` block cannot flip it.  |
+| `postProcessModel`        | global only        | `"session"` | Reuses the session model, or `provider/modelId`.        |
+| `postProcessContextTurns` | global and project | `2`         | Conversation turns sent with the transcript, `0`–`10`.  |
+| `postProcessTimeoutMs`    | global and project | `12000`     | Per-pass timeout in milliseconds, `1000`–`30000`.       |
+
+The global-only fields resolve from `~/.pi/agent/settings.json` even when a
+repository provides its own `voice` block, so a cloned repo can neither turn the
+feature on nor redirect where dictated text goes. The model is chosen from a
+picker (`/voice-polish model`), never typed: a hand-typed reference is refused,
+and an unavailable or malformed model keeps the raw transcript instead of
+switching provider. `postProcessNoticeShown` is machine-local bookkeeping for the
+one-time notice, not a user setting.
+
 ---
 
 ## Troubleshooting
@@ -310,6 +412,7 @@ Run `/voice test` inside Pi for full diagnostics.
 | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
 | "DEEPGRAM_API_KEY not set"                       | [Get a key](https://dpgr.am/pi-voice) → `export DEEPGRAM_API_KEY="..."` in `~/.zshrc`                           |
 | "No audio capture tool found"                    | `brew install sox` or `brew install ffmpeg`                                                                     |
+| Remote microphone records silence                | Audio over PulseAudio/SSH — install ffmpeg on the Pi side (capture then prefers ffmpeg)                         |
 | Space doesn't activate voice                     | Run `/voice-settings` — voice may be disabled                                                                   |
 | Local model not transcribing                     | Check `/voice-settings` → Device tab for sherpa-onnx status                                                     |
 | Download failed                                  | Partial downloads auto-resume on retry. Check disk space in Device tab.                                         |
@@ -321,7 +424,7 @@ Run `/voice test` inside Pi for full diagnostics.
 
 - **Cloud STT** — audio is sent to Deepgram for transcription (Deepgram backend only)
 - **Local STT** — audio never leaves your machine (local backend)
-- **No telemetry** — pi-listen does not collect or transmit usage data
+- **No telemetry** — pi-voicekit does not collect or transmit usage data
 - **API key** — stored in env var or Pi settings, never logged
 
 See [SECURITY.md](SECURITY.md) for vulnerability reporting.

package/extensions/voice/config.ts

@@ -7,7 +7,7 @@ function getAgentDir(): string {
 }
 
 export const SETTINGS_KEY = "voice";
-export const VOICE_CONFIG_VERSION = 2;
+export const VOICE_CONFIG_VERSION = 3;
 
 export type VoiceSettingsScope = "global" | "project";
 export type VoiceConfigSource = VoiceSettingsScope | "default";
@@ -40,6 +40,27 @@ export interface VoiceConfig {
 	/** Global-only shortcut used to toggle recording without hold-to-talk */
 	toggleShortcut?: string;
 
+	// ─── Post-processing (optional transcript polish) — new in v3 ─────
+
+	/**
+	 * Master switch for the post-ASR polish pass. Global-only — the
+	 * enablement decides whether dictated text makes an extra model call,
+	 * so a project file must not be able to flip it.
+	 */
+	postProcessEnabled?: boolean;
+	/**
+	 * Model used by the polish pass — "session" reuses the active session
+	 * model, or "<provider>/<modelId>". Global-only: the value decides
+	 * where dictated text is sent.
+	 */
+	postProcessModel?: string;
+	/** How many recent conversation turns accompany the transcript. Honoured in both scopes; clamped to [0, 10]. */
+	postProcessContextTurns?: number;
+	/** Upper bound in milliseconds for one polish pass. Honoured in both scopes; clamped to [1000, 30000]. */
+	postProcessTimeoutMs?: number;
+	/** Set once the one-time default-on notice has been shown. Global-only — it describes this machine, not the repository. */
+	postProcessNoticeShown?: boolean;
+
 	// ─── TTS (text-to-speech) ─────────────────────────────────────────
 	// All TTS fields are opt-in (default: TTS disabled). New in v6.0.0.
 
@@ -125,6 +146,12 @@ export const DEFAULT_CONFIG: VoiceConfig = {
 	localModel: undefined,
 	localEndpoint: undefined,
 	toggleShortcut: "ctrl+shift+v",
+	// Post-processing defaults — on by default (D5), reusing the session model
+	postProcessEnabled: true,
+	postProcessModel: "session",
+	postProcessContextTurns: 2,
+	postProcessTimeoutMs: 12000,
+	postProcessNoticeShown: false,
 	// TTS defaults — all opt-in
 	ttsEnabled: false,
 	ttsBackend: "local",
@@ -150,7 +177,7 @@ export function readJsonFile(filePath: string): Record<string, unknown> {
 		return JSON.parse(fs.readFileSync(filePath, "utf8"));
 	} catch (err) {
 		process.stderr.write(
-			`[pi-voice] Warning: failed to read ${filePath}: ${err instanceof Error ? err.message : err}\n`
+			`[pi-voicekit] Warning: failed to read ${filePath}: ${err instanceof Error ? err.message : err}\n`
 		);
 		return {};
 	}
@@ -176,11 +203,46 @@ function normalizeOnboarding(input: any, fallbackCompleted: boolean): VoiceOnboa
 	};
 }
 
-function migrateConfig(rawVoice: any, source: VoiceConfigSource): VoiceConfig {
+/** Clamp an integer config value; non-numeric or non-finite input takes the default. */
+function clampInt(value: unknown, min: number, max: number, fallback: number): number {
+	if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) return fallback;
+	return Math.max(min, Math.min(max, value));
+}
+
+function migrateConfig(rawVoice: any, source: VoiceConfigSource, globalVoice?: unknown): VoiceConfig {
 	if (!rawVoice || typeof rawVoice !== "object") {
 		return structuredClone(DEFAULT_CONFIG);
 	}
 
+	// D7: model selection, enablement and the notice flag are global-only, and a
+	// project file must not be able to inject an API key or point audio at a
+	// non-loopback host. These fields resolve from the global block in BOTH scopes —
+	// falling back to DEFAULT_CONFIG would let a cloned repository re-enable a
+	// feature the maintainer turned off globally (spec §4.2).
+	const projectScoped = source === "project";
+	const globalRaw: Record<string, unknown> =
+		globalVoice && typeof globalVoice === "object" ? (globalVoice as Record<string, unknown>) : {};
+	const globalOnly = (key: string): unknown => (projectScoped ? globalRaw[key] : rawVoice[key]);
+	const asString = (value: unknown): string | undefined => (typeof value === "string" && value ? value : undefined);
+	const asBoolean = (value: unknown, fallbackValue: boolean): boolean =>
+		typeof value === "boolean" ? value : fallbackValue;
+
+	for (const key of ["postProcessEnabled", "postProcessModel", "deepgramApiKey", "localEndpoint"]) {
+		if (!projectScoped || rawVoice[key] === undefined) continue;
+		// A loopback project endpoint is honoured, not ignored — reporting it would
+		// cry wolf on the safe case and weaken the signal for the discarded ones.
+		if (
+			key === "localEndpoint" &&
+			typeof rawVoice.localEndpoint === "string" &&
+			isLoopbackEndpoint(rawVoice.localEndpoint)
+		) {
+			continue;
+		}
+		// Never print a key, even one that is being ignored.
+		const shown = key === "deepgramApiKey" ? "<redacted>" : JSON.stringify(rawVoice[key]);
+		process.stderr.write(`[pi-voicekit] Ignoring project-scoped voice.${key} (${shown}); using the global value\n`);
+	}
+
 	// Legacy configs may have backend+model — treat that as completed onboarding
 	const hasMeaningfulLegacySetup =
 		(typeof rawVoice.backend === "string" && typeof rawVoice.model === "string") ||
@@ -192,14 +254,26 @@ function migrateConfig(rawVoice: any, source: VoiceConfigSource): VoiceConfig {
 		enabled: typeof rawVoice.enabled === "boolean" ? rawVoice.enabled : DEFAULT_CONFIG.enabled,
 		language: typeof rawVoice.language === "string" ? rawVoice.language : DEFAULT_CONFIG.language,
 		scope: (rawVoice.scope as VoiceSettingsScope | undefined) ?? (source === "project" ? "project" : "global"),
-		deepgramApiKey: typeof rawVoice.deepgramApiKey === "string" ? rawVoice.deepgramApiKey : undefined,
+		deepgramApiKey: asString(globalOnly("deepgramApiKey")),
 		backend: rawVoice.backend === "local" ? "local" : undefined,
 		localModel: typeof rawVoice.localModel === "string" ? rawVoice.localModel : undefined,
-		localEndpoint: typeof rawVoice.localEndpoint === "string" ? rawVoice.localEndpoint : undefined,
+		localEndpoint: projectScoped
+			? typeof rawVoice.localEndpoint === "string" && isLoopbackEndpoint(rawVoice.localEndpoint)
+				? rawVoice.localEndpoint
+				: asString(globalRaw.localEndpoint)
+			: asString(rawVoice.localEndpoint),
 		toggleShortcut:
 			source !== "project" && typeof rawVoice.toggleShortcut === "string"
 				? rawVoice.toggleShortcut
 				: DEFAULT_CONFIG.toggleShortcut,
+		// Post-processing fields (v3). Model selection, enablement and the
+		// notice flag resolve through `globalOnly`; the two numeric knobs are
+		// honoured in both scopes.
+		postProcessEnabled: asBoolean(globalOnly("postProcessEnabled"), DEFAULT_CONFIG.postProcessEnabled ?? true),
+		postProcessModel: asString(globalOnly("postProcessModel")) ?? DEFAULT_CONFIG.postProcessModel,
+		postProcessContextTurns: clampInt(rawVoice.postProcessContextTurns, 0, 10, DEFAULT_CONFIG.postProcessContextTurns!),
+		postProcessTimeoutMs: clampInt(rawVoice.postProcessTimeoutMs, 1000, 30000, DEFAULT_CONFIG.postProcessTimeoutMs!),
+		postProcessNoticeShown: asBoolean(globalOnly("postProcessNoticeShown"), false),
 		// TTS fields — type-validated; mismatched persisted values fall
 		// back to safe defaults so a hand-edited config can't poison the
 		// engine. Notably: ttsLocalVoiceId rejects strings (would crash
@@ -251,7 +325,7 @@ export function loadConfigWithSource(cwd: string, options: ConfigPathOptions = {
 
 	if (projectVoice && typeof projectVoice === "object") {
 		return {
-			config: migrateConfig(projectVoice, "project"),
+			config: migrateConfig(projectVoice, "project", globalVoice),
 			source: "project",
 			globalSettingsPath,
 			projectSettingsPath,
@@ -303,7 +377,7 @@ export function loadGlobalToggleShortcut(options: ConfigPathOptions = {}): strin
 			const candidate = (globalVoice as any).toggleShortcut;
 			if (isValidShortcut(candidate)) return candidate;
 			process.stderr.write(
-				`[pi-voice] Warning: invalid toggleShortcut "${candidate}" in settings, using default "${fallback}"\n`
+				`[pi-voicekit] Warning: invalid toggleShortcut "${candidate}" in settings, using default "${fallback}"\n`
 			);
 		}
 	} catch {
@@ -353,6 +427,11 @@ function serializeConfig(config: VoiceConfig, scope: VoiceSettingsScope): VoiceC
 			scope === "project" && config.localEndpoint && !isLoopbackEndpoint(config.localEndpoint)
 				? undefined
 				: config.localEndpoint,
+		// D7: model selection and enablement are global-only, and the notice flag
+		// describes this machine, not this repository.
+		postProcessEnabled: scope === "project" ? undefined : config.postProcessEnabled,
+		postProcessModel: scope === "project" ? undefined : config.postProcessModel,
+		postProcessNoticeShown: scope === "project" ? undefined : config.postProcessNoticeShown,
 		// Shortcut registration is static at extension load time — project-scoped overrides cannot apply
 		toggleShortcut: scope === "project" ? undefined : config.toggleShortcut,
 		onboarding: {
@@ -362,6 +441,23 @@ function serializeConfig(config: VoiceConfig, scope: VoiceSettingsScope): VoiceC
 	};
 }
 
+/**
+ * Atomic settings write: temp file + rename prevents corruption from partial
+ * writes. Shared by every writer in this module so the path cannot diverge.
+ */
+function writeSettingsFile(settingsPath: string, settings: Record<string, unknown>): void {
+	fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+	const tmpPath = `${settingsPath}.${process.pid}.tmp`;
+	try {
+		fs.writeFileSync(tmpPath, JSON.stringify(settings, null, 2) + "\n");
+		fs.renameSync(tmpPath, settingsPath);
+	} finally {
+		try {
+			if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
+		} catch {}
+	}
+}
+
 export function saveConfig(
 	config: VoiceConfig,
 	scope: VoiceSettingsScope,
@@ -371,17 +467,62 @@ export function saveConfig(
 	const settingsPath = scope === "project" ? getProjectSettingsPath(cwd) : getGlobalSettingsPath(options);
 	const settings = readJsonFile(settingsPath);
 	settings[SETTINGS_KEY] = serializeConfig(config, scope);
-	fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
-	// Atomic write: temp file + rename prevents corruption from partial writes
-	const tmpPath = `${settingsPath}.${process.pid}.tmp`;
-	try {
-		fs.writeFileSync(tmpPath, JSON.stringify(settings, null, 2) + "\n");
-		fs.renameSync(tmpPath, settingsPath);
-	} finally {
+	writeSettingsFile(settingsPath, settings);
+	return settingsPath;
+}
+
+/**
+ * The global-only keys `saveGlobalVoiceFields` accepts. A project block cannot
+ * carry them — `serializeConfig` strips them and the loader ignores them — so
+ * they always belong in the global file.
+ */
+type GlobalVoiceFieldKey = "postProcessEnabled" | "postProcessModel" | "postProcessNoticeShown";
+
+/**
+ * Field-level writer for the global-only voice settings (R26).
+ *
+ * `saveConfig(config, "global", …)` renders the WHOLE in-memory config, and in a
+ * project-scoped session that object also carries project and default values —
+ * writing it globally silently resets every unrelated machine-global setting
+ * (TTS speed, auto-submit, hold threshold, …). This writer instead reads the
+ * existing global file and merges only the named keys into its `voice` block:
+ *
+ * - an existing `version` is preserved; a block created here gets the current
+ *   schema version,
+ * - no other key is created, changed or removed,
+ * - a missing file or `voice` block is created,
+ * - a file that exists but cannot be parsed is refused, not overwritten,
+ * - the write is atomic (temp file + rename), like `saveConfig`.
+ */
+export function saveGlobalVoiceFields(
+	fields: Partial<Pick<VoiceConfig, GlobalVoiceFieldKey>>,
+	options: ConfigPathOptions = {}
+): string {
+	const settingsPath = getGlobalSettingsPath(options);
+	// The shared reader reports a file it cannot parse exactly like a missing one, so this
+	// writer has to tell them apart itself: merging into `{}` would replace a damaged
+	// settings file with a fresh object and lose every other key. An existing file that
+	// cannot be read is logged and left untouched; throwing hands the failure to the
+	// caller's guard instead of silently reporting a write that never happened.
+	let settings: Record<string, unknown> = {};
+	if (fs.existsSync(settingsPath)) {
 		try {
-			if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
-		} catch {}
+			settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`[pi-voicekit] Warning: not writing ${settingsPath}: ${reason}\n`);
+			throw new Error(`Refusing to overwrite an unreadable settings file: ${settingsPath}`);
+		}
+	}
+	const existing = settings[SETTINGS_KEY];
+	const voice: Record<string, unknown> =
+		existing && typeof existing === "object" ? { ...(existing as Record<string, unknown>) } : {};
+	if (typeof voice.version !== "number") voice.version = VOICE_CONFIG_VERSION;
+	for (const [key, value] of Object.entries(fields)) {
+		if (value !== undefined) voice[key] = value;
 	}
+	settings[SETTINGS_KEY] = voice;
+	writeSettingsFile(settingsPath, settings);
 	return settingsPath;
 }
 

package/extensions/voice/onboarding.ts

@@ -314,7 +314,7 @@ export function finalizeOnboardingConfig(
 }
 
 export async function promptFirstRunOnboarding(ctx: VoiceUiContext): Promise<FirstRunDecision> {
-	const choice = await ctx.ui.select("Set up pi-voice now?", ["Start voice setup", "Remind me later"]);
+	const choice = await ctx.ui.select("Set up pi-voicekit now?", ["Start voice setup", "Remind me later"]);
 
 	return { action: choice === "Start voice setup" ? "start" : "later" };
 }
@@ -665,7 +665,7 @@ export async function runVoiceOnboarding(
 	}
 
 	// ─── Choose scope ────────────────────────────────────────
-	const scopeChoice = await ctx.ui.select("Where should pi-voice settings be saved?", [
+	const scopeChoice = await ctx.ui.select("Where should pi-voicekit settings be saved?", [
 		"Global (all projects)",
 		"Project only (this repo)",
 	]);