@drakulavich/kesha-voice-kit 1.30.0 → 2.0.0

package/README.md

@@ -19,7 +19,7 @@
 - **Small Rust engine** — single ~65MB binary, no ffmpeg, no Python, no native Node addons
 
 <p align="center">
-  <img src="https://github.com/drakulavich/kesha-voice-kit/raw/main/demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
+  <img src="https://github.com/drakulavich/kesha-voice-kit/raw/main/docs/assets/demo.webp" alt="kesha demo: an English voice message transcribed, a Russian one as JSON with automatic language detection, then text-to-speech into a wav" width="800">
 </p>
 
 ## Quick Start
@@ -138,10 +138,10 @@ Full per-file breakdown (Russian + English): [BENCHMARK.md](BENCHMARK.md). The C
 
 All of these install the Bun CLI wrapper; engine + models still download explicitly via `kesha install`. (Nix is the exception — it currently builds only the engine from source; see below.)
 
-- **Homebrew** — `brew install drakulavich/tap/kesha-voice-kit` · [docs/homebrew.md](docs/homebrew.md)
-- **Linux packages** (`.deb`/`.rpm`, x64) — published on CLI releases, see [docs/linux-packages.md](docs/linux-packages.md)
+- **Homebrew** — `brew install drakulavich/tap/kesha-voice-kit` · [docs/distribution.md](docs/distribution.md#homebrew)
+- **Linux packages** (`.deb`/`.rpm`, x64) — published on stable releases, see [docs/distribution.md](docs/distribution.md#linux-packages)
 - **Docker** (GHCR image) — [docs/docker.md](docs/docker.md)
-- **Nix** (`aarch64-darwin` / `x86_64-linux`) — builds the engine from source (`nix build github:drakulavich/kesha-voice-kit#kesha-engine`). The full `kesha` CLI via `nix run` / `nix profile install` is **not yet available** — it needs a maintainer with Nix to populate a build hash ([#946](https://github.com/drakulavich/kesha-voice-kit/issues/946)). · [docs/nix-install.md](docs/nix-install.md)
+- **Nix** (`aarch64-darwin` / `x86_64-linux`) — builds the engine from source (`nix build github:drakulavich/kesha-voice-kit#kesha-engine`). The full `kesha` CLI via `nix run` / `nix profile install` is **not yet available** — it needs a maintainer with Nix to populate a build hash ([#946](https://github.com/drakulavich/kesha-voice-kit/issues/946)). · [docs/distribution.md](docs/distribution.md#nix)
 - **Shell completions + manpage** — `kesha completions bash|zsh|fish` and `kesha manpage` print the packaged files to install wherever your shell expects them.
 
 ## Integrations
@@ -158,7 +158,7 @@ All of these install the Bun CLI wrapper; engine + models still download explici
 - [Use cases](docs/use-cases.md) — copy-paste recipes (transcribe a meeting, speak from OpenClaw, run offline, move the cache).
 - [Product positioning](docs/product-positioning.md) — supported workflows, non-goals, maturity labels, platform matrix.
 - [Changelog](CHANGELOG.md) — every release, with the behaviour changes spelled out.
-- **Diagnostics:** `kesha doctor`, `kesha support-bundle` (redacted `.tar.gz` for issues), and `kesha logs` produce local, content-free diagnostics — see [docs/diagnostic-logs.md](docs/diagnostic-logs.md). Every failure prints a stable `error [CODE]: …` line and a documented [process exit code](docs/errors.md#process-exit-codes).
+- **Diagnostics:** `kesha doctor`, `kesha support-bundle` (redacted `.tar.gz` for issues), and `kesha logs` produce local, content-free diagnostics — see [docs/diagnostic-logs.md](docs/diagnostic-logs.md). One variable, `KESHA_HOME`, moves everything Kesha writes (models, logs, stats) into a directory of your choice — see [where Kesha keeps its files](docs/diagnostic-logs.md#where-kesha-keeps-its-files). Every failure prints a stable `error [CODE]: …` line and a documented [process exit code](docs/errors.md#process-exit-codes).
 - **Scripting & CI:** `--json` (or `--toon`) for machine-readable output, `--include-errors` (with either) to get per-file failures on stdout alongside the results, `--quiet`/`-q` to silence progress, and `--no-color` (or `NO_COLOR=1`) for plain logs. Colors switch off automatically when `CI=true`.
 - **Privacy / Local Stats:** Stats are **off by default** and fully local. Opt in with `kesha stats enable` to record content-free operational metrics in a local SQLite database — never networked, never storing audio, transcripts, text, or paths. Full commands & lifecycle: [docs/local-stats.md](docs/local-stats.md).
 

package/SKILL.md

@@ -236,7 +236,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 (9):** English (Kokoro-82M; FluidAudio CoreML on darwin-arm64, ONNX elsewhere), Russian (Vosk-TTS, 5 baked-in speakers — default `ru-vosk-m02`), Spanish, French, Italian, Portuguese (Kokoro — CharsiuG2P on ONNX builds, FluidAudio G2P on darwin-arm64), plus Hindi, Japanese, Chinese (Kokoro, darwin-arm64 only). `hi`/`ja` accept romanized Latin input only; native Devanagari and kana/kanji are rejected with `E_SCRIPT_UNSUPPORTED` — see [#492](https://github.com/drakulavich/kesha-voice-kit/issues/492). Any macOS system voice is also available via `--voice macos-*`.
+**Text-to-speech (9):** English (Kokoro-82M; FluidAudio CoreML on darwin-arm64, ONNX elsewhere), Russian (Vosk-TTS, 5 baked-in speakers — default `ru-vosk-m02`), Spanish, French, Italian, Portuguese (Kokoro — CharsiuG2P on ONNX builds, FluidAudio G2P on darwin-arm64), plus Hindi, Japanese, Chinese (Kokoro, darwin-arm64 only). The `hi`/`ja` Kokoro voices read romanized Latin input only; on macOS, text that is mostly Devanagari or kana/kanji with no `--voice` routes to an installed AVSpeech voice (Lekha for `hi-IN`, Otoya for `ja-JP`), while an explicit `--voice hi-*`/`ja-*` refuses them with `E_SCRIPT_UNSUPPORTED`; non-macOS builds have no `hi`/`ja` voices, so the text is refused by the default English voice (`E_SCRIPT_UNSUPPORTED`) and `--voice hi-*`/`ja-*` is `E_VOICE_UNKNOWN` — see [#492](https://github.com/drakulavich/kesha-voice-kit/issues/492). Any macOS system voice is also available via `--voice macos-*`.
 
 ## Performance
 

package/completions/kesha.bash

@@ -38,4 +38,4 @@ _kesha_completion() {
   fi
 }
 
-complete -F _kesha_completion kesha
+complete -o default -F _kesha_completion kesha

package/completions/kesha.fish

@@ -1,5 +1,4 @@
 # fish completion for kesha.
-complete -c kesha -f
 complete -c kesha -n '__fish_use_subcommand' -a 'completions' -d 'Print shell completion script for bash, zsh, or fish'
 complete -c kesha -n '__fish_use_subcommand' -a 'doctor' -d 'Collect support diagnostics without changing local state'
 complete -c kesha -n '__fish_use_subcommand' -a 'init' -d 'Interactive setup guide for Kesha features'

package/completions/kesha.zsh

@@ -40,6 +40,7 @@ _kesha() {
       '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]'
     else
       _describe -t commands 'kesha command' commands
+      _files
     fi
     return
   fi
@@ -155,7 +156,8 @@ _kesha() {
       '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
       '--no-vad[Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers]' \
       '--quiet[Suppress progress output; print only results and errors]' \
-      '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]'
+      '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]' \
+      '*:audio file:_files'
       ;;
   esac
 }

package/docs/diagnostic-logs.md

@@ -43,9 +43,11 @@ stage names, exit codes, duration numbers, and stable error codes.
 
 When enabled, `kesha install`, `kesha <audio>`, and `kesha say` record command
 lifecycle events such as `command.start`, `input.audio`, `input.missing`,
-`engine.exit`, and `command.finish`. These events use only counts, booleans,
-format extensions, duration milliseconds, and bucket labels. In the default
-`retain-on-failure` mode, successful runs still leave no log file behind.
+`engine.exit`, `engine.debug` (the Engine's own `KESHA_DEBUG` timeline, carrying
+its event name and typed fields but never its message text), and `command.finish`.
+These events use only counts, booleans, format extensions, duration milliseconds,
+and bucket labels. In the default `retain-on-failure` mode, successful runs still
+leave no log file behind.
 
 Diagnostic logs must not store:
 
@@ -75,6 +77,37 @@ Set `KESHA_LOG_DIR` to override the directory. The active file is
 `kesha.ndjson`; rotated files are named `kesha.1.ndjson`, `kesha.2.ndjson`, and
 so on.
 
+## Where Kesha keeps its files
+
+Kesha writes to four places. Each resolves by the same rule: its own variable
+when set, otherwise the path under `KESHA_HOME` when that is set, otherwise the
+platform default. `KESHA_HOME` uses one layout on every platform, so a test run,
+a CI job or a second profile needs exactly one variable to leave your real
+models, logs and Stats untouched. Nothing is moved when you set it: a fresh
+`KESHA_HOME` starts with an empty cache, and `kesha install` fills it. Two roots FluidAudio owns stay outside it on darwin-arm64: the Kokoro ANE bundles and voice packs under `~/.cache/fluidaudio`, and its Silero VAD copy under `~/Library/Application Support/FluidAudio`; `status --disk` reports both as external roots, and `kesha install --tts` stages into the first regardless of `KESHA_HOME`.
+
+| What | Default (macOS / Windows / Linux) | Under `KESHA_HOME` | Own variable |
+|---|---|---|---|
+| Model cache: engine, models, `recordings/` | `~/.cache/kesha` everywhere | `<home>/cache` | `KESHA_CACHE_DIR` |
+| Diagnostic log directory | `~/Library/Logs/kesha` / `%LOCALAPPDATA%\kesha\logs` / `$XDG_STATE_HOME/kesha/logs` | `<home>/logs` | `KESHA_LOG_DIR` |
+| Stats DB | `~/Library/Application Support/kesha/stats.sqlite` / `%APPDATA%\kesha\stats.sqlite` / `$XDG_DATA_HOME/kesha/stats.sqlite` | `<home>/stats.sqlite` | `KESHA_STATS_DB` |
+| MCP audio (`kesha mcp` synthesis output) | `<tmpdir>/kesha-mcp` | `<home>/mcp-audio` | none |
+
+`kesha status --json` and `kesha doctor --json` report every path together with
+the rule that decided it (`default`, `KESHA_HOME`, or the variable name), so an
+isolated run can be verified from one command:
+
+```bash
+KESHA_HOME=/tmp/kesha-ci kesha status --json | jq .paths
+```
+
+An empty variable counts as unset; a relative path is resolved against the
+working directory when the command starts. The engine itself reads only
+`KESHA_CACHE_DIR`, so the CLI hands it the resolved cache root under that name
+whenever `KESHA_HOME` decided it. FluidAudio's own Silero VAD copy under
+`~/Library/Application Support/FluidAudio` is placed by FluidAudio and stays
+outside `KESHA_HOME`; `kesha status --disk` lists it as an external root.
+
 The first implementation rotates at 10 MB and keeps 5 rotated files. `kesha logs
 reset` deletes Kesha log files but preserves the selected mode.
 

package/docs/product-positioning.md

@@ -27,7 +27,7 @@ The product promise is not "one model for every audio problem." The promise is a
 | Integrate with OpenClaw as a local voice model | Stable integration surface, user-configured route | `docs/openclaw.md` |
 | Integrate with Hermes Agent as local STT/TTS commands | Stable CLI surface, user-configured route | `docs/hermes.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` |
+| Install through Nix instead of Bun/npm | Beta, selected systems | `docs/distribution.md#nix` |
 
 ## Non-goals
 
@@ -63,8 +63,8 @@ The product promise is not "one model for every audio problem." The promise is a
 | 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: Kokoro (`en` `es` `fr` `it` `pt`) | 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` |
+| TTS: Kokoro (`en` `es` `fr` `it` `pt`) | Supported, FluidAudio/CoreML in release builds | Not shipped | Supported, ONNX path | Supported, ONNX path | Supported except where noted in `docs/distribution.md#nix` |
+| TTS: Russian Vosk-TTS | Supported | Not shipped | Supported | Supported | Supported except where noted in `docs/distribution.md#nix` |
 | TTS: Kokoro (`hi` `ja` `zh`) | Supported, darwin-arm64 only | Not shipped | Not supported | Not supported | `aarch64-darwin` only |
 | 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 |

package/model-plan.json

@@ -34,6 +34,136 @@
     { "relPath": "models/vosk-ru/bert/model.onnx", "sizeBytes": 654361598 },
     { "relPath": "models/vosk-ru/bert/vocab.txt", "sizeBytes": 1780720 }
   ],
+  "aneEn": [
+    { "relPath": "KokoroAlbert.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroAlbert.mlmodelc/coremldata.bin", "sizeBytes": 433 },
+    { "relPath": "KokoroAlbert.mlmodelc/metadata.json", "sizeBytes": 2480 },
+    { "relPath": "KokoroAlbert.mlmodelc/model.mil", "sizeBytes": 101485 },
+    { "relPath": "KokoroAlbert.mlmodelc/weights/weight.bin", "sizeBytes": 5718848 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/coremldata.bin", "sizeBytes": 556 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/metadata.json", "sizeBytes": 4171 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/model.mil", "sizeBytes": 60047 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/weights/weight.bin", "sizeBytes": 13806464 },
+    { "relPath": "KokoroAlignment.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroAlignment.mlmodelc/coremldata.bin", "sizeBytes": 484 },
+    { "relPath": "KokoroAlignment.mlmodelc/metadata.json", "sizeBytes": 3021 },
+    { "relPath": "KokoroAlignment.mlmodelc/model.mil", "sizeBytes": 8194 },
+    { "relPath": "KokoroAlignment.mlmodelc/weights/weight.bin", "sizeBytes": 4128 },
+    { "relPath": "KokoroProsody.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroProsody.mlmodelc/coremldata.bin", "sizeBytes": 421 },
+    { "relPath": "KokoroProsody.mlmodelc/metadata.json", "sizeBytes": 2721 },
+    { "relPath": "KokoroProsody.mlmodelc/model.mil", "sizeBytes": 79705 },
+    { "relPath": "KokoroProsody.mlmodelc/weights/weight.bin", "sizeBytes": 8454272 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/coremldata.bin", "sizeBytes": 440 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/metadata.json", "sizeBytes": 3020 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/model.mil", "sizeBytes": 93152 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/weights/weight.bin", "sizeBytes": 4580160 },
+    { "relPath": "KokoroVocoder.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroVocoder.mlmodelc/coremldata.bin", "sizeBytes": 626 },
+    { "relPath": "KokoroVocoder.mlmodelc/metadata.json", "sizeBytes": 4331 },
+    { "relPath": "KokoroVocoder.mlmodelc/model.mil", "sizeBytes": 309000 },
+    { "relPath": "KokoroVocoder.mlmodelc/weights/weight.bin", "sizeBytes": 48889920 },
+    { "relPath": "KokoroTail_v2.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroTail_v2.mlmodelc/coremldata.bin", "sizeBytes": 392 },
+    { "relPath": "KokoroTail_v2.mlmodelc/metadata.json", "sizeBytes": 1872 },
+    { "relPath": "KokoroTail_v2.mlmodelc/model.mil", "sizeBytes": 7014 },
+    { "relPath": "KokoroTail_v2.mlmodelc/weights/weight.bin", "sizeBytes": 81088 },
+    { "relPath": "vocab.json", "sizeBytes": 1416 },
+    { "relPath": "af_heart.bin", "sizeBytes": 522240 }
+  ],
+  "kokoroG2p": [
+    { "relPath": "G2PEncoder.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "G2PEncoder.mlmodelc/coremldata.bin", "sizeBytes": 398 },
+    { "relPath": "G2PEncoder.mlmodelc/metadata.json", "sizeBytes": 2034 },
+    { "relPath": "G2PEncoder.mlmodelc/model.mil", "sizeBytes": 20392 },
+    { "relPath": "G2PEncoder.mlmodelc/weights/weight.bin", "sizeBytes": 694592 },
+    { "relPath": "G2PDecoder.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "G2PDecoder.mlmodelc/coremldata.bin", "sizeBytes": 545 },
+    { "relPath": "G2PDecoder.mlmodelc/metadata.json", "sizeBytes": 3064 },
+    { "relPath": "G2PDecoder.mlmodelc/model.mil", "sizeBytes": 19737 },
+    { "relPath": "G2PDecoder.mlmodelc/weights/weight.bin", "sizeBytes": 828030 },
+    { "relPath": "g2p_vocab.json", "sizeBytes": 1665 },
+    { "relPath": "us_lexicon_cache.json", "sizeBytes": 10444631 }
+  ],
+  "aneVoices": [
+    { "relPath": "af_alloy.bin", "sizeBytes": 522240 },
+    { "relPath": "af_aoede.bin", "sizeBytes": 522240 },
+    { "relPath": "af_bella.bin", "sizeBytes": 522240 },
+    { "relPath": "af_jessica.bin", "sizeBytes": 522240 },
+    { "relPath": "af_kore.bin", "sizeBytes": 522240 },
+    { "relPath": "af_nicole.bin", "sizeBytes": 522240 },
+    { "relPath": "af_nova.bin", "sizeBytes": 522240 },
+    { "relPath": "af_river.bin", "sizeBytes": 522240 },
+    { "relPath": "af_sarah.bin", "sizeBytes": 522240 },
+    { "relPath": "af_sky.bin", "sizeBytes": 522240 },
+    { "relPath": "am_adam.bin", "sizeBytes": 522240 },
+    { "relPath": "am_echo.bin", "sizeBytes": 522240 },
+    { "relPath": "am_eric.bin", "sizeBytes": 522240 },
+    { "relPath": "am_fenrir.bin", "sizeBytes": 522240 },
+    { "relPath": "am_liam.bin", "sizeBytes": 522240 },
+    { "relPath": "am_michael.bin", "sizeBytes": 522240 },
+    { "relPath": "am_onyx.bin", "sizeBytes": 522240 },
+    { "relPath": "am_puck.bin", "sizeBytes": 522240 },
+    { "relPath": "am_santa.bin", "sizeBytes": 522240 },
+    { "relPath": "bm_lewis.bin", "sizeBytes": 522240 },
+    { "relPath": "em_alex.bin", "sizeBytes": 522240 },
+    { "relPath": "ff_siwis.bin", "sizeBytes": 522240 },
+    { "relPath": "hm_omega.bin", "sizeBytes": 522240 },
+    { "relPath": "im_nicola.bin", "sizeBytes": 522240 },
+    { "relPath": "jm_kumo.bin", "sizeBytes": 522240 },
+    { "relPath": "pm_alex.bin", "sizeBytes": 522240 }
+  ],
+  "aneZh": [
+    { "relPath": "KokoroAlbert.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroAlbert.mlmodelc/coremldata.bin", "sizeBytes": 433 },
+    { "relPath": "KokoroAlbert.mlmodelc/metadata.json", "sizeBytes": 2480 },
+    { "relPath": "KokoroAlbert.mlmodelc/model.mil", "sizeBytes": 101485 },
+    { "relPath": "KokoroAlbert.mlmodelc/weights/weight.bin", "sizeBytes": 5718848 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/coremldata.bin", "sizeBytes": 556 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/metadata.json", "sizeBytes": 4171 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/model.mil", "sizeBytes": 60047 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/weights/weight.bin", "sizeBytes": 13806464 },
+    { "relPath": "KokoroAlignment.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroAlignment.mlmodelc/coremldata.bin", "sizeBytes": 484 },
+    { "relPath": "KokoroAlignment.mlmodelc/metadata.json", "sizeBytes": 3021 },
+    { "relPath": "KokoroAlignment.mlmodelc/model.mil", "sizeBytes": 8194 },
+    { "relPath": "KokoroAlignment.mlmodelc/weights/weight.bin", "sizeBytes": 4128 },
+    { "relPath": "KokoroProsody.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroProsody.mlmodelc/coremldata.bin", "sizeBytes": 422 },
+    { "relPath": "KokoroProsody.mlmodelc/metadata.json", "sizeBytes": 2721 },
+    { "relPath": "KokoroProsody.mlmodelc/model.mil", "sizeBytes": 79705 },
+    { "relPath": "KokoroProsody.mlmodelc/weights/weight.bin", "sizeBytes": 8454272 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/coremldata.bin", "sizeBytes": 440 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/metadata.json", "sizeBytes": 3091 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/model.mil", "sizeBytes": 93152 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/weights/weight.bin", "sizeBytes": 4580160 },
+    { "relPath": "KokoroVocoder.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroVocoder.mlmodelc/coremldata.bin", "sizeBytes": 627 },
+    { "relPath": "KokoroVocoder.mlmodelc/metadata.json", "sizeBytes": 4331 },
+    { "relPath": "KokoroVocoder.mlmodelc/model.mil", "sizeBytes": 308997 },
+    { "relPath": "KokoroVocoder.mlmodelc/weights/weight.bin", "sizeBytes": 48889920 },
+    { "relPath": "KokoroTail_v2.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroTail_v2.mlmodelc/coremldata.bin", "sizeBytes": 392 },
+    { "relPath": "KokoroTail_v2.mlmodelc/metadata.json", "sizeBytes": 1872 },
+    { "relPath": "KokoroTail_v2.mlmodelc/model.mil", "sizeBytes": 7014 },
+    { "relPath": "KokoroTail_v2.mlmodelc/weights/weight.bin", "sizeBytes": 81088 },
+    { "relPath": "vocab.json", "sizeBytes": 1796 },
+    { "relPath": "voices/zf_001.bin", "sizeBytes": 522240 },
+    { "relPath": "voices/zm_050.bin", "sizeBytes": 522240 },
+    { "relPath": "g2pw/g2pw.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "g2pw/g2pw.mlmodelc/coremldata.bin", "sizeBytes": 515 },
+    { "relPath": "g2pw/g2pw.mlmodelc/metadata.json", "sizeBytes": 3717 },
+    { "relPath": "g2pw/g2pw.mlmodelc/model.mil", "sizeBytes": 245446 },
+    { "relPath": "g2pw/g2pw.mlmodelc/weights/weight.bin", "sizeBytes": 159294962 }
+  ],
+  "aneZhG2p": [
+    { "relPath": "g2p/pinyin_phrases.bin", "sizeBytes": 9552083 },
+    { "relPath": "g2p/pinyin_single.bin", "sizeBytes": 480169 }
+  ],
   "diarize": [
     { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Manifest.json", "sizeBytes": 617 },
     { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Data/com.apple.CoreML/model.mlmodel", "sizeBytes": 856521 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.30.0",
+  "version": "2.0.0",
   "description": "Give your tools a voice — speech to text and back, 25 languages, up to ~19× faster than Whisper. On your machine.",
   "type": "module",
   "bin": {
@@ -39,9 +39,6 @@
       "openclawVersion": "2026.5.27"
     }
   },
-  "keshaEngine": {
-    "version": "1.25.0"
-  },
   "scripts": {
     "test": "bun test --timeout 30000",
     "test:watch": "bun test --timeout 30000 --watch",
@@ -61,7 +58,7 @@
     "check:release-manifest": "bun .github/scripts/release-manifest.mjs --check",
     "check:versions": "bun .github/scripts/check-versions.ts",
     "check:engine-targets": "bun .github/scripts/check-engine-targets.ts",
-    "mutants:ts": "bun scripts/mutants-ts.ts"
+    "check:file-sizes": "bun .github/scripts/check-file-sizes.ts"
   },
   "keywords": [
     "asr",
@@ -89,8 +86,6 @@
     "bun": ">=1.3.0"
   },
   "devDependencies": {
-    "@hughescr/stryker-bun-runner": "^1.3.8",
-    "@stryker-mutator/core": "^9.6.1",
     "@types/bun": "latest",
     "fast-xml-parser": "^5.8.0",
     "typescript": "^7.0.2",
@@ -111,5 +106,24 @@
     "fast-uri": "^3.1.5",
     "ip-address": "^10.3.1",
     "smol-toml": "1.7.2"
+  },
+  "kesha": {
+    "engine": {
+      "version": "2.0.0",
+      "sha256": {
+        "kesha-engine-darwin-arm64": "2d75bc773fb81917a0dd996124c0e18eea3b15ecc8f04fe274d41c68bda9276c",
+        "kesha-engine-linux-x64": "09082a1f3eb07d8f8051806a057669f098856d84541f087a1e614ca80d8235b2",
+        "kesha-engine-windows-x64.exe": "de86f350bfd3d076cf339d99d892605b1a37a99085e8ff4c8ef87057618193f3",
+        "say-avspeech-darwin-arm64": "a3aa5b75ddff68a48f1158e838310b37cac72ef86841d9cfcdf1ee233cb7451a",
+        "kesha-textlang-darwin-arm64": "e45e2822248b14dd72aa79e2def8fa6b9c07c97423f11c841508769225d72da4"
+      },
+      "size": {
+        "kesha-engine-darwin-arm64": 73623152,
+        "kesha-engine-linux-x64": 67392296,
+        "kesha-engine-windows-x64.exe": 66550272,
+        "say-avspeech-darwin-arm64": 64208,
+        "kesha-textlang-darwin-arm64": 57648
+      }
+    }
   }
 }

package/src/cache-layout.ts

@@ -1,8 +1,21 @@
-import { join, resolve, sep } from "path";
+import { existsSync, realpathSync, statSync } from "fs";
+import { dirname, join, resolve, sep } from "path";
+import { dirSizeBytes } from "./diagnostic-paths";
 
-export interface CachePathEntry {
+/** The sidecar executables the engine spawns from its own directory. */
+const SIDECAR_FILES = ["say-avspeech", "kesha-textlang"] as const;
+
+export interface CacheComponentSize {
   label: string;
   path: string;
+  exists: boolean;
+  sizeBytes: number;
+}
+
+interface EngineFootprint {
+  path: string;
+  members: string[];
+  sizeOf: (path: string) => number;
 }
 
 /**
@@ -18,6 +31,56 @@ export function isInsideDir(child: string, parent: string): boolean {
   return resolvedChild === resolvedParent || resolvedChild.startsWith(`${resolvedParent}${sep}`);
 }
 
+/**
+ * What the Engine row owns (#1313). A managed install owns all of `<cache>/engine`. An
+ * overridden binary (`KESHA_ENGINE_BIN`, a Nix store path) shares its directory with software
+ * Kesha does not own, so only the binary and the sidecars beside it are counted — its
+ * grandparent may be `/usr/local`.
+ */
+function engineFootprint(binPath: string, cacheRoot: string): EngineFootprint {
+  const managedRoot = join(cacheRoot, "engine");
+  if (resolve(dirname(binPath)) === resolve(managedRoot, "bin")) {
+    return { path: managedRoot, members: [managedRoot], sizeOf: dirSizeBytes };
+  }
+  const binDir = dirname(binPath);
+  return {
+    path: binPath,
+    members: [binPath, ...SIDECAR_FILES.map((f) => join(binDir, f))],
+    sizeOf: regularFileBytes,
+  };
+}
+
+/** A sidecar name that is (or links to) a directory is not ours to walk. */
+function regularFileBytes(path: string): number {
+  try {
+    const st = statSync(path);
+    return st.isFile() ? st.size : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function footprintBytes(engine: EngineFootprint, members: string[]): number {
+  return members.reduce((n, p) => n + engine.sizeOf(p), 0);
+}
+
+/** The cache plus whatever engine bytes live outside it, each counted once (#790). */
+export function cacheTotalBytes(cacheRoot: string, binPath: string): number {
+  const engine = engineFootprint(binPath, cacheRoot);
+  const realCache = existingPath(cacheRoot);
+  const outside = engine.members.filter((m) => !isInsideDir(existingPath(m), realCache));
+  return dirSizeBytes(cacheRoot) + footprintBytes(engine, outside);
+}
+
+/** Compared by target, so an outside symlink into the cache is not counted twice. */
+function existingPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
 /**
  * The Kesha-managed directories both `kesha status --disk` and `kesha doctor` report, in one
  * place so a new model dir cannot be added to only one of them. The two ASR rows are mutually
@@ -26,13 +89,19 @@ export function isInsideDir(child: string, parent: string): boolean {
  * Whatever stayed in FluidAudio's own trees is outside this cache and is reported separately
  * by `fluidExternalRoots`.
  */
-export function cacheComponentPaths(
+export function cacheComponents(
   cacheRoot: string,
-  engineDir: string,
+  binPath: string,
   coreml: boolean,
-): CachePathEntry[] {
-  return [
-    { label: "Engine", path: engineDir },
+): CacheComponentSize[] {
+  const engine = engineFootprint(binPath, cacheRoot);
+  const engineRow = {
+    label: "Engine",
+    path: engine.path,
+    exists: existsSync(engine.path),
+    sizeBytes: footprintBytes(engine, engine.members),
+  };
+  const modelRows = [
     ...(coreml
       ? [{ label: "FluidAudio (in cache)", path: join(cacheRoot, "fluidaudio") }]
       : [{ label: "ASR (Parakeet)", path: join(cacheRoot, "models/parakeet-tdt-v3") }]),
@@ -40,5 +109,6 @@ export function cacheComponentPaths(
     { label: "VAD (Silero)", path: join(cacheRoot, "models/silero-vad") },
     { label: "TTS (Kokoro)", path: join(cacheRoot, "models/kokoro-82m") },
     { label: "TTS (Vosk)", path: join(cacheRoot, "models/vosk-ru") },
-  ];
+  ].map((row) => ({ ...row, exists: existsSync(row.path), sizeBytes: dirSizeBytes(row.path) }));
+  return [engineRow, ...modelRows];
 }

package/src/cli/action-result.ts

@@ -1,4 +1,5 @@
 import { log } from "../log";
+import { renderInvalidArg } from "./options";
 
 export type ActionMessage = { level: "success" | "info" | "warn"; text: string };
 
@@ -9,7 +10,7 @@ export type ActionResult =
 /** Renders an action's messages, writing `stdout` verbatim; a rejected action exits 2. */
 export function emitActionResult(result: ActionResult): void {
   if (!result.ok) {
-    log.error(result.error);
+    log.error(renderInvalidArg(result.error));
     if (result.hint) log.warn(result.hint);
     process.exit(2);
   }

package/src/cli/command-session.ts

@@ -50,9 +50,8 @@ export async function runCommandSession(
   setEngineDebugSink((event) =>
     session.diagnosticLog.event("engine.debug", {
       t_ms: event.t_ms,
-      event: event.event ?? null,
-      message: event.message,
-      fields: event.fields === undefined ? null : JSON.stringify(event.fields),
+      engineEvent: event.event ?? null,
+      ...engineDebugFields(event.fields),
     }),
   );
   let outcome: CommandOutcome;
@@ -74,6 +73,18 @@ export async function runCommandSession(
   return outcome;
 }
 
+// The message is prose and `event` is a reserved log field, so only the engine's typed fields ride along (Exploratory S9-F5).
+function engineDebugFields(fields: unknown): DiagnosticLogFields {
+  const out: DiagnosticLogFields = {};
+  if (!fields || typeof fields !== "object" || Array.isArray(fields)) return out;
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
 function closeSessionQuietly(
   session: CommandSession,
   command: StatsCommandName,

package/src/cli/completions.ts

@@ -1,5 +1,6 @@
 import { defineCommand } from "citty";
 import { log } from "../log";
+import { renderInvalidArg } from "./options";
 // Inlined because import.meta.url escapes the embedded filesystem in the compiled .deb/.rpm binary (#914).
 import bashCompletions from "../../completions/kesha.bash" with { type: "text" };
 import zshCompletions from "../../completions/kesha.zsh" with { type: "text" };
@@ -29,14 +30,15 @@ export const completionsCommand = defineCommand({
   args: {
     shell: {
       type: "positional",
-      required: true,
+      required: false,
       description: "Shell: bash | zsh | fish",
     },
   },
   async run({ args }: { args: CompletionsCommandArgs }) {
     const shell = args.shell;
     if (!shell || !isShell(shell)) {
-      log.error("usage: kesha completions <bash|zsh|fish>");
+      log.error(renderInvalidArg(shell ? `unknown shell '${shell}' (bash, zsh or fish)` : "missing shell (bash, zsh or fish)"));
+      process.stderr.write("usage: kesha completions <bash|zsh|fish>\n");
       process.exit(2);
     }
     process.stdout.write(SHELL_SCRIPTS[shell]);

package/src/cli/dispatch.ts

@@ -1,9 +1,10 @@
-import { runMain, type CommandDef } from "citty";
+import { runMain, type ArgsDef, type CommandDef } from "citty";
 import { existsSync } from "fs";
 import { log } from "../log";
 import { guardStdoutWrites } from "../stdout-pipe";
 import { suggestCommand } from "../suggest-command";
 import { applyCliContext, resolveCliContext } from "./context";
+import { rejectUnknownOptions, renderInvalidArg } from "./options";
 
 // Lazy loaders so a cold CLI spawn transpiles only the invoked command, not the whole graph (#568).
 // `CommandDef<any>`: citty's generic is invariant in the arg shape and each command has its own schema.
@@ -89,18 +90,42 @@ export function unknownCommandMessages(token: string, subcommandKeys: string[]):
   return { errorLine: `unknown command '${token}'`, warnLines };
 }
 
+async function resolveArgsDef(command: CommandDef<any>): Promise<ArgsDef> {
+  const args = command.args;
+  return (typeof args === "function" ? await args() : await args) ?? {};
+}
+
+/** `kesha --json record --out j.wav` is `record --json --out j.wav`: flag-shaped tokens before a subcommand name move behind it (S3-F3). */
+export function hoistLeadingFlags(rawArgs: string[], subcommandKeys: string[]): string[] {
+  let i = 0;
+  while (i < rawArgs.length && rawArgs[i]!.startsWith("-") && rawArgs[i] !== "--") i++;
+  const name = rawArgs[i];
+  if (i === 0 || name === undefined || !subcommandKeys.includes(name)) return rawArgs;
+  return [name, ...rawArgs.slice(0, i), ...rawArgs.slice(i + 1)];
+}
+
+/** A subcommand name that a valued leading flag hid from hoisting, unless a file of that name exists. */
+function misplacedSubcommand(rawArgs: string[], subcommandKeys: string[]): string | undefined {
+  const end = rawArgs.indexOf("--");
+  return rawArgs.slice(0, end === -1 ? undefined : end).find((arg) => subcommandKeys.includes(arg) && !existsSync(arg));
+}
+
 export async function runCli(argv = process.argv.slice(2)): Promise<void> {
   guardStdoutWrites();
   const context = resolveCliContext(argv);
   applyCliContext(context);
 
-  const [firstArg, ...restArgs] = context.rawArgs;
   const subcommandKeys = SUBCOMMAND_NAMES;
+  const rawArgs = hoistLeadingFlags(context.rawArgs, subcommandKeys);
+  const [firstArg, ...restArgs] = rawArgs;
 
   switch (classifyFirstArg(firstArg, subcommandKeys)) {
-    case "subcommand":
-      await runMain(await SUBCOMMANDS[firstArg!]!(), { rawArgs: restArgs });
+    case "subcommand": {
+      const command = await SUBCOMMANDS[firstArg!]!();
+      rejectUnknownOptions(restArgs, await resolveArgsDef(command));
+      await runMain(command, { rawArgs: restArgs });
       return;
+    }
 
     case "unknown": {
       // Extensionless existing files are valid transcription inputs; bare non-path tokens are likely command typos.
@@ -112,8 +137,15 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
     }
 
     default: {
+      const misplaced = misplacedSubcommand(rawArgs, subcommandKeys);
+      if (misplaced !== undefined) {
+        log.error(renderInvalidArg(`put global flags after the subcommand: kesha ${misplaced} ...`));
+        process.exit(2);
+      }
       const { createMainCommand } = await import("./main");
-      await runMain(createMainCommand(context), { rawArgs: context.rawArgs });
+      const command = createMainCommand(context);
+      rejectUnknownOptions(rawArgs, await resolveArgsDef(command));
+      await runMain(command, { rawArgs });
     }
   }
 }