@drakulavich/kesha-voice-kit 1.18.0 → 1.18.2

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,91 @@ kesha audio.ogg     # transcript to stdout
 
 Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
 
+## Shell Completions and Manpage
+
+The npm package includes bash, zsh, and fish completions plus `kesha(1)`.
+The CLI can print the packaged files, so install paths do not depend on the
+Bun global package layout:
+
+```bash
+# bash
+mkdir -p ~/.local/share/bash-completion/completions
+kesha completions bash > ~/.local/share/bash-completion/completions/kesha
+
+# zsh
+mkdir -p ~/.zsh/completions
+kesha completions zsh > ~/.zsh/completions/_kesha
+# add to ~/.zshrc once: fpath=(~/.zsh/completions $fpath); autoload -Uz compinit; compinit
+
+# fish
+mkdir -p ~/.config/fish/completions
+kesha completions fish > ~/.config/fish/completions/kesha.fish
+
+# manpage
+mkdir -p ~/.local/share/man/man1
+kesha manpage > ~/.local/share/man/man1/kesha.1
+mandb ~/.local/share/man 2>/dev/null || true
+```
+
+## 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.
+
+## Local Stats privacy and lifecycle
+
+Kesha Stats is disabled by default. When you opt in with `kesha stats enable`,
+Kesha writes a local SQLite database only on your machine:
+
+```bash
+kesha stats status
+kesha stats week
+kesha stats errors
+kesha stats export --format json   # or csv
+kesha stats retention 30           # default: 90 days
+kesha stats retention off          # keep until reset
+kesha stats reset                  # delete recorded stats rows
+kesha stats vacuum                 # compact the SQLite file
+```
+
+The database stores content-free operational records only: command name
+(`transcribe` or `say`), timestamps, success/failure status, app version, item
+count, anonymous stage timings, input/output artifact kind, file extension,
+size, optional duration/sample-rate/channel counts, and sanitized error
+class/code/message.
+
+Stats never stores audio bytes, transcripts, input text, generated speech text,
+file names, full file paths, raw stdout/stderr, environment variables, model
+files, API tokens, or cloud identifiers. `support-bundle` reports Stats status
+only; it never includes the Stats SQLite database.
+
+By default, Stats prunes rows older than 90 days before writing or exporting
+data. Use `kesha stats retention <days>` to change the TTL or `kesha stats
+retention off` to disable TTL pruning. `kesha stats reset` deletes recorded
+runs, artifacts, timings, and errors while preserving settings such as enabled
+state and retention.
+
 ## Nix Install
 
 Alternative reproducible-build path on `aarch64-darwin` / `x86_64-linux`:
@@ -60,6 +147,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

package/completions/kesha.bash

@@ -0,0 +1,38 @@
+# bash completion for kesha.
+# Source this file or copy it into your bash-completion directory.
+
+_kesha_completion() {
+  local cur command opts commands
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  command="${COMP_WORDS[1]}"
+  commands="completions doctor install manpage say stats status support-bundle"
+
+  if [[ "$COMP_CWORD" -eq 1 ]]; then
+    if [[ "$cur" == -* ]]; then
+      COMPREPLY=( $(compgen -W "--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad" -- "$cur") )
+    else
+      COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+    fi
+    return 0
+  fi
+
+  case "$command" in
+    completions) opts="--help -h" ;;
+    doctor) opts="--help -h --json --redact" ;;
+    install) opts="--help -h --coreml --onnx --no-cache --plan --tts --vad --diarize" ;;
+    manpage) opts="--help -h" ;;
+    say) opts="--help -h --voice --lang --out --rate --list-voices --ssml --format --bitrate --sample-rate --no-expand-abbrev --verbose --debug" ;;
+    stats) opts="--help -h --format" ;;
+    status) opts="--help -h --disk" ;;
+    support-bundle) opts="--help -h --output" ;;
+    *) opts="--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad" ;;
+  esac
+
+  if [[ "$cur" == -* ]]; then
+    COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
+  fi
+}
+
+complete -F _kesha_completion kesha
+complete -F _kesha_completion parakeet

package/completions/kesha.fish

