@drakulavich/kesha-voice-kit 1.17.1 → 1.18.1

package/README.md

@@ -11,13 +11,15 @@
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
 </p>
 
-<p align="center"><b>Open-source voice toolkit.</b> Optimized for Apple Silicon (CoreML), works on any platform (ONNX fallback).<br>A collection of small, fast, open-source audio models — packaged as CLI tools and an <a href="https://github.com/openclaw/openclaw">OpenClaw</a> skill for LLM agents.</p>
+<p align="center"><b>Open-source voice toolkit.</b> Optimized for Apple Silicon (CoreML), with ONNX fallback on supported Linux/Windows builds.<br>A collection of small, fast, open-source audio models — packaged as CLI tools and an <a href="https://github.com/openclaw/openclaw">OpenClaw</a> skill for LLM agents.</p>
 
 - **Speech-to-text** — 25 languages, ~15x faster than Whisper on Apple Silicon, ~2.5x on CPU
 - **Text-to-speech** — Kokoro (EN) + Vosk-TTS (RU) + macOS system voices, SSML preview
 - **Rust engine** — single 20MB binary, no ffmpeg, no Python, no native Node addons
 - **OpenClaw-ready** — plug into your LLM agent as a voice processing skill
 
+See [Product positioning](docs/product-positioning.md) for supported workflows, non-goals, maturity labels, and the platform matrix.
+
 <p align="center">
   <img src="./demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
 </p>
@@ -49,6 +51,32 @@ kesha audio.ogg     # transcript to stdout
 
 Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
 
+## Homebrew Install
+
+Homebrew installs the Bun-based CLI wrapper. Engine and model downloads remain
+explicit:
+
+```bash
+brew tap oven-sh/bun
+brew install drakulavich/tap/kesha-voice-kit
+kesha install
+kesha audio.ogg
+```
+
+See [Homebrew install](docs/homebrew.md) for package scope and maintainer
+validation.
+
+## Support diagnostics
+
+Kesha can collect local diagnostics without downloading models or mutating cache state:
+
+```bash
+kesha doctor --json --redact
+kesha support-bundle --output kesha-support.tar.gz
+```
+
+`support-bundle` creates a redacted `.tar.gz` archive for GitHub issues. It includes runtime, engine, cache, optional-component, Stats status, and known Kesha environment settings. It does not include audio, transcripts, model files, or the Stats database.
+
 ## Nix Install
 
 Alternative reproducible-build path on `aarch64-darwin` / `x86_64-linux`:
@@ -60,6 +88,44 @@ nix run github:drakulavich/kesha-voice-kit -- audio.ogg    # transcribe
 
 Full recipes (one-liner, profile install, engine-only, dev shell) live in [docs/nix-install.md](docs/nix-install.md).
 
+## Docker
+
+Linux x64 CLI image, published to GHCR:
+
+```bash
+docker run --rm \
+  -v kesha-cache:/cache/kesha \
+  -v "$PWD:/work" -w /work \
+  ghcr.io/drakulavich/kesha-voice-kit:latest install
+
+docker run --rm \
+  -v kesha-cache:/cache/kesha \
+  -v "$PWD:/work" -w /work \
+  ghcr.io/drakulavich/kesha-voice-kit:latest audio.ogg
+```
+
+The image keeps model downloads and the engine cache under `/cache/kesha`.
+Mount that path as a named volume so `kesha install`, TTS models, VAD, and future
+runs reuse the same cache. `compose.yml` provides the same layout:
+
+```bash
+docker compose run --rm kesha install
+docker compose run --rm kesha audio.ogg
+```
+
+## Linux Packages
+
+Stable engine releases also publish `.deb` and `.rpm` packages for Linux x64.
+They install the standalone CLI wrapper; engine and model downloads remain explicit:
+
+```bash
+kesha install
+kesha audio.ogg
+```
+
+See [Linux packages](docs/linux-packages.md) for install commands and package
+scope.
+
 ## Speech-to-text
 
 ```bash
@@ -100,7 +166,7 @@ Each segment gets a `speaker` integer (cluster ID, stable within one file). Linu
 
 ## Text-to-speech
 
-Kesha speaks back via Kokoro-82M (English) and Vosk-TTS (Russian) — voice auto-picks from the text's language:
+Kesha speaks back via Kokoro-82M (English) and Vosk-TTS (Russian) — voice auto-picks from the text's language. On darwin-arm64, Kokoro uses FluidAudio CoreML instead of ONNX:
 
 ```bash
 kesha install --tts                      # ~990MB (Kokoro + Vosk-TTS RU, opt-in)
