@tychenjiajun/pi-voice 0.8.1 → 0.9.0

package/README.md

@@ -32,10 +32,10 @@ pi install ssh://git@github.com/tychenjiajun/pi-voice
 
 The extension registers:
 
-- a configurable terminal shortcut (`Ctrl+Alt+Z` by default) to start and stop recording;
+- a configurable terminal shortcut (`Ctrl+Space` by default) to start and stop recording;
 - `/voice`, which does the same as the shortcut. While recording, `Space` also stops and transcribes, and `Escape` discards;
 - a `transcribe_file` tool that the agent can use to transcribe local audio or video files;
-- `/voice-settings` for preferred languages, model, transcription backend, transcription language, post-processing, microphone, and shortcut settings.
+- `/voice-settings` for preferred languages, model, transcription backend, transcription language, post-processing (model and prompt), microphone, and shortcut settings.
 
 `/transcribe` remains available as a compatibility alias for `/voice-settings`.
 
@@ -74,6 +74,8 @@ Set it up in `/voice-settings` → **Post-processing** → **On**. You then choo
 - **Pi's current model** (default) — whichever model the agent is using, exactly like compaction;
 - **a different model** — any model from Pi's registry, using that provider's configured authentication. The picker is searchable: type a keyword (a model name or part of `provider/id`) to filter the list, `Enter` selects the highlighted match, and `Esc` clears the search.
 
+**Post-processing prompt** (the row below it) controls the instructions the model follows. **Built-in default** strips fillers and false starts, fixes punctuation and casing, and keeps the language, names, numbers, and technical terms exactly. **Custom prompt** opens a multi-line editor prefilled with the built-in wording, so you can adjust it instead of retyping it — for example to keep the transcript verbatim and only add punctuation, translate, or reformat as Markdown. Clearing the editor, or picking **Built-in default**, restores the built-in prompt; the row summary shows `Built-in default` or `Custom (n chars)`. The custom prompt replaces the built-in system prompt entirely, so keep the "output only the refined text" instruction if you want it.
+
 Pi Voice makes a small nested request through Pi's model registry, so it automatically reuses Pi's model definitions and API keys (or OAuth). No base URL, key, or timeout is stored in Pi Voice settings.
 
 Behavior:
@@ -82,6 +84,7 @@ Behavior:
 - **Reasoning-safe.** A provider's thinking is ignored (Pi reports it as `thinking` blocks), and inline reasoning tags a model may embed in its text are stripped. If only reasoning comes back, the raw transcript is kept.
 - **Discrete, not streaming.** Refinement happens after the full transcript is produced, so there is no live preview of the polished text.
 - **Applies to all transcription.** Microphone dictation and the `transcribe_file` tool both go through the same post-processing step when it is enabled.
+- **Custom prompt is optional and stored in settings.** `polishPrompt` in `settings.json` holds the custom instructions; absent means the built-in prompt. The prompt is sent as the system prompt of the refinement request, and an empty or whitespace-only value falls back to the built-in one.
 
 ## Upgrading from pi-transcribe
 
@@ -142,6 +145,14 @@ Only for the `transcribe_file` tool (transcribing existing audio/video files). M
 
 ## Changelog
 
+### 0.9.0
+
+**Added — Configurable post-processing prompt**
+
+- `/voice-settings` → **Post-processing prompt** (shown while **Post-processing** is On) opens a picker with **Built-in default** or **Custom prompt**; the row summary reads `Built-in default` or `Custom (n chars)`.
+- **Custom prompt** opens a multi-line editor prefilled with the built-in wording, so the default can be adjusted instead of retyped — for example to keep transcripts verbatim, translate, or reformat as Markdown. Clearing the editor, or picking **Built-in default**, restores the built-in prompt.
+- The custom instructions are stored as `polishPrompt` in `settings.json` and sent as the system prompt of the refinement request. They replace the built-in prompt entirely, including its rule that the transcript is text to edit and never instructions to follow; an absent, blank, or over-20 000-character value means the built-in prompt is used.
+
 ### 0.8.0
 
 **Added — Upstream sync: voice activity detection, long-audio chunking, and language detection**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tychenjiajun/pi-voice",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Speech-to-text for the Pi coding agent: press a shortcut and dictate — transcripts land directly in your chat. Local models (Whisper, Parakeet) or any OpenAI-compatible remote ASR endpoint, with compaction-style post-processing that strips fillers.",
   "type": "module",
   "license": "MIT",
@@ -64,8 +64,8 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.3.0",
-    "@earendil-works/pi-tui": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "^1.4.0",
     "@huggingface/gguf": "^0.4.6",
     "@types/node": "22.20.1",
     "typebox": "^1.3.7",

package/src/default-shortcut.ts