@@ -0,0 +1,129 @@
+# 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 'install' -d 'Download inference engine and models'
+complete -c kesha -n '__fish_use_subcommand' -a 'manpage' -d 'Print the kesha(1) manpage'
+complete -c kesha -n '__fish_use_subcommand' -a 'say' -d 'Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
+complete -c kesha -n '__fish_use_subcommand' -a 'stats' -d 'Manage local anonymous Kesha Stats'
+complete -c kesha -n '__fish_use_subcommand' -a 'status' -d 'Show backend installation status'
+complete -c kesha -n '__fish_use_subcommand' -a 'support-bundle' -d 'Create a redacted diagnostics archive for support'
+complete -c kesha -n '__fish_use_subcommand' -l help -d 'Show help'
+complete -c kesha -n '__fish_use_subcommand' -s h -d 'Show help'
+complete -c kesha -n '__fish_use_subcommand' -l version -d 'Show version'
+complete -c kesha -n '__fish_use_subcommand' -s v -d 'Show version'
+complete -c kesha -n '__fish_use_subcommand' -l json -d 'Output results as JSON'
+complete -c kesha -n '__fish_use_subcommand' -l toon -d 'Output results as TOON (compact, LLM-friendly encoding of the same data as --json)'
+complete -c kesha -n '__fish_use_subcommand' -l timestamps -d 'Include timestamped transcript segments in JSON/TOON output'
+complete -c kesha -n '__fish_use_subcommand' -l speakers -d 'Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).'
+complete -c kesha -n '__fish_use_subcommand' -l include-errors -d 'With --json, output { results, errors } so scripts can read per-file failures without parsing stderr'
+complete -c kesha -n '__fish_use_subcommand' -l verbose -d 'Show language detection details'
+complete -c kesha -n '__fish_use_subcommand' -l format -r -d 'Output format: transcript | json | toon (long-form alias for --json / --toon)'
+complete -c kesha -n '__fish_use_subcommand' -l lang -r -d 'Expected language code (ISO 639-1), warn if mismatch'
+complete -c kesha -n '__fish_use_subcommand' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
+complete -c kesha -n '__fish_use_subcommand' -l vad -d 'Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.'
+complete -c kesha -n '__fish_use_subcommand' -l no-vad -d 'Disable VAD preprocessing regardless of duration or install state'
+complete -c kesha -n '__fish_seen_subcommand_from completions' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from completions' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from doctor' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from doctor' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from doctor' -l json -d 'Output diagnostics as JSON'
+complete -c kesha -n '__fish_seen_subcommand_from doctor' -l redact -d 'Redact secrets and user-home paths from diagnostic output'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from install' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l coreml -d 'Force CoreML backend (macOS arm64)'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l onnx -d 'Force ONNX backend'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l no-cache -d 'Re-download even if cached'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l plan -d 'Show download, disk, and warm-up plan without changing local state'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l tts -d 'Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l vad -d 'Also install Silero VAD (~2.3MB) for long-audio preprocessing'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l diarize -d 'Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)'
+complete -c kesha -n '__fish_seen_subcommand_from manpage' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from manpage' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from say' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l voice -r -d 'Voice id, e.g. en-am_michael'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l lang -r -d 'BCP 47 language code (default en-us)'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio to file instead of stdout'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l rate -r -d 'Speaking rate 0.5–2.0'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l list-voices -d 'List installed voices and exit'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l ssml -d 'Parse input as SSML (supports <speak>, <break>; strips unknown tags)'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l bitrate -r -d 'Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l sample-rate -r -d 'Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l no-expand-abbrev -d 'Disable Russian acronym auto-expansion (ВОЗ → \'вэ о зэ\') for ru-vosk-* voices. <say-as interpret-as=\'characters\'> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l verbose -d 'Log TTS synthesis time to stderr'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
+complete -c kesha -n '__fish_seen_subcommand_from stats' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from stats' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from stats' -l format -r -d 'Export format: json | csv'
+complete -c kesha -n '__fish_seen_subcommand_from status' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from status' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from status' -l disk -d 'Include recursive cache disk usage'
+complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -l output -r -d 'Write archive to this .tar.gz path'
+complete -c parakeet -f
+complete -c parakeet -n '__fish_use_subcommand' -a 'completions' -d 'Print shell completion script for bash, zsh, or fish'
+complete -c parakeet -n '__fish_use_subcommand' -a 'doctor' -d 'Collect support diagnostics without changing local state'
+complete -c parakeet -n '__fish_use_subcommand' -a 'install' -d 'Download inference engine and models'
+complete -c parakeet -n '__fish_use_subcommand' -a 'manpage' -d 'Print the kesha(1) manpage'
+complete -c parakeet -n '__fish_use_subcommand' -a 'say' -d 'Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
+complete -c parakeet -n '__fish_use_subcommand' -a 'stats' -d 'Manage local anonymous Kesha Stats'
+complete -c parakeet -n '__fish_use_subcommand' -a 'status' -d 'Show backend installation status'
+complete -c parakeet -n '__fish_use_subcommand' -a 'support-bundle' -d 'Create a redacted diagnostics archive for support'
+complete -c parakeet -n '__fish_use_subcommand' -l help -d 'Show help'
+complete -c parakeet -n '__fish_use_subcommand' -s h -d 'Show help'
+complete -c parakeet -n '__fish_use_subcommand' -l version -d 'Show version'
+complete -c parakeet -n '__fish_use_subcommand' -s v -d 'Show version'
+complete -c parakeet -n '__fish_use_subcommand' -l json -d 'Output results as JSON'
+complete -c parakeet -n '__fish_use_subcommand' -l toon -d 'Output results as TOON (compact, LLM-friendly encoding of the same data as --json)'
+complete -c parakeet -n '__fish_use_subcommand' -l timestamps -d 'Include timestamped transcript segments in JSON/TOON output'
+complete -c parakeet -n '__fish_use_subcommand' -l speakers -d 'Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).'
+complete -c parakeet -n '__fish_use_subcommand' -l include-errors -d 'With --json, output { results, errors } so scripts can read per-file failures without parsing stderr'
+complete -c parakeet -n '__fish_use_subcommand' -l verbose -d 'Show language detection details'
+complete -c parakeet -n '__fish_use_subcommand' -l format -r -d 'Output format: transcript | json | toon (long-form alias for --json / --toon)'
+complete -c parakeet -n '__fish_use_subcommand' -l lang -r -d 'Expected language code (ISO 639-1), warn if mismatch'
+complete -c parakeet -n '__fish_use_subcommand' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
+complete -c parakeet -n '__fish_use_subcommand' -l vad -d 'Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.'
+complete -c parakeet -n '__fish_use_subcommand' -l no-vad -d 'Disable VAD preprocessing regardless of duration or install state'
+complete -c parakeet -n '__fish_seen_subcommand_from completions' -l help -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from completions' -s h -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from doctor' -l help -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from doctor' -s h -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from doctor' -l json -d 'Output diagnostics as JSON'
+complete -c parakeet -n '__fish_seen_subcommand_from doctor' -l redact -d 'Redact secrets and user-home paths from diagnostic output'
+complete -c parakeet -n '__fish_seen_subcommand_from install' -l help -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from install' -s h -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from install' -l coreml -d 'Force CoreML backend (macOS arm64)'
+complete -c parakeet -n '__fish_seen_subcommand_from install' -l onnx -d 'Force ONNX backend'
+complete -c parakeet -n '__fish_seen_subcommand_from install' -l no-cache -d 'Re-download even if cached'
+complete -c parakeet -n '__fish_seen_subcommand_from install' -l plan -d 'Show download, disk, and warm-up plan without changing local state'
+complete -c parakeet -n '__fish_seen_subcommand_from install' -l tts -d 'Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)'
+complete -c parakeet -n '__fish_seen_subcommand_from install' -l vad -d 'Also install Silero VAD (~2.3MB) for long-audio preprocessing'
+complete -c parakeet -n '__fish_seen_subcommand_from install' -l diarize -d 'Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)'
+complete -c parakeet -n '__fish_seen_subcommand_from manpage' -l help -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from manpage' -s h -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l help -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -s h -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l voice -r -d 'Voice id, e.g. en-am_michael'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l lang -r -d 'BCP 47 language code (default en-us)'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio to file instead of stdout'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l rate -r -d 'Speaking rate 0.5–2.0'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l list-voices -d 'List installed voices and exit'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l ssml -d 'Parse input as SSML (supports <speak>, <break>; strips unknown tags)'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l bitrate -r -d 'Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l sample-rate -r -d 'Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l no-expand-abbrev -d 'Disable Russian acronym auto-expansion (ВОЗ → \'вэ о зэ\') for ru-vosk-* voices. <say-as interpret-as=\'characters\'> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l verbose -d 'Log TTS synthesis time to stderr'
+complete -c parakeet -n '__fish_seen_subcommand_from say' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
+complete -c parakeet -n '__fish_seen_subcommand_from stats' -l help -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from stats' -s h -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from stats' -l format -r -d 'Export format: json | csv'
+complete -c parakeet -n '__fish_seen_subcommand_from status' -l help -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from status' -s h -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from status' -l disk -d 'Include recursive cache disk usage'
+complete -c parakeet -n '__fish_seen_subcommand_from support-bundle' -l help -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from support-bundle' -s h -d 'Show help'
+complete -c parakeet -n '__fish_seen_subcommand_from support-bundle' -l output -r -d 'Write archive to this .tar.gz path'

package/completions/kesha.zsh

@@ -0,0 +1,117 @@
+#compdef kesha parakeet
+# zsh completion for kesha.
+
+_kesha() {
+  local -a commands
+  commands=(
+    'completions:Print shell completion script for bash, zsh, or fish'
+    'doctor:Collect support diagnostics without changing local state'
+    'install:Download inference engine and models'
+    'manpage:Print the kesha(1) manpage'
+    'say:Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
+    'stats:Manage local anonymous Kesha Stats'
+    'status:Show backend installation status'
+    'support-bundle:Create a redacted diagnostics archive for support'
+  )
+
+  if (( CURRENT == 2 )); then
+    if [[ "$words[CURRENT]" == -* ]]; then
+      _arguments '--help[Show help]' \
+      '-h[Show help]' \
+      '--version[Show version]' \
+      '-v[Show version]' \
+      '--json[Output results as JSON]' \
+      '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
+      '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
+      '--speakers[Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).]' \
+      '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
+      '--verbose[Show language detection details]' \
+      '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
+      '--lang=[Expected language code (ISO 639-1), warn if mismatch]:lang:' \
+      '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
+      '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
+      '--no-vad[Disable VAD preprocessing regardless of duration or install state]'
+    else
+      _describe -t commands 'kesha command' commands
+    fi
+    return
+  fi
+
+  case "$words[2]" in
+    completions)
+      _arguments '--help[Show help]' \
+        '-h[Show help]'
+      ;;
+    doctor)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--json[Output diagnostics as JSON]' \
+        '--redact[Redact secrets and user-home paths from diagnostic output]'
+      ;;
+    install)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--coreml[Force CoreML backend (macOS arm64)]' \
+        '--onnx[Force ONNX backend]' \
+        '--no-cache[Re-download even if cached]' \
+        '--plan[Show download, disk, and warm-up plan without changing local state]' \
+        '--tts[Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)]' \
+        '--vad[Also install Silero VAD (~2.3MB) for long-audio preprocessing]' \
+        '--diarize[Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)]'
+      ;;
+    manpage)
+      _arguments '--help[Show help]' \
+        '-h[Show help]'
+      ;;
+    say)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--voice=[Voice id, e.g. en-am_michael]:voice:' \
+        '--lang=[BCP 47 language code (default en-us)]:lang:' \
+        '--out=[Write audio to file instead of stdout]:out:' \
+        '--rate=[Speaking rate 0.5–2.0]:rate:' \
+        '--list-voices[List installed voices and exit]' \
+        '--ssml[Parse input as SSML (supports <speak>, <break>; strips unknown tags)]' \
+        '--format=[Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.]:format:' \
+        '--bitrate=[Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.]:bitrate:' \
+        '--sample-rate=[Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.]:sample rate:' \
+        '--no-expand-abbrev[Disable Russian acronym auto-expansion (ВОЗ → '\''вэ о зэ'\'') for ru-vosk-* voices. <say-as interpret-as='\''characters'\''> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.]' \
+        '--verbose[Log TTS synthesis time to stderr]' \
+        '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]'
+      ;;
+    stats)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--format=[Export format: json | csv]:format:'
+      ;;
+    status)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--disk[Include recursive cache disk usage]'
+      ;;
+    support-bundle)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--output=[Write archive to this .tar.gz path]:output:'
+      ;;
+    *)
+      _arguments '--help[Show help]' \
+      '-h[Show help]' \
+      '--version[Show version]' \
+      '-v[Show version]' \
+      '--json[Output results as JSON]' \
+      '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
+      '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
+      '--speakers[Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).]' \
+      '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
+      '--verbose[Show language detection details]' \
+      '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
+      '--lang=[Expected language code (ISO 639-1), warn if mismatch]:lang:' \
+      '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
+      '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
+      '--no-vad[Disable VAD preprocessing regardless of duration or install state]'
+      ;;
+  esac
+}
+
+_kesha "$@"

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.