@@ -158,7 +224,7 @@ See [BENCHMARK.md](BENCHMARK.md) for the full per-file breakdown (Russian + Engl
 | SpeechBrain ECAPA-TDNN | Audio language detection | ~86MB | [HuggingFace](https://huggingface.co/speechbrain/lang-id-voxlingua107-ecapa) |
 | Apple NLLanguageRecognizer | Text language detection | built-in | macOS system framework |
 | Silero VAD v5 (opt-in) | Voice activity detection | ~2.3MB | [snakers4/silero-vad](https://github.com/snakers4/silero-vad) |
-| Kokoro-82M / Vosk-TTS (opt-in) | Text-to-speech | ~990MB | [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) · [Vosk-TTS](https://github.com/alphacep/vosk-tts) |
+| Kokoro-82M / Vosk-TTS (opt-in) | Text-to-speech | ~990MB | [FluidAudio Kokoro](https://github.com/FluidInference/FluidAudio) on darwin-arm64; ONNX Kokoro elsewhere · [Vosk-TTS](https://github.com/alphacep/vosk-tts) |
 
 All models run through `kesha-engine` — a Rust binary using [FluidAudio](https://github.com/FluidInference/FluidAudio) (CoreML) on Apple Silicon and [ort](https://github.com/pykeio/ort) (ONNX Runtime) on other platforms.
 

package/SKILL.md

@@ -22,7 +22,7 @@ Local voice toolkit: transcribe voice messages to text, synthesize speech, detec
 ## When to use
 
 - **Voice memo arrived** (Telegram, WhatsApp, Slack, Signal .ogg/.opus/.m4a): transcribe with `kesha --json <path>` and branch on the detected language.
-- **Need to reply with audio (file playback)**: synthesize with `kesha say "<text>" > reply.wav`. Auto-routes by detected language (Kokoro-82M for English, Vosk-TTS for Russian). For other languages and ~180 more voices use `--voice macos-*` on macOS (zero model download).
+- **Need to reply with audio (file playback)**: synthesize with `kesha say "<text>" > reply.wav`. Auto-routes by detected language (Kokoro-82M for English, Vosk-TTS for Russian). On darwin-arm64, English Kokoro uses FluidAudio CoreML instead of ONNX. For other languages and ~180 more voices use `--voice macos-*` on macOS (zero model download).
 - **Need to send a voice note (Telegram, WhatsApp, Signal, Discord)**: synthesize directly into the messenger-native format with `kesha say "<text>" --format ogg-opus --out reply.ogg`. Default is mono 24 kHz @ 32 kbps — what Telegram `sendVoice` expects. No `ffmpeg` round-trip needed.
 - **Need to detect what language a file is in** before choosing a pipeline: `kesha --json audio.ogg` returns both audio-based and text-based language detection with confidence scores.
 
@@ -153,7 +153,7 @@ No system deps — English G2P is embedded (`misaki-rs`); Russian G2P is bundled
 
 **Speech-to-text (25):** Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Ukrainian.
 
-**Text-to-speech:** English (Kokoro-82M, ~70 voices), Russian (Vosk-TTS, 5 baked-in speakers — default `ru-vosk-m02`), plus any macOS system voice via `--voice macos-*`.
+**Text-to-speech:** English (Kokoro-82M; FluidAudio CoreML on darwin-arm64, ONNX elsewhere), Russian (Vosk-TTS, 5 baked-in speakers — default `ru-vosk-m02`), plus any macOS system voice via `--voice macos-*`.
 
 ## Performance
 

package/docs/product-positioning.md

@@ -0,0 +1,76 @@
+# Product positioning
+
+Kesha Voice Kit is a local-first voice toolkit for developers and agent workflows. It is built for small, scriptable jobs where a CLI can turn audio into text, text into audio, or voice messages into structured data without sending content to a hosted API.
+
+The product promise is not "one model for every audio problem." The promise is a boring, automatable local voice stack with clear platform limits, predictable install paths, and machine-readable output.
+
+## Who this is for
+
+- Developers and agent builders who need local speech-to-text for voice messages, meetings, support clips, or batch audio files.
+- OpenClaw users who want private, low-latency voice-message transcription through a CLI model route.
+- macOS users who want the fastest path on Apple Silicon through CoreML, with a CPU/ONNX fallback on Linux and Windows.
+- Automation-heavy users who prefer stdout/stderr contracts, JSON/TOON output, and shell-friendly commands over a hosted dashboard.
+- Projects that can accept explicit model downloads and local cache management in exchange for no API keys and no cloud audio upload.
+
+## Primary workflows
+
+| Workflow | Status | Command surface |
+|---|---|---|
+| Transcribe one or more audio files to plain text | Stable | `kesha audio.ogg` |
+| Transcribe to structured output for scripts or agents | Stable | `kesha --json audio.ogg`, `kesha --toon audio.ogg`, `kesha --format transcript audio.ogg` |
+| Detect likely audio/text language during transcription | Stable | `--lang`, `--verbose`, JSON/TOON language fields |
+| Skip silence in long audio | Beta | `kesha --vad meeting.m4a`, auto-on for long audio when VAD is installed |
+| Synthesize English or Russian speech locally | Beta | `kesha say "text"`, `kesha install --tts` |
+| Use macOS system voices without model downloads | Stable on macOS | `kesha say --voice macos-*` |
+| Label speakers in meeting transcripts | Preview, darwin-arm64 only | `kesha --json --vad --speakers meeting.m4a` |
+| Integrate with OpenClaw as a local voice model | Stable integration surface, user-configured route | `docs/openclaw.md` |
+| Use Raycast actions for selected-file transcription or clipboard speech | Beta, macOS only | `raycast/` extension |
+| Install through Nix instead of Bun/npm | Beta, selected systems | `docs/nix-install.md` |
+
+## Non-goals
+
+- Hosted SaaS transcription, dashboards, accounts, billing, or team management.
+- Streaming phone-call transcription or real-time conversation infrastructure.
+- Speaker identity across files. Diarization emits per-file cluster IDs, not names or persistent voice profiles.
+- Full SSML coverage. Kesha supports a practical subset for current TTS engines; unsupported tags should fail or warn clearly.
+- Universal TTS across all 25 STT languages. TTS is intentionally scoped to English, Russian, and macOS system voices.
+- Model training, fine-tuning, or benchmark leadership on every dataset.
+- Browser/mobile SDKs. The supported product surface is CLI-first, with thin integrations around it.
+
+## Feature maturity
+
+| Feature | Maturity | Notes |
+|---|---|---|
+| Core STT CLI | Stable | Main product path; stdout transcript, stderr progress/errors. |
+| JSON / TOON / transcript output formats | Stable | Intended for scripts, agents, and downstream tooling. |
+| Audio language detection | Stable | Used for warnings and structured metadata. |
+| VAD preprocessing | Beta | Useful for long or silence-heavy audio; short voice messages stay on the fast path. |
+| English/Russian TTS | Beta | Requires `kesha install --tts`; model cache and first-run cost are expected. |
+| macOS AVSpeech voices | Stable on macOS | Zero-install system voices; quality is OS voice quality, not neural TTS. |
+| SSML subset | Preview | `<prosody rate>`, Russian stress markers, and IPA support are engine-specific. |
+| Speaker diarization | Preview | darwin-arm64 only; cluster IDs are stable within one file only. |
+| Raycast extension | Beta | Convenience UI over the CLI; macOS-only. |
+| OpenClaw plugin | Stable integration surface | Discovery is packaged; actual audio route remains explicit user config. |
+| Nix flake | Beta | Reproducible alternate install path for selected systems; Bun/npm remains canonical. |
+
+## Platform matrix
+
+| Capability | macOS arm64 | macOS x64 | Linux x64 | Windows x64 | Nix path |
+|---|---|---|---|---|---|
+| STT | Supported, CoreML path | Not shipped | Supported, ONNX CPU path | Supported, ONNX CPU path | `aarch64-darwin`, `x86_64-linux` |
+| Audio language detection | Supported | Not shipped | Supported | Supported | Supported where the flake builds |
+| VAD | Supported with `kesha install --vad` | Not shipped | Supported with `kesha install --vad` | Supported with `kesha install --vad` | Supported where the engine path includes VAD assets |
+| TTS: English Kokoro | Supported, FluidAudio/CoreML in release builds | Not shipped | Supported, ONNX path | Supported, ONNX path | Supported except where noted in `docs/nix-install.md` |
+| TTS: Russian Vosk-TTS | Supported | Not shipped | Supported | Supported | Supported except where noted in `docs/nix-install.md` |
+| macOS system voices | Supported | Not shipped | Not applicable | Not applicable | Supported on `aarch64-darwin` |
+| Speaker diarization | Preview, darwin-arm64 only | Not supported | Not supported | Not supported | Not wired into the Nix build yet |
+| Raycast extension | Supported | Not shipped | Not applicable | Not applicable | Not applicable |
+| OpenClaw integration | Supported through CLI route | Not shipped | Supported through CLI route | Supported through CLI route | Use the installed `kesha` command from the chosen path |
+
+`macOS x64` means Intel Macs. Kesha does not currently publish a `darwin-x64` engine binary, so Intel Macs are intentionally marked as not shipped rather than implied to use the ONNX fallback.
+
+## When to choose something else
+
+Use a hosted transcription provider when you need managed uptime, centralized audit logs, team permissions, or no local model cache. Use a streaming ASR stack when partial transcripts during a live call matter more than local-first batch reliability. Use a domain-specific ASR model when medical, legal, or noisy industrial audio quality is the primary requirement.
+
+Kesha is strongest when the input is already a file, the caller is an engineer or agent, and the desired output is a transcript, JSON object, TOON payload, or WAV file that can continue through a local pipeline.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.17.1",
+  "version": "1.18.1",
   "description": "Open-source voice toolkit. Speech-to-text (25 langs, ~19x faster than Whisper on Apple Silicon, ONNX fallback on CPU), text-to-speech (Kokoro + Vosk-TTS + ~180 macOS system voices, SSML), voice-activity detection, language detection (107 langs). Rust engine, OpenClaw skill.",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "tsconfig.json",
     "openclaw.plugin.json",
     "openclaw-plugin.cjs",
+    "docs/product-positioning.md",
     "SKILL.md",
     "scripts/postinstall.cjs",
     "LICENSE",
@@ -30,15 +31,18 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.17.0"
+    "version": "1.18.0"
   },
   "scripts": {
     "test": "bun test",
     "test:unit": "bun test tests/unit/",
+    "test:cli-fast": "bun test tests/unit/ tests/integration/cli-contracts.test.ts tests/integration/e2e-cli.test.ts tests/integration/say.test.ts",
     "test:integration": "bun test tests/integration/",
     "lint": "bunx tsc --noEmit",
     "lint:tsgo": "bunx tsgo --noEmit",
+    "check": "bun run lint && bun run check:versions && bun run test:cli-fast",
     "check:workflows": "bun .github/scripts/check-workflows.ts",
+    "check:release-manifest": "bun .github/scripts/release-manifest.mjs --check",
     "check:versions": "bun .github/scripts/check-versions.ts",
     "postinstall": "node scripts/postinstall.cjs"
   },

package/src/cli/dispatch.ts

@@ -2,13 +2,15 @@ import { runMain } from "citty";
 import { existsSync } from "fs";
 import { log } from "../log";
 import { suggestCommand } from "../suggest-command";
+import { doctorCommand } from "./doctor";
 import { installCommand } from "./install";
 import { sayCommand } from "./say";
 import { statsCommand } from "./stats";
 import { statusCommand } from "./status";
+import { supportBundleCommand } from "./support-bundle";
 import { mainCommand } from "./main";
 
-const SUBCOMMANDS = ["install", "status", "say", "stats"];
+const SUBCOMMANDS = ["doctor", "install", "status", "say", "stats", "support-bundle"];
 
 function isPathLike(arg: string): boolean {
   return arg.includes(".") || arg.includes("/") || existsSync(arg);
@@ -17,6 +19,11 @@ function isPathLike(arg: string): boolean {
 export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
   const [firstArg, ...restArgs] = rawArgs;
 
+  if (firstArg === "doctor") {
+    await runMain(doctorCommand, { rawArgs: restArgs });
+    return;
+  }
+
   if (firstArg === "install") {
     await runMain(installCommand, { rawArgs: restArgs });
     return;
@@ -37,6 +44,11 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
     return;
   }
 
+  if (firstArg === "support-bundle") {
+    await runMain(supportBundleCommand, { rawArgs: restArgs });
+    return;
+  }
+
   // Check for unknown subcommands (non-flag, non-file-path args).
   // Extensionless existing files remain valid transcription inputs; missing
   // bare tokens are more likely command typos and should not start the engine.

package/src/cli/doctor.ts

@@ -0,0 +1,35 @@
+import { defineCommand } from "citty";
+import { collectDoctorReport, formatDoctorReport } from "../doctor";
+import { log } from "../log";
+
+interface DoctorCommandArgs {
+  json: boolean;
+  redact: boolean;
+}
+
+export const doctorCommand = defineCommand({
+  meta: {
+    name: "doctor",
+    description: "Collect support diagnostics without changing local state",
+  },
+  args: {
+    json: {
+      type: "boolean",
+      description: "Output diagnostics as JSON",
+      default: false,
+    },
+    redact: {
+      type: "boolean",
+      description: "Redact secrets and user-home paths from diagnostic output",
+      default: false,
+    },
+  },
+  async run({ args }: { args: DoctorCommandArgs }) {
+    const report = await collectDoctorReport({ redact: args.redact });
+    if (args.json) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+    log.info(formatDoctorReport(report));
+  },
+});

package/src/cli/install.ts

@@ -1,8 +1,10 @@
 import { defineCommand } from "citty";
 import { downloadEngine } from "../engine-install";
 import { getEngineBinPath } from "../engine";
+import { renderInstallPlan } from "../install-plan";
 import { maybeAskForStar } from "../star";
 import { log } from "../log";
+import { packageVersion } from "../package-info";
 
 interface InstallCommandArgs {
   coreml: boolean;
@@ -11,10 +13,9 @@ interface InstallCommandArgs {
   tts: boolean;
   vad: boolean;
   diarize: boolean;
+  plan: boolean;
 }
 
-const pkg = await Bun.file(new URL("../../package.json", import.meta.url)).json();
-
 function resolveBackendFlag(coreml: boolean, onnx: boolean): string | undefined {
   if (coreml && onnx) {
     log.error('Choose only one backend: "--coreml" or "--onnx".');
@@ -31,7 +32,12 @@ async function performInstall(
   tts = false,
   vad = false,
   diarize = false,
+  plan = false,
 ) {
+  if (plan) {
+    log.info(await renderInstallPlan({ noCache, backend, tts, vad, diarize }));
+    return;
+  }
   if (diarize && !(process.platform === "darwin" && process.arch === "arm64")) {
     log.error(
       "--diarize is currently darwin-arm64 only " +
@@ -41,8 +47,7 @@ async function performInstall(
   }
   try {
     await downloadEngine(noCache, backend, { tts, vad, diarize });
-    const currentVersion = typeof pkg.version === "string" ? pkg.version : null;
-    await maybeAskForStar(getEngineBinPath(), currentVersion, log);
+    await maybeAskForStar(getEngineBinPath(), packageVersion, log);
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);
     log.error(message);
@@ -71,6 +76,11 @@ export const installCommand = defineCommand({
       description: "Re-download even if cached",
       default: false,
     },
+    plan: {
+      type: "boolean",
+      description: "Show download, disk, and warm-up plan without changing local state",
+      default: false,
+    },
     tts: {
       type: "boolean",
       description: "Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)",
@@ -89,6 +99,6 @@ export const installCommand = defineCommand({
   },
   async run({ args }: { args: InstallCommandArgs }) {
     const backend = resolveBackendFlag(args.coreml, args.onnx);
-    await performInstall(args["no-cache"], backend, args.tts, args.vad, args.diarize);
+    await performInstall(args["no-cache"], backend, args.tts, args.vad, args.diarize, args.plan);
   },
 });

package/src/cli/main.ts

@@ -5,18 +5,17 @@ import { transcribeWithSegments } from "../transcribe";
 import { detectAudioLanguageEngine, detectTextLanguageEngine } from "../engine";
 import type { LangDetectResult } from "../engine";
 import { log } from "../log";
-import type { TranscribeResult } from "../types";
+import type { TranscribeErrorRecord, TranscribeResult } from "../types";
 import {
   formatJsonOutput,
   formatTextOutput,
   formatTranscriptOutput,
   formatVerboseOutput,
 } from "../format";
+import { packageVersion } from "../package-info";
 import { formatToonOutput } from "../toon";
 import { artifactFromFile, createStatsRecorder } from "../stats";
 
-const pkg = await Bun.file(new URL("../../package.json", import.meta.url)).json();
-
 interface MainCommandArgs {
   _: string[];
   json: boolean;
@@ -25,8 +24,11 @@ interface MainCommandArgs {
   debug: boolean;
   vad: boolean;
   "no-vad": boolean;
+  noVad?: boolean;
+  no_vad?: boolean;
   timestamps: boolean;
   speakers: boolean;
+  "include-errors": boolean;
   format?: string;
   lang?: string;
 }
@@ -107,15 +109,17 @@ export function checkLanguageMismatch(expected: string | undefined, detected: st
 export const mainCommand = defineCommand({
   meta: {
     name: "kesha",
-    version: pkg.version,
+    version: packageVersion,
     description:
       "Kesha Voice Kit — open-source voice toolkit for Apple Silicon.\n" +
       "\n" +
       "Commands:\n" +
+      "  doctor     Collect support diagnostics.\n" +
       "  install    Download engine and models.\n" +
       "  status     Inspect installed backend.\n" +
       "  say        Synthesize speech from text.\n" +
-      "  stats      Manage local anonymous performance stats.",
+      "  stats      Manage local anonymous performance stats.\n" +
+      "  support-bundle  Create a redacted diagnostics archive.",
   },
   args: {
     json: {
@@ -138,6 +142,11 @@ export const mainCommand = defineCommand({
       description: "Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).",
       default: false,
     },
+    "include-errors": {
+      type: "boolean",
+      description: "With --json, output { results, errors } so scripts can read per-file failures without parsing stderr",
+      default: false,
+    },
     verbose: {
       type: "boolean",
       description: "Show language detection details",
@@ -167,7 +176,7 @@ export const mainCommand = defineCommand({
       default: false,
     },
   },
-  async run({ args }: { args: MainCommandArgs }) {
+  async run({ args, rawArgs }: { args: MainCommandArgs; rawArgs: string[] }) {
     if (args.debug) log.debugEnabled = true;
     const files = args._;
 
@@ -187,7 +196,12 @@ export const mainCommand = defineCommand({
     }
     const { wantsJson, wantsToon, wantsTranscript } = fmt;
 
-    if (args.vad && args["no-vad"]) {
+    // citty treats --no-vad as the negated form of --vad, so read rawArgs
+    // to distinguish "off" from the default auto mode and to catch both flags.
+    const vad = rawArgs.includes("--vad") || Boolean(args.vad);
+    const noVad = rawArgs.includes("--no-vad") || Boolean(args["no-vad"] ?? args.noVad ?? args.no_vad);
+
+    if (vad && noVad) {
       log.error("--vad and --no-vad are mutually exclusive.");
       process.exit(2);
     }
@@ -199,21 +213,28 @@ export const mainCommand = defineCommand({
       log.error("--speakers requires --json, --toon, or --format {json,toon}.");
       process.exit(2);
     }
-    const vadMode = args.vad ? "on" : args["no-vad"] ? "off" : "auto";
+    if (args["include-errors"] && !wantsJson) {
+      log.error("--include-errors requires --json or --format json.");
+      process.exit(2);
+    }
+    const vadMode = vad ? "on" : noVad ? "off" : "auto";
 
     if (files.length === 0) {
       log.info(
         "Usage: kesha <audio_file> [audio_file ...]\n" +
+          "       kesha doctor [--json] [--redact]\n" +
           "       kesha install [--no-cache]\n" +
           "       kesha status\n" +
           "       kesha say <text>\n" +
-          "       kesha stats [enable|disable|status|week|errors]",
+          "       kesha stats [enable|disable|status|week|errors]\n" +
+          "       kesha support-bundle [--output path.tar.gz]",
       );
       process.exit(1);
     }
 
     let hasError = false;
     const results: TranscribeResult[] = [];
+    const errors: TranscribeErrorRecord[] = [];
     const stats = createStatsRecorder("transcribe");
 
     const wantsLangId = !!(args.lang || args.verbose || wantsJson || wantsToon || wantsTranscript);
@@ -223,6 +244,7 @@ export const mainCommand = defineCommand({
       if (!existsSync(file)) {
         hasError = true;
         stats.recordError("input", new Error("File not found"), "file_not_found");
+        errors.push({ file, code: "file_not_found", message: "File not found" });
         log.error(`${file}: File not found`);
         continue;
       }
@@ -290,12 +312,13 @@ export const mainCommand = defineCommand({
         hasError = true;
         stats.recordError("transcribe", err);
         const message = err instanceof Error ? err.message : String(err);
+        errors.push({ file, code: "transcribe_failed", message });
         log.error(`${file}: ${message}`);
       }
     }
 
     if (wantsJson) {
-      process.stdout.write(formatJsonOutput(results));
+      process.stdout.write(formatJsonOutput(results, args["include-errors"] ? errors : undefined));
     } else if (wantsToon) {
       process.stdout.write(formatToonOutput(results));
     } else if (wantsTranscript) {

package/src/cli/say.ts

@@ -29,6 +29,55 @@ async function resolveText(inline: string | undefined): Promise<string> {
   return new TextDecoder().decode(merged).trim();
 }
 
+export function shouldRejectMissingSayText(
+  inlineText: string | undefined,
+  stdinIsTty: boolean | undefined,
+): boolean {
+  return (inlineText === undefined || inlineText.length === 0) && stdinIsTty === true;
+}
+
+function parseFiniteNumberFlag(name: string, value: unknown): number | undefined {
+  if (value === undefined || value === null || value === false) return undefined;
+  const raw = String(value).trim();
+  const parsed = Number(raw);
+  if (raw === "" || !Number.isFinite(parsed)) {
+    log.error(`${name} must be a finite number.`);
+    process.exit(2);
+  }
+  return parsed;
+}
+
+function parseRateFlag(value: unknown): number | undefined {
+  const rate = parseFiniteNumberFlag("--rate", value);
+  if (rate === undefined) return undefined;
+  if (rate < 0.5 || rate > 2.0) {
+    log.error("--rate must be between 0.5 and 2.0.");
+    process.exit(2);
+  }
+  return rate;
+}
+
+function parseBitrateFlag(value: unknown): number | undefined {
+  const bitrate = parseFiniteNumberFlag("--bitrate", value);
+  if (bitrate === undefined) return undefined;
+  if (!Number.isInteger(bitrate) || bitrate <= 0) {
+    log.error("--bitrate must be a positive integer.");
+    process.exit(2);
+  }
+  return bitrate;
+}
+
+function parseSampleRateFlag(value: unknown): number | undefined {
+  const sampleRate = parseFiniteNumberFlag("--sample-rate", value);
+  if (sampleRate === undefined) return undefined;
+  const supported = [8000, 12000, 16000, 24000, 48000];
+  if (!Number.isInteger(sampleRate) || !supported.includes(sampleRate)) {
+    log.error("--sample-rate must be one of 8000, 12000, 16000, 24000, 48000.");
+    process.exit(2);
+  }
+  return sampleRate;
+}
+
 export const sayCommand = defineCommand({
   meta: {
     name: "say",
@@ -88,11 +137,6 @@ export const sayCommand = defineCommand({
       process.exit(await proc.exited);
     }
 
-    const inlineText = typeof args.text === "string" ? args.text : undefined;
-    const text = await resolveText(inlineText);
-    const explicitVoice = typeof args.voice === "string" ? args.voice : undefined;
-    const voice = explicitVoice ?? (await autoRouteVoice(text));
-
     // Validate --format up front so we surface a clear error before spawning
     // the engine subprocess. The engine repeats the check authoritatively, but
     // catching it here gives the user a faster failure mode in scripts.
@@ -109,8 +153,12 @@ export const sayCommand = defineCommand({
       }
     }
 
+    const rate = parseRateFlag(args.rate);
+    const bitrate = parseBitrateFlag(args.bitrate);
+    const sampleRate = parseSampleRateFlag(args["sample-rate"]);
+
     // Reject --bitrate / --sample-rate with WAV up front to surface the error fast.
-    const hasOpusOnlyFlag = Boolean(args.bitrate) || Boolean(args["sample-rate"]);
+    const hasOpusOnlyFlag = bitrate !== undefined || sampleRate !== undefined;
     if (hasOpusOnlyFlag) {
       const outExt = typeof args.out === "string"
         ? args.out.split(".").pop()?.toLowerCase()
@@ -122,16 +170,26 @@ export const sayCommand = defineCommand({
       }
     }
 
+    const inlineText = typeof args.text === "string" ? args.text : undefined;
+    const stdinIsTty = (process.stdin as { isTTY?: boolean }).isTTY;
+    if (shouldRejectMissingSayText(inlineText, stdinIsTty)) {
+      log.error("kesha say requires text or piped stdin. Usage: kesha say <text>");
+      process.exit(2);
+    }
+    const text = await resolveText(inlineText);
+    const explicitVoice = typeof args.voice === "string" ? args.voice : undefined;
+    const voice = explicitVoice ?? (await autoRouteVoice(text));
+
     const opts = {
       text,
       voice,
       lang: typeof args.lang === "string" ? args.lang : undefined,
       out: typeof args.out === "string" ? args.out : undefined,
-      rate: args.rate ? Number(args.rate) : undefined,
+      rate,
       ssml: Boolean(args.ssml),
       format,
-      bitrate: args.bitrate ? Number(args.bitrate) : undefined,
-      sampleRate: args["sample-rate"] ? Number(args["sample-rate"]) : undefined,
+      bitrate,
+      sampleRate,
       noExpandAbbrev: Boolean(args["no-expand-abbrev"]),
     };
     const stats = createStatsRecorder("say");

package/src/cli/status.ts

@@ -1,12 +1,23 @@
 import { defineCommand } from "citty";
 import { showStatus } from "../status";
 
+interface StatusCommandArgs {
+  disk: boolean;
+}
+
 export const statusCommand = defineCommand({
   meta: {
     name: "status",
     description: "Show backend installation status",
   },
-  async run() {
-    await showStatus();
+  args: {
+    disk: {
+      type: "boolean",
+      description: "Include recursive cache disk usage",
+      default: false,
+    },
+  },
+  async run({ args }: { args: StatusCommandArgs }) {
+    await showStatus({ disk: args.disk });
   },
 });