@@ -0,0 +1,45 @@
+import { execFileSync } from "node:child_process";
+
+/** The shortcut new users get when nothing on the system claims it. */
+export const PREFERRED_SHORTCUT = "ctrl+space";
+/** Used instead when Ctrl+Space would switch keyboard input sources. */
+export const FALLBACK_SHORTCUT = "ctrl+alt+z";
+
+const KEYBOARD_SOURCE =
+  /InputSourceKind = "(?:Keyboard Layout|Keyboard Input Method|Input Mode)"/g;
+
+/** macOS only claims Ctrl+Space once there are two keyboard sources to switch between. */
+export function hasMultipleInputSources(enabledSources: string): boolean {
+  return (enabledSources.match(KEYBOARD_SOURCE)?.length ?? 0) > 1;
+}
+
+function macCtrlSpaceSwitchesInput(): boolean {
+  try {
+    const enabledSources = execFileSync(
+      "/usr/bin/defaults",
+      ["read", "com.apple.HIToolbox", "AppleEnabledInputSources"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 1000 },
+    );
+    return hasMultipleInputSources(enabledSources);
+  } catch {
+    // Unknown counts as taken; the fallback works everywhere.
+    return true;
+  }
+}
+
+/** fcitx toggles on Ctrl+Space by default; IBus and GNOME use Super+Space. */
+function linuxCtrlSpaceSwitchesInput(env: NodeJS.ProcessEnv): boolean {
+  return [env.XMODIFIERS, env.GTK_IM_MODULE, env.QT_IM_MODULE].some((value) =>
+    value?.includes("fcitx"),
+  );
+}
+
+/** Only for users without saved settings, which always store a shortcut. */
+export function defaultShortcut(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  if (platform === "darwin" && macCtrlSpaceSwitchesInput()) return FALLBACK_SHORTCUT;
+  if (platform === "linux" && linuxCtrlSpaceSwitchesInput(env)) return FALLBACK_SHORTCUT;
+  return PREFERRED_SHORTCUT;
+}

package/src/file-transcription.ts

@@ -162,13 +162,12 @@ export function registerFileTranscriptionTool(
               operationSignal,
             );
             const transcript = configured.polishEnabled
-              ? await polishTranscript(
-                  ctx,
-                  rawTranscript,
-                  true,
-                  configured.polishModel,
-                  operationSignal,
-                )
+              ? await polishTranscript(ctx, rawTranscript, {
+                  enabled: true,
+                  modelRef: configured.polishModel,
+                  prompt: configured.polishPrompt,
+                  signal: operationSignal,
+                })
               : rawTranscript;
             const details: FileTranscriptionDetails = {
               inputPath,

package/src/index.ts

@@ -10,6 +10,7 @@ import {
   findLegacyGitInstall,
   legacyGitMigrationMessage,
 } from "./install-migration.js";
+import { takeReadyRequest } from "./ready-handoff.js";
 import type { PiVoiceRuntime } from "./runtime.js";
 import { displayShortcut, STATUS_WIDGET_KEY } from "./shortcut-core.js";
 import { initLog, log, logStep, markKeyPress, watchEventLoop } from "./log.js";
@@ -43,6 +44,12 @@ export default function piVoice(pi: ExtensionAPI): void {
   }
 
   pi.on("session_start", async (_event, ctx) => {
+    // Setup that saved a new shortcut reloaded to bind it; finish it here.
+    if (takeReadyRequest()) {
+      await (await loadRuntime()).showReadyAfterReload(ctx);
+      return;
+    }
+
     let showedMigrationNotice = false;
     if (ctx.mode === "tui") {
       const legacyInstall = findLegacyGitInstall(pi.getCommands());

package/src/onboarding.ts

@@ -30,7 +30,6 @@ import {
   type TranscribeSettings,
   type TranscriptionLanguage,
 } from "./settings.js";
-import { DEFAULT_SHORTCUT } from "./shortcut-core.js";
 import {
   SingleSelectPicker,
   type SingleSelectChoice,
@@ -58,7 +57,7 @@ function createSettingsActivation(
 }
 
 type ModelSelectionOptions = {
-  shortcut?: string;
+  shortcut: string;
   preferredLanguages?: readonly string[];
   transcriptionLanguage?: TranscriptionLanguage;
   chineseOutput?: ChineseOutput;
@@ -70,6 +69,8 @@ type ModelSelectionOptions = {
   polishEnabled?: boolean;
   /** Preserved across the model re-pick; absent means the agent's current model. */
   polishModel?: PolishModelRef;
+  /** Preserved across the model re-pick; absent means the built-in prompt. */
+  polishPrompt?: string;
   voiceActivityDetection?: boolean;
   longformChunking?: boolean;
   /** Persists language changes made before this flow activates a model. */
@@ -79,7 +80,7 @@ type ModelSelectionOptions = {
 
 export async function runModelSelection(
   ctx: ExtensionContext,
-  options: ModelSelectionOptions = {},
+  options: ModelSelectionOptions,
 ): Promise<TranscribeSettings | undefined> {
   if (!requireTui(ctx)) return undefined;
 
@@ -90,7 +91,7 @@ export async function runModelSelection(
   let configured: TranscribeSettings | undefined;
   const { activate, waitForCommits } = createSettingsActivation(
     () => ({
-      shortcut: configured?.shortcut ?? options.shortcut ?? DEFAULT_SHORTCUT,
+      shortcut: configured?.shortcut ?? options.shortcut,
       preferredLanguages,
       transcriptionLanguage:
         configured?.transcriptionLanguage ?? options.transcriptionLanguage,
@@ -99,6 +100,7 @@ export async function runModelSelection(
       backend: configured?.backend ?? options.backend,
       polishEnabled: configured?.polishEnabled ?? options.polishEnabled ?? false,
       polishModel: configured?.polishModel ?? options.polishModel,
+      polishPrompt: configured?.polishPrompt ?? options.polishPrompt,
       voiceActivityDetection: configured?.voiceActivityDetection ?? options.voiceActivityDetection,
       longformChunking: configured?.longformChunking ?? options.longformChunking,
     }),
@@ -233,6 +235,7 @@ export async function changeOnboardingModel(
       backend: current.backend,
       polishEnabled: current.polishEnabled,
       polishModel: current.polishModel,
+      polishPrompt: current.polishPrompt,
       voiceActivityDetection: current.voiceActivityDetection,
       longformChunking: current.longformChunking,
     }),
@@ -322,7 +325,7 @@ async function chooseSetupMode(ctx: ExtensionContext): Promise<SetupMode | undef
 
 export async function runOnboarding(
   ctx: ExtensionContext,
-  shortcut = DEFAULT_SHORTCUT,
+  shortcut: string,
 ): Promise<TranscribeSettings | undefined> {
   if (!requireTui(ctx)) return undefined;
 

package/src/polish.ts

@@ -13,6 +13,11 @@ import type { PolishModelRef } from "./settings.js";
  * empty response — the original transcript is returned unchanged. Provider
  * reasoning is ignored (Pi reports it as `thinking` blocks), and inline
  * reasoning tags are stripped from the refined text.
+ *
+ * The instructions can be replaced from settings (`polishPrompt`); the built-in
+ * prompt below remains the default and the starting point for editing. A custom
+ * prompt is the whole system prompt, so it also takes over rule 5 of the
+ * built-in one: the transcript is text to edit, never instructions to follow.
  */
 
 export const POLISH_SYSTEM_PROMPT = `# Role
@@ -73,13 +78,26 @@ type PolishModelRegistry = {
   ): Promise<PolishAssistantMessage>;
 };
 
+export type PolishRequest = {
+  /** When false the raw transcript is returned untouched. */
+  enabled: boolean;
+  /** Explicit model override; absent uses the agent's current model. */
+  modelRef?: PolishModelRef;
+  /**
+   * The whole system prompt when set; absent or blank uses POLISH_SYSTEM_PROMPT.
+   * A custom value replaces the built-in prompt entirely, including its rule that
+   * treats the transcript as text and never as instructions.
+   */
+  prompt?: string;
+  signal?: AbortSignal;
+};
+
 export async function polishTranscript(
   ctx: ExtensionContext,
   text: string,
-  enabled: boolean,
-  modelRef?: PolishModelRef,
-  signal?: AbortSignal,
+  request: PolishRequest,
 ): Promise<string> {
+  const { enabled, modelRef, signal } = request;
   if (!enabled) return text;
   const trimmed = text.trim();
   if (!trimmed) return text;
@@ -87,6 +105,9 @@ export async function polishTranscript(
   const requestSignal = signal ?? ctx.signal;
   if (requestSignal?.aborted) return text;
 
+  const customPrompt = request.prompt?.trim();
+  const systemPrompt = customPrompt || POLISH_SYSTEM_PROMPT;
+
   // An explicit override is resolved against Pi's own model definitions, so it
   // shares the same catalog and provider authentication as the agent. Falls
   // back to the agent's current model when the override is unusable.
@@ -113,14 +134,15 @@ export async function polishTranscript(
   writeLog(
     "info",
     "polish",
-    `refining ${trimmed.length} chars with ${model.provider ?? "?"}/${model.id ?? "?"}`,
+    `refining ${trimmed.length} chars with ${model.provider ?? "?"}/${model.id ?? "?"}` +
+      `${customPrompt ? " (custom prompt)" : ""}`,
   );
 
   try {
     const response = await registry.complete(
       model,
       {
-        systemPrompt: POLISH_SYSTEM_PROMPT,
+        systemPrompt,
         messages: [
           {
             role: "user",

package/src/ready-handoff.ts

@@ -0,0 +1,15 @@
+// ctx.reload() clears widgets, so setup asks the next instance to show Ready.
+// Reload re-evaluates the extension in the same process; a global symbol survives it.
+const READY_AFTER_RELOAD = Symbol.for("pi-voice.readyAfterReload");
+
+type Handoff = { [READY_AFTER_RELOAD]?: true };
+
+export function requestReadyAfterReload(): void {
+  (globalThis as Handoff)[READY_AFTER_RELOAD] = true;
+}
+
+export function takeReadyRequest(): boolean {
+  const requested = (globalThis as Handoff)[READY_AFTER_RELOAD] === true;
+  delete (globalThis as Handoff)[READY_AFTER_RELOAD];
+  return requested;
+}

package/src/runtime.ts

@@ -12,6 +12,7 @@ import { logStep, watchEventLoop } from "./log.js";
 import { DictationController } from "./dictation-controller.js";
 import { VoiceKeys } from "./keybindings.js";
 import { polishTranscript } from "./polish.js";
+import { requestReadyAfterReload, takeReadyRequest } from "./ready-handoff.js";
 import type { TranscribeSettings } from "./settings.js";
 import { displayShortcut } from "./shortcut-core.js";
 import { TranscriptionService } from "./transcription-service.js";
@@ -36,6 +37,8 @@ export type PiVoiceRuntime = {
   toggleCapture(ctx: ExtensionContext): Promise<void>;
   showSettings(ctx: ExtensionCommandContext): Promise<void>;
   replayOnboarding(ctx: ExtensionCommandContext): Promise<void>;
+  /** Shows Ready for setup that a reload interrupted. */
+  showReadyAfterReload(ctx: ExtensionContext): Promise<void>;
   shutdown(ctx: ExtensionContext): Promise<void>;
 };
 
@@ -93,13 +96,13 @@ export function createPiVoiceRuntime(
     settingsReadWarning = undefined;
   }
 
-  async function notifyReady(ctx: ExtensionContext, configured: TranscribeSettings): Promise<void> {
+  async function notifyReady(ctx: ExtensionContext, shortcut: string): Promise<void> {
     // Pi binds shortcuts at extension load. The command path reloads on its
     // own; the shortcut path cannot, so say what it takes to use a new one.
-    const reloadNeeded = configured.shortcut !== registeredShortcut;
+    const reloadNeeded = shortcut !== registeredShortcut;
     const talk = reloadNeeded
-      ? `run /reload, then ${displayShortcut(configured.shortcut)} to talk`
-      : `${displayShortcut(configured.shortcut)} to talk`;
+      ? `run /reload, then ${displayShortcut(shortcut)} to talk`
+      : `${displayShortcut(shortcut)} to talk`;
     const command = "/voice-settings";
     const commandDescription = "to change settings and download new models";
     const summary = `${command} ${commandDescription}`;
@@ -152,6 +155,7 @@ export function createPiVoiceRuntime(
       backend: previous.backend,
       polishEnabled: previous.polishEnabled,
       polishModel: previous.polishModel,
+      polishPrompt: previous.polishPrompt,
       voiceActivityDetection: previous.voiceActivityDetection,
       longformChunking: previous.longformChunking,
       postActivation: "advance",
@@ -160,9 +164,10 @@ export function createPiVoiceRuntime(
     return configured;
   }
 
+  // `setUp`: setup ran and finished; the caller shows Ready since only it knows if a reload follows.
   async function ensureSettings(
     ctx: ExtensionContext,
-  ): Promise<{ configured?: TranscribeSettings; completedFirstRun: boolean }> {
+  ): Promise<{ configured?: TranscribeSettings; setUp: boolean; completedFirstRun: boolean }> {
     await loadSettingsOnce();
     if (settingsReadWarning && !settingsWarningShown) {
       settingsWarningShown = true;
@@ -170,7 +175,7 @@ export function createPiVoiceRuntime(
     }
 
     if (settings && (!settings.model || existsSync(settings.model.path))) {
-      return { configured: settings, completedFirstRun: false };
+      return { configured: settings, setUp: false, completedFirstRun: false };
     }
 
     const previous = settings;
@@ -185,8 +190,11 @@ export function createPiVoiceRuntime(
     const configured = previous
       ? await configureModel(ctx, previous)
       : await configureFirstRun(ctx);
-    if (configured) await notifyReady(ctx, configured);
-    return { configured, completedFirstRun: previous === undefined && configured !== undefined };
+    return {
+      configured,
+      setUp: configured !== undefined,
+      completedFirstRun: previous === undefined && configured !== undefined,
+    };
   }
 
   async function requireConfiguredSettingsForTool(): Promise<TranscribeSettings> {
@@ -303,7 +311,11 @@ export function createPiVoiceRuntime(
         await reportDictationError(ctx, active.dictation);
       } else if (result.text) {
         const text = active.settings.polishEnabled
-          ? await polishTranscript(ctx, result.text, true, active.settings.polishModel)
+          ? await polishTranscript(ctx, result.text, {
+              enabled: true,
+              modelRef: active.settings.polishModel,
+              prompt: active.settings.polishPrompt,
+            })
           : result.text;
         ctx.ui.pasteToEditor(text);
         showTranscribeStatus(
@@ -422,7 +434,8 @@ export function createPiVoiceRuntime(
       clearTranscribeWidget(ctx);
     }
 
-    const { configured, completedFirstRun } = await ensureSettings(ctx);
+    const { configured, setUp, completedFirstRun } = await ensureSettings(ctx);
+    if (configured && setUp) await notifyReady(ctx, configured.shortcut);
     if (configured && !completedFirstRun) await startRecording(ctx, configured);
     // The meter shares the widget slot and has replaced the spinner when
     // recording began; clear the spinner only when recording never started.
@@ -462,14 +475,16 @@ export function createPiVoiceRuntime(
     }
 
     let reload = false;
+    let readyShortcut: string | undefined;
     await runExclusive(ctx, async () => {
-      await loadSettingsOnce();
-      const { configured, completedFirstRun } = await ensureSettings(ctx);
+      const { configured, setUp } = await ensureSettings(ctx);
       if (!configured) return;
-      if (completedFirstRun) {
+      if (setUp) {
         // First-run setup ends on its Ready message rather than falling
         // straight through into the regular settings menu.
         reload = configured.shortcut !== registeredShortcut;
+        if (reload) readyShortcut = configured.shortcut;
+        else await notifyReady(ctx, configured.shortcut);
         return;
       }
       // A recovered missing model file also lands here: the user asked for
@@ -478,8 +493,19 @@ export function createPiVoiceRuntime(
       const { showSettingsMenu } = await import("./settings-menu.js");
       reload = await showSettingsMenu(pi, ctx, configured, registeredShortcut);
     });
-    if (reload) {
-      await ctx.reload();
+    if (reload) await reloadForShortcut(ctx, readyShortcut);
+  }
+
+  // Reload clears widgets, so Ready after setup is shown by the next instance.
+  async function reloadForShortcut(
+    ctx: ExtensionCommandContext,
+    readyShortcut: string | undefined,
+  ): Promise<void> {
+    if (readyShortcut) requestReadyAfterReload();
+    await ctx.reload();
+    // Unclaimed means Pi declined the reload (e.g. mid-response): show Ready with the /reload hint.
+    if (takeReadyRequest() && readyShortcut && !shuttingDown) {
+      await notifyReady(ctx, readyShortcut);
     }
   }
 
@@ -493,6 +519,7 @@ export function createPiVoiceRuntime(
       return;
     }
 
+    let readyShortcut: string | undefined;
     await runExclusive(ctx, async () => {
       await loadSettingsOnce();
       const { runOnboarding } = await import("./onboarding.js");
@@ -502,10 +529,15 @@ export function createPiVoiceRuntime(
       );
       if (!configured) return;
       rememberSettings(configured);
-      // End on the same Ready state as first-run setup. A replay should expose
-      // the complete user flow rather than a debug-only completion message.
-      await notifyReady(ctx, configured);
+      // End like first-run setup: Ready, reloading first if the shortcut changed.
+      if (configured.shortcut === registeredShortcut) await notifyReady(ctx, configured.shortcut);
+      else readyShortcut = configured.shortcut;
     });
+    if (readyShortcut) await reloadForShortcut(ctx, readyShortcut);
+  }
+
+  async function showReadyAfterReload(ctx: ExtensionContext): Promise<void> {
+    await notifyReady(ctx, registeredShortcut);
   }
 
   async function shutdown(ctx: ExtensionContext): Promise<void> {
@@ -536,6 +568,7 @@ export function createPiVoiceRuntime(
     toggleCapture,
     showSettings,
     replayOnboarding,
+    showReadyAfterReload,
     shutdown,
   };
 }

package/src/settings-menu.ts

@@ -21,6 +21,7 @@ import {
 import { runModelSelection } from "./onboarding.js";
 import { chooseBackendType, promptRemoteBackend, warnMissingApiKey } from "./remote-asr.js";
 import {
+  MAX_POLISH_PROMPT_LENGTH,
   settingsWithPreferredLanguages,
   writeSettings,
   type BackendSettings,
@@ -32,6 +33,7 @@ import {
 } from "./settings.js";
 import { displayShortcut } from "./shortcut-core.js";
 import { createShortcutPicker } from "./shortcuts.js";
+import { POLISH_SYSTEM_PROMPT } from "./polish.js";
 import {
   padToWidth,
   SingleSelectPicker,
@@ -51,6 +53,7 @@ export type SettingsAction =
   | "transcription-language"
   | "chinese-output"
   | "post-processing"
+  | "post-processing-prompt"
   | "microphone"
   | "shortcut";
 
@@ -99,6 +102,10 @@ function polishSummary(polishEnabled: boolean | undefined, model: PolishModelRef
   return model ? `${model.provider}/${model.id}` : "Pi's current model";
 }
 
+function polishPromptSummary(prompt: string | undefined): string {
+  return prompt ? `Custom (${prompt.length} chars)` : "Built-in default";
+}
+
 let detectorDownload: Promise<void> | undefined;
 
 /**
@@ -164,6 +171,18 @@ export function settingsHomeChoices(
     },
   );
 
+  // The prompt only applies to a refinement that runs, so its row follows the
+  // post-processing toggle instead of offering dead configuration.
+  if (configured.polishEnabled) {
+    choices.push({
+      value: "post-processing-prompt",
+      label: "Post-processing prompt",
+      summary: polishPromptSummary(configured.polishPrompt),
+      description:
+        "Instructions the post-processing model follows; edit or reset the built-in prompt",
+    });
+  }
+
   if (model) {
     choices.push({
       value: "transcription-language",
@@ -344,6 +363,7 @@ async function editBackend(
       backend: { type: "transcribe-cpp" },
       polishEnabled: configured.polishEnabled,
       polishModel: configured.polishModel,
+      polishPrompt: configured.polishPrompt,
       postActivation: "stay",
     });
     if (!updated) {
@@ -499,6 +519,92 @@ async function editPostProcessing(
   );
 }
 
+type PolishPromptSource = "default" | "custom";
+
+/** Ask whether post-processing runs the built-in prompt or a custom one. */
+export async function choosePolishPromptSource(
+  ctx: ExtensionContext,
+  current: string | undefined,
+): Promise<PolishPromptSource | undefined> {
+  const choices: SingleSelectChoice<PolishPromptSource>[] = [
+    {
+      value: "default",
+      label: "Built-in default",
+      description:
+        "Strip fillers and false starts, fix punctuation and casing; keeps the language and technical terms exactly",
+    },
+    {
+      value: "custom",
+      label: "Custom prompt",
+      description:
+        "Write your own instructions, starting from the built-in prompt; your text replaces it entirely, including its rule that the transcript is never instructions",
+    },
+  ];
+  return ctx.ui.custom<PolishPromptSource | undefined>((tui, theme, keybindings, done) =>
+    new SingleSelectPicker(
+      tui,
+      theme,
+      keybindings,
+      choices,
+      current ? "custom" : "default",
+      { title: "Post-processing prompt", cancelLabel: "back" },
+      done,
+    ),
+  );
+}
+
+/**
+ * Post-processing prompt flow: pick the built-in prompt or edit a custom one.
+ * Clearing the custom text resets to the built-in prompt, so the editor doubles
+ * as a way to read and restore the default.
+ */
+export async function editPostProcessingPrompt(
+  ctx: ExtensionContext,
+  configured: TranscribeSettings,
+): Promise<boolean> {
+  const source = await choosePolishPromptSource(ctx, configured.polishPrompt);
+  if (!source) return false;
+
+  const resetToDefault = (message: string): Promise<boolean> =>
+    saveUpdatedSettings(ctx, configured, { ...configured, polishPrompt: undefined }, message);
+
+  if (source === "default") {
+    if (!configured.polishPrompt) return false;
+    return resetToDefault("Post-processing uses the built-in prompt");
+  }
+
+  // Prefilled so the built-in wording can be adjusted instead of retyped.
+  const edited = await ctx.ui.editor(
+    "Post-processing prompt (clear it to restore the built-in default)",
+    configured.polishPrompt ?? POLISH_SYSTEM_PROMPT,
+  );
+  if (edited === undefined) return false;
+
+  const prompt = edited.trim();
+  if (prompt.length > MAX_POLISH_PROMPT_LENGTH) {
+    ctx.ui.notify(
+      `Post-processing prompt is too long (${prompt.length} characters; the limit is ${MAX_POLISH_PROMPT_LENGTH})`,
+      "error",
+    );
+    return false;
+  }
+  if (!prompt) {
+    if (!configured.polishPrompt) return false;
+    return resetToDefault("Post-processing prompt reset to the built-in default");
+  }
+  if (prompt === configured.polishPrompt) return false;
+  // Saving the prefilled built-in text unchanged is not a custom prompt: storing
+  // it would relabel the row "Custom" and pin a copy that no longer tracks
+  // improvements to the built-in wording.
+  if (!configured.polishPrompt && prompt === POLISH_SYSTEM_PROMPT.trim()) return false;
+  return saveUpdatedSettings(
+    ctx,
+    configured,
+    { ...configured, polishPrompt: prompt },
+    `Post-processing prompt saved (${prompt.length} characters)`,
+  );
+}
+
 export async function openMacOSMicrophoneSettings(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
@@ -576,6 +682,7 @@ export async function showSettingsMenu(
         backend: configured.backend,
         polishEnabled: configured.polishEnabled,
         polishModel: configured.polishModel,
+        polishPrompt: configured.polishPrompt,
         voiceActivityDetection: configured.voiceActivityDetection,
         longformChunking: configured.longformChunking,
         postActivation: "stay",
@@ -601,6 +708,11 @@ export async function showSettingsMenu(
       continue;
     }
 
+    if (action === "post-processing-prompt") {
+      await editPostProcessingPrompt(ctx, configured);
+      continue;
+    }
+
     if (action === "transcription-language") {
       const transcriptionLanguage = await chooseTranscriptionLanguage(ctx, configured);
       if (!transcriptionLanguage) continue;

package/src/settings.ts

@@ -6,7 +6,7 @@ import {
   type CatalogModel,
 } from "./catalog.js";
 import { autoLanguagePolicy } from "./language-detection-policy.js";
-import { DEFAULT_SHORTCUT, normalizeShortcut } from "./shortcut-core.js";
+import { normalizeShortcut } from "./shortcut-core.js";
 import { legacySettingsPath, settingsPath } from "./settings-path.js";
 
 const SETTINGS_VERSION = 1;
@@ -58,6 +58,8 @@ export type TranscribeSettings = {
   polishEnabled?: boolean;
   /** Optional post-processing model override; absent uses the agent's current model. */
   polishModel?: PolishModelRef;
+  /** Optional post-processing instructions; absent uses the built-in prompt. */
+  polishPrompt?: string;
   /** Transcribe only the speech in a recording, not its silence and noise. */
   voiceActivityDetection: boolean;
   /** Hidden, settings.json only: false decodes long audio in one piece, without voice activity cuts. */
@@ -175,6 +177,22 @@ function normalizePolishModel(value: unknown): PolishModelRef | undefined {
   return { provider: value.provider.trim(), id: value.id.trim() };
 }
 
+/** A custom prompt replaces the whole system prompt, so keep it to a sane size. */
+export const MAX_POLISH_PROMPT_LENGTH = 20_000;
+
+/**
+ * A blank or non-string prompt means "use the built-in one", so it is dropped.
+ * So is one over the cap: the value would become a model system prompt, and the
+ * editor never writes one that large, so it can only come from a hand-edited
+ * file.
+ */
+function normalizePolishPrompt(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const prompt = value.trim();
+  if (!prompt || prompt.length > MAX_POLISH_PROMPT_LENGTH) return undefined;
+  return prompt;
+}
+
 function validateModelValue(
   value: unknown,
 ): { id: string; path: string; catalogModel: CatalogModel } | undefined {
@@ -203,6 +221,7 @@ function validateSettings(value: unknown): TranscribeSettings | undefined {
   const microphone = validateMicrophone(value.microphone);
   if (!preferredLanguages || !microphone) return undefined;
   const polishModel = normalizePolishModel(value.polishModel);
+  const polishPrompt = normalizePolishPrompt(value.polishPrompt);
 
   // The remote endpoint detects the language itself; the stored language only
   // triggers Chinese script conversion, so any previous value is kept as-is.
@@ -227,6 +246,7 @@ function validateSettings(value: unknown): TranscribeSettings | undefined {
     microphone,
     polishEnabled: value.polishEnabled === true,
     ...(polishModel ? { polishModel } : {}),
+    ...(polishPrompt ? { polishPrompt } : {}),
     voiceActivityDetection: value.voiceActivityDetection !== false,
     longformChunking: value.longformChunking !== false,
     ...(backend.type === "transcribe-cpp"
@@ -288,7 +308,7 @@ export async function writeSettings(settings: TranscribeSettings): Promise<void>
 }
 
 type ModelSettingsOptions = {
-  shortcut?: string;
+  shortcut: string;
   preferredLanguages?: readonly string[];
   transcriptionLanguage?: TranscriptionLanguage;
   chineseOutput?: ChineseOutput;
@@ -302,6 +322,8 @@ type ModelSettingsOptions = {
   polishEnabled?: boolean;
   /** Preserved across model re-selection; absent means the agent's current model. */
   polishModel?: PolishModelRef;
+  /** Preserved across model re-selection; absent means the built-in prompt. */
+  polishPrompt?: string;
   voiceActivityDetection?: boolean;
   longformChunking?: boolean;
 };
@@ -309,7 +331,7 @@ type ModelSettingsOptions = {
 export function settingsForModel(
   modelId: string,
   modelPath: string,
-  options: ModelSettingsOptions = {},
+  options: ModelSettingsOptions,
 ): TranscribeSettings {
   const model = getCatalogModel(modelId);
   if (!model) throw new Error(`Unknown catalog model: ${modelId}`);
@@ -323,7 +345,7 @@ export function settingsForModel(
       options.backend && options.backend.type === "transcribe-cpp"
         ? options.backend
         : { type: "transcribe-cpp" },
-    shortcut: options.shortcut ?? DEFAULT_SHORTCUT,
+    shortcut: options.shortcut,
     preferredLanguages,
     transcriptionLanguage: transcriptionLanguageForModel(
       options.transcriptionLanguage,
@@ -334,6 +356,7 @@ export function settingsForModel(
     microphone: { ...(options.microphone ?? DEFAULT_MICROPHONE) },
     polishEnabled: options.polishEnabled ?? false,
     ...(options.polishModel ? { polishModel: options.polishModel } : {}),
+    ...(options.polishPrompt ? { polishPrompt: options.polishPrompt } : {}),
     voiceActivityDetection: options.voiceActivityDetection ?? true,
     longformChunking: options.longformChunking ?? true,
     model: { source: "catalog", id: modelId, path: modelPath },
@@ -353,7 +376,7 @@ export function settingsRemoteOnly(options: RemoteSettingsOptions): TranscribeSe
   return {
     version: SETTINGS_VERSION,
     backend: options.backend,
-    shortcut: options.shortcut ?? DEFAULT_SHORTCUT,
+    shortcut: options.shortcut,
     preferredLanguages,
     // The endpoint detects the language itself; "auto" keeps the stored value
     // from triggering Chinese conversion against a language that is not there.
@@ -362,6 +385,7 @@ export function settingsRemoteOnly(options: RemoteSettingsOptions): TranscribeSe
     microphone: { ...(options.microphone ?? DEFAULT_MICROPHONE) },
     polishEnabled: options.polishEnabled ?? false,
     ...(options.polishModel ? { polishModel: options.polishModel } : {}),
+    ...(options.polishPrompt ? { polishPrompt: options.polishPrompt } : {}),
     voiceActivityDetection: options.voiceActivityDetection ?? true,
     longformChunking: options.longformChunking ?? true,
   };

package/src/shortcut-core.ts

@@ -1,5 +1,3 @@
-export const DEFAULT_SHORTCUT = "ctrl+alt+z";
-
 /** Widget slot shared by the startup status and the recording meter. */
 export const STATUS_WIDGET_KEY = "pi-voice-meter";
 

package/src/shortcuts.ts

@@ -9,11 +9,8 @@ import {
   type KeybindingsManager,
   type TUI,
 } from "@earendil-works/pi-tui";
-import {
-  DEFAULT_SHORTCUT,
-  displayShortcut,
-  normalizeShortcut,
-} from "./shortcut-core.js";
+import { defaultShortcut } from "./default-shortcut.js";
+import { displayShortcut, normalizeShortcut } from "./shortcut-core.js";
 import { VoiceKeys } from "./keybindings.js";
 import { panelBorder } from "./ui-components.js";
 
@@ -48,6 +45,7 @@ export function createShortcutPicker(
   done: (shortcut: string | undefined) => void,
 ): Component {
   const keys = new VoiceKeys(keybindings);
+  const defaultKey = defaultShortcut();
   let phase: Phase = { kind: "waiting" };
   const container = new Container();
 
@@ -98,7 +96,7 @@ export function createShortcutPicker(
       container.addChild(new Spacer(1));
       container.addChild(
         new Text(
-          `${keys.hint("voice.shortcut.useDefault", `default (${displayShortcut(DEFAULT_SHORTCUT)})`)}  ${keys.hint("tui.select.cancel", "back")}`,
+          `${keys.hint("voice.shortcut.useDefault", `default (${displayShortcut(defaultKey)})`)}  ${keys.hint("tui.select.cancel", "back")}`,
           1,
           0,
         ),
@@ -132,8 +130,8 @@ export function createShortcutPicker(
       if (keys.matches(data, "voice.shortcut.useDefault")) {
         phase = {
           kind: "preview",
-          normalized: DEFAULT_SHORTCUT,
-          conflicts: findConflicts(keybindings, DEFAULT_SHORTCUT),
+          normalized: defaultKey,
+          conflicts: findConflicts(keybindings, defaultKey),
         };
         rebuild();
         tui.requestRender();

package/src/startup-shortcut.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
-import { DEFAULT_SHORTCUT, normalizeShortcut } from "./shortcut-core.js";
+import { defaultShortcut } from "./default-shortcut.js";
+import { normalizeShortcut } from "./shortcut-core.js";
 import { legacySettingsPath, settingsPath } from "./settings-path.js";
 
 function isObject(value: unknown): value is Record<string, unknown> {
@@ -12,13 +13,13 @@ export function readShortcutForRegistration(): string {
     try {
       const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
       if (!isObject(parsed) || parsed.version !== 1 || typeof parsed.shortcut !== "string") {
-        return DEFAULT_SHORTCUT;
+        return defaultShortcut();
       }
-      return normalizeShortcut(parsed.shortcut) ?? DEFAULT_SHORTCUT;
+      return normalizeShortcut(parsed.shortcut) ?? defaultShortcut();
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
-      return DEFAULT_SHORTCUT;
+      return defaultShortcut();
     }
   }
-  return DEFAULT_SHORTCUT;
+  return defaultShortcut();
 }