@drakulavich/kesha-voice-kit 1.18.6 → 1.19.0-beta.2

package/README.md

@@ -96,10 +96,10 @@ 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. On darwin-arm64, Kokoro uses FluidAudio CoreML instead of ONNX:
+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; FluidAudio stores that CoreML cache at `~/.cache/fluidaudio/Models/kokoro`, outside Kesha's pinned model cache:
 
 ```bash
-kesha install --tts                      # ~990MB (Kokoro + Vosk-TTS RU, opt-in)
+kesha install --tts                      # TTS, opt-in; Darwin Kokoro uses FluidAudio cache
 kesha say "Hello, world" > hello.wav
 kesha say "Привет, мир" > privet.wav     # auto-routes (Milena on darwin, ru-vosk-m02 elsewhere)
 ```
@@ -236,6 +236,50 @@ Compared against Whisper `large-v3-turbo` — all engines auto-detect language.
 
 See [BENCHMARK.md](BENCHMARK.md) for the full per-file breakdown (Russian + English).
 
+## Architecture
+
+```text
+Users / agents
+  shell | scripts | OpenClaw | Hermes | Raycast | @drakulavich/kesha-voice-kit/core
+        |
+        v
++------------------------------- Kesha CLI -------------------------------+
+| Bun + TypeScript wrapper                                                |
+| - parses commands and formats stdout/stderr                             |
+| - installs pinned engine/model assets only when explicitly requested    |
+| - keeps cache, support bundles, and local Stats in the CLI              |
++-----------------------------------+-------------------------------------+
+                                   |
+                                   | spawns one local process
+                                   v
++----------------------------- kesha-engine ------------------------------+
+| Rust binary, no cloud calls, no Python, no ffmpeg                       |
+|                                                                         |
+|  Audio input                 Text input                  Diagnostics    |
+|  WAV/MP3/OGG/FLAC/AAC/M4A   plain text / SSML           status/support  |
+|       |                           |                           |         |
+|       v                           v                           v         |
+|  Symphonia decode            TTS preprocessing           runtime probes |
+|       |                           |                                     |
+|       +--> optional VAD           +--> voice routing                    |
+|       |    + diarization          |    Kokoro / Vosk / macOS voices     |
+|       |                           |                                     |
+|       +--> audio lang ID          +--> speech synthesis                 |
+|       |    SpeechBrain ONNX                                             |
+|       |                                                                 |
+|       +--> ASR backend                                                  |
+|            CoreML on Apple Silicon                                      |
+|            ONNX Runtime on Linux/Windows/fallback                       |
++-----------------------------------+-------------------------------------+
+                                   |
+                                   v
+                         transcript | JSON/TOON | WAV | local diagnostics
+```
+
+Cache boundary: `kesha install` and opt-in feature installs populate the local
+cache; ordinary transcription and speech commands fail fast if required assets
+are missing.
+
 ## What's Inside
 
 | Model | Task | Size | Source |
@@ -244,7 +288,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 | [FluidAudio Kokoro](https://github.com/FluidInference/FluidAudio) on darwin-arm64; ONNX Kokoro elsewhere · [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 (FluidAudio cache, not Kesha-verified); 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.
 
@@ -277,9 +321,23 @@ Kesha can collect local diagnostics without downloading models or mutating cache
 ```bash
 kesha doctor --json --redact
 kesha support-bundle --output kesha-support.tar.gz
+kesha support-bundle --include-logs --output kesha-support-with-logs.tar.gz
+kesha logs status
+kesha logs status --json
 ```
 
 `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.
+Diagnostic log contents are excluded by default; pass `--include-logs` to add a
+bounded tail of Kesha's privacy-safe NDJSON diagnostic log.
+
+`kesha logs` manages local, rotated diagnostic logs for troubleshooting. Logs
+default to `retain-on-failure` and also support explicit `off` and `on` modes.
+Use `kesha logs status --json` for a stable machine-readable status contract
+covering the active path, mode, size, rotation settings, and rotated-file list.
+They use content-free NDJSON events: command/stage names, versions, durations,
+exit codes, and coarse audio metadata only. They must not store audio,
+transcripts, input text, generated speech text, file names, full paths, raw
+stdout/stderr, environment variables, tokens, or URLs. See [Diagnostic logs](docs/diagnostic-logs.md).
 
 ## Local Stats privacy and lifecycle
 

package/SKILL.md

@@ -22,8 +22,8 @@ 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). 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 send a voice note (Telegram, WhatsApp, Signal, Discord)**: synthesize directly into messenger-native OGG/Opus with `kesha say --format ogg-opus --out reply.ogg "<text>"`. Default is mono 24 kHz @ 32 kbps - what Telegram `sendVoice` expects. No WAV redirect and no `ffmpeg` round-trip.
+- **Need local file playback/debug output**: WAV is still available with `kesha say --out reply.wav "<text>"`, but do not use WAV for Telegram voice replies. 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 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.
 
 ## OpenClaw plugin setup
@@ -79,6 +79,33 @@ openclaw config get tools.media.audio.echoFormat
 
 Do not rely on `openclaw.plugin.json` to patch `tools.media.audio.models`; OpenClaw ignores non-schema fields such as `configPatch`. Keep the CLI route in user config.
 
+For OpenClaw TTS replies, route the local TTS provider to Kesha OGG/Opus output. This is the Telegram-safe path:
+
+```bash
+openclaw config patch --stdin <<'JSON5'
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "tts-local-cli",
+      providers: {
+        "tts-local-cli": {
+          command: "kesha",
+          args: ["say", "--format", "ogg-opus", "--out", "{{OutputPath}}", "{{Text}}"],
+          outputFormat: "opus",
+          timeoutMs: 120000,
+        },
+      },
+    },
+  },
+}
+JSON5
+```
+
+When invoking Kesha manually from an OpenClaw flow, write OGG/Opus into an OpenClaw-owned temp path, for example `kesha say --format ogg-opus --out /tmp/openclaw/reply.ogg "<text>"`, after ensuring the directory exists. The configured `tts-local-cli` provider should use OpenClaw's `{{OutputPath}}` placeholder instead of a hardcoded path.
+
+Do not configure OpenClaw Telegram TTS as `kesha say "<text>" > reply.wav`; that creates a WAV file and will not render as a native Telegram voice note.
+
 ## STT: transcribe audio
 
 ```bash
@@ -135,14 +162,14 @@ kesha say --voice macos-de-DE "Guten Tag" > de.wav # any macOS system voice —
 kesha say --list-voices                            # Kokoro + Vosk-TTS + ~180 macos-* voices
 ```
 
-Output: WAV mono float32 by default. `--out <path>` writes to a file instead of stdout.
+Output: WAV mono float32 by default. `--out <path>` writes to a file instead of stdout. For Telegram/OpenClaw replies, prefer `--format ogg-opus --out reply.ogg` or the OpenClaw-provided `{{OutputPath}}`.
 
 **Voice notes (Telegram / WhatsApp / Signal / Discord):** add `--format ogg-opus` to emit OGG/Opus directly — the format messenger APIs render as a native voice message:
 
 ```bash
-kesha say "Hello there" --format ogg-opus --out reply.ogg                  # 24 kHz @ 32 kbps mono — Telegram-grade
-kesha say "Привет" --voice ru-vosk-m02 --format ogg-opus --out reply.ogg   # Russian voice note
-kesha say "Hi" --format ogg-opus --bitrate 16000 --out tiny.ogg            # tinier file, intelligible but lossy
+kesha say --format ogg-opus --out reply.ogg "Hello there"                  # 24 kHz @ 32 kbps mono - Telegram-grade
+kesha say --voice ru-vosk-m02 --format ogg-opus --out reply.ogg "Привет"   # Russian voice note
+kesha say --format ogg-opus --bitrate 16000 --out tiny.ogg "Hi"            # tinier file, intelligible but lossy
 ```
 
 Format is also inferred from `--out` extension (`.ogg` / `.opus` / `.oga` → OGG/Opus). `--bitrate` (6 000–510 000 bps) and `--sample-rate` (8 000 / 12 000 / 16 000 / 24 000 / 48 000 Hz) tune the encoder.

package/completions/kesha.bash

@@ -6,7 +6,7 @@ _kesha_completion() {
   COMPREPLY=()
   cur="${COMP_WORDS[COMP_CWORD]}"
   command="${COMP_WORDS[1]}"
-  commands="completions doctor install manpage record say stats status support-bundle"
+  commands="completions doctor init install logs manpage record say stats status support-bundle"
 
   if [[ "$COMP_CWORD" -eq 1 ]]; then
     if [[ "$cur" == -* ]]; then
@@ -20,13 +20,15 @@ _kesha_completion() {
   case "$command" in
     completions) opts="--help -h" ;;
     doctor) opts="--help -h --json --redact" ;;
+    init) opts="--help -h --coreml --onnx --no-cache --plan --yes --tts --vad --diarize" ;;
     install) opts="--help -h --coreml --onnx --no-cache --plan --tts --vad --diarize" ;;
+    logs) opts="--help -h --json" ;;
     manpage) opts="--help -h" ;;
     record) opts="--help -h --out --max-seconds --debug" ;;
     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" ;;
+    support-bundle) opts="--help -h --output --include-logs" ;;
     *) opts="--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad" ;;
   esac
 

package/completions/kesha.fish

@@ -2,7 +2,9 @@
 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'
 complete -c kesha -n '__fish_use_subcommand' -a 'install' -d 'Download inference engine and models'
+complete -c kesha -n '__fish_use_subcommand' -a 'logs' -d 'Manage local privacy-safe diagnostic logs'
 complete -c kesha -n '__fish_use_subcommand' -a 'manpage' -d 'Print the kesha(1) manpage'
 complete -c kesha -n '__fish_use_subcommand' -a 'record' -d 'Record microphone audio to a WAV file'
 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.'
@@ -30,6 +32,16 @@ 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 init' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from init' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from init' -l coreml -d 'Preselect CoreML backend (macOS arm64)'
+complete -c kesha -n '__fish_seen_subcommand_from init' -l onnx -d 'Preselect ONNX backend'
+complete -c kesha -n '__fish_seen_subcommand_from init' -l no-cache -d 'Re-download even if cached'
+complete -c kesha -n '__fish_seen_subcommand_from init' -l plan -d 'Show the selected install plan without downloading'
+complete -c kesha -n '__fish_seen_subcommand_from init' -l yes -d 'Accept defaults and run without prompts'
+complete -c kesha -n '__fish_seen_subcommand_from init' -l tts -d 'Preselect TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)'
+complete -c kesha -n '__fish_seen_subcommand_from init' -l vad -d 'Preselect Silero VAD (~2.3MB) for long-audio preprocessing'
+complete -c kesha -n '__fish_seen_subcommand_from init' -l diarize -d 'Preselect Sortformer speaker diarization (~245MB, darwin-arm64 only)'
 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)'
@@ -39,6 +51,9 @@ complete -c kesha -n '__fish_seen_subcommand_from install' -l plan -d 'Show down
 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 logs' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from logs' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from logs' -l json -d 'Output status as JSON'
 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 record' -l help -d 'Show help'
@@ -69,3 +84,4 @@ complete -c kesha -n '__fish_seen_subcommand_from status' -l disk -d 'Include re
 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 kesha -n '__fish_seen_subcommand_from support-bundle' -l include-logs -d 'Include a bounded tail of privacy-safe diagnostic logs'

package/completions/kesha.zsh

@@ -6,7 +6,9 @@ _kesha() {
   commands=(
     'completions:Print shell completion script for bash, zsh, or fish'
     'doctor:Collect support diagnostics without changing local state'
+    'init:Interactive setup guide for Kesha features'
     'install:Download inference engine and models'
+    'logs:Manage local privacy-safe diagnostic logs'
     'manpage:Print the kesha(1) manpage'
     'record:Record microphone audio to a WAV file'
     '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.'
@@ -49,6 +51,18 @@ _kesha() {
         '--json[Output diagnostics as JSON]' \
         '--redact[Redact secrets and user-home paths from diagnostic output]'
       ;;
+    init)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--coreml[Preselect CoreML backend (macOS arm64)]' \
+        '--onnx[Preselect ONNX backend]' \
+        '--no-cache[Re-download even if cached]' \
+        '--plan[Show the selected install plan without downloading]' \
+        '--yes[Accept defaults and run without prompts]' \
+        '--tts[Preselect TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)]' \
+        '--vad[Preselect Silero VAD (~2.3MB) for long-audio preprocessing]' \
+        '--diarize[Preselect Sortformer speaker diarization (~245MB, darwin-arm64 only)]'
+      ;;
     install)
       _arguments '--help[Show help]' \
         '-h[Show help]' \
@@ -60,6 +74,11 @@ _kesha() {
         '--vad[Also install Silero VAD (~2.3MB) for long-audio preprocessing]' \
         '--diarize[Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)]'
       ;;
+    logs)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--json[Output status as JSON]'
+      ;;
     manpage)
       _arguments '--help[Show help]' \
         '-h[Show help]'
@@ -100,7 +119,8 @@ _kesha() {
     support-bundle)
       _arguments '--help[Show help]' \
         '-h[Show help]' \
-        '--output=[Write archive to this .tar.gz path]:output:'
+        '--output=[Write archive to this .tar.gz path]:output:' \
+        '--include-logs[Include a bounded tail of privacy-safe diagnostic logs]'
       ;;
     *)
       _arguments '--help[Show help]' \

package/docs/diagnostic-logs.md

@@ -0,0 +1,93 @@
+# Diagnostic Logs
+
+Kesha diagnostic logs are local, rotated NDJSON event logs for install, engine,
+and runtime troubleshooting. They are separate from Kesha Stats: Stats stores
+aggregate timings in SQLite after explicit opt-in, while diagnostic logs keep a
+small local ring buffer of structured events.
+
+Diagnostic logs default to `retain-on-failure`: passing commands leave no log
+file, while failed commands can preserve a small local trace for debugging.
+
+```bash
+kesha logs status
+kesha logs status --json
+kesha logs enable
+kesha logs disable
+kesha logs mode retain-on-failure
+kesha logs path
+kesha logs reset
+```
+
+## Modes
+
+Diagnostic logs follow a Playwright-style retention model:
+
+- `off`: do not record diagnostic events.
+- `on`: append events to the rotated local log immediately.
+- `retain-on-failure`: buffer events for the current command and write them only
+  if the command fails. This is the default.
+
+`kesha logs enable` is shorthand for `kesha logs mode on`; `kesha logs disable`
+is shorthand for `kesha logs mode off`. `retain-on-failure` keeps passing runs
+artifact-free while failed runs keep enough context to debug.
+
+`kesha logs status --json` prints the same local status as a stable JSON object:
+`dir`, `activePath`, `statePath`, `exists`, `activeSizeBytes`, `rotatedFiles`,
+`totalSizeBytes`, `mode`, `maxBytes`, and `retain`.
+
+## Privacy Contract
+
+Diagnostic logs are content-free. Event payloads are built from an allowlist of
+typed fields such as command name, app version, platform, backend, feature flags,
+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.
+
+Diagnostic logs must not store:
+
+- audio bytes
+- transcripts
+- input text or generated speech text
+- file names, basenames, or full file paths
+- raw stdout or stderr
+- environment variables
+- URLs, tokens, secrets, API keys, or cloud identifiers
+- model files or model contents
+
+For audio shape, logs should use coarse metadata such as extension, duration
+bucket, size bucket, sample-rate bucket, or channel count. Do not log a path or
+basename even when it looks harmless; names like `therapy-session.m4a` can be
+private.
+
+## Storage
+
+Default paths:
+
+- macOS: `~/Library/Logs/kesha/kesha.ndjson`
+- Linux: `${XDG_STATE_HOME:-~/.local/state}/kesha/logs/kesha.ndjson`
+- Windows: `%LOCALAPPDATA%\kesha\logs\kesha.ndjson`
+
+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.
+
+The first implementation rotates at 10 MB and keeps 5 rotated files. `kesha logs
+reset` deletes Kesha log files but preserves the selected mode.
+
+## Support Bundles
+
+`kesha support-bundle` does not include diagnostic log contents by default. Use
+`kesha support-bundle --include-logs` to add a bounded tail of the active
+already-sanitized NDJSON log when a support issue needs recent command events.
+Recommended flow for a bug report:
+
+```bash
+kesha logs status
+kesha logs mode retain-on-failure
+# reproduce the failure
+kesha support-bundle --include-logs --output kesha-support-with-logs.tar.gz
+```

package/man/kesha.1

@@ -1,4 +1,4 @@
-.TH KESHA 1 "May 2026" "kesha 1.18.6" "User Commands"
+.TH KESHA 1 "May 2026" "kesha 1.19.0-beta.2" "User Commands"
 .SH NAME
 kesha \- open-source local voice toolkit
 .SH SYNOPSIS
@@ -17,9 +17,15 @@ Print shell completion script for bash, zsh, or fish
 .B doctor
 Collect support diagnostics without changing local state
 .TP
+.B init
+Interactive setup guide for Kesha features
+.TP
 .B install
 Download inference engine and models
 .TP
+.B logs
+Manage local privacy\-safe diagnostic logs
+.TP
 .B manpage
 Print the kesha(1) manpage
 .TP
@@ -79,6 +85,31 @@ Output diagnostics as JSON
 .TP
 .B \-\-redact
 Redact secrets and user\-home paths from diagnostic output
+.SS init
+.TP
+.B \-\-coreml
+Preselect CoreML backend (macOS arm64)
+.TP
+.B \-\-onnx
+Preselect ONNX backend
+.TP
+.B \-\-no\-cache
+Re\-download even if cached
+.TP
+.B \-\-plan
+Show the selected install plan without downloading
+.TP
+.B \-\-yes
+Accept defaults and run without prompts
+.TP
+.B \-\-tts
+Preselect TTS models (Kokoro EN + Vosk\-TTS RU, ~990MB)
+.TP
+.B \-\-vad
+Preselect Silero VAD (~2.3MB) for long\-audio preprocessing
+.TP
+.B \-\-diarize
+Preselect Sortformer speaker diarization (~245MB, darwin\-arm64 only)
 .SS install
 .TP
 .B \-\-coreml
@@ -101,6 +132,10 @@ Also install Silero VAD (~2.3MB) for long\-audio preprocessing
 .TP
 .B \-\-diarize
 Also install the Sortformer streaming\-diarization model (~245MB, darwin\-arm64 only — #199)
+.SS logs
+.TP
+.B \-\-json
+Output status as JSON
 .SS record
 .TP
 .B \-\-out
@@ -160,6 +195,9 @@ Include recursive cache disk usage
 .TP
 .B \-\-output
 Write archive to this .tar.gz path
+.TP
+.B \-\-include\-logs
+Include a bounded tail of privacy\-safe diagnostic logs
 .SH FILES
 .TP
 .B completions/kesha.bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.18.6",
+  "version": "1.19.0-beta.2",
   "description": "Give your local tools a voice: fast STT in 25 languages (~19x faster than Whisper on Apple Silicon, ONNX CPU fallback), TTS via Kokoro/Vosk/macOS voices, VAD + 107-language detection. Rust engine, Bun CLI, OpenClaw skill.",
   "type": "module",
   "bin": {
@@ -19,9 +19,9 @@
     "tsconfig.json",
     "openclaw.plugin.json",
     "openclaw-plugin.cjs",
+    "docs/diagnostic-logs.md",
     "docs/product-positioning.md",
     "SKILL.md",
-    "scripts/postinstall.cjs",
     "LICENSE",
     "NOTICES.md",
     "README.md"
@@ -32,7 +32,7 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.18.6"
+    "version": "1.19.0-beta.2"
   },
   "scripts": {
     "test": "bun test",
@@ -49,8 +49,7 @@
     "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"
+    "check:versions": "bun .github/scripts/check-versions.ts"
   },
   "keywords": [
     "asr",

package/src/cli/dispatch.ts

@@ -4,7 +4,9 @@ import { log } from "../log";
 import { suggestCommand } from "../suggest-command";
 import { completionsCommand } from "./completions";
 import { doctorCommand } from "./doctor";
+import { initCommand } from "./init";
 import { installCommand } from "./install";
+import { logsCommand } from "./logs";
 import { manpageCommand } from "./manpage";
 import { recordCommand } from "./record";
 import { sayCommand } from "./say";
@@ -15,7 +17,9 @@ import { mainCommand } from "./main";
 
 const SUBCOMMANDS = [
   "doctor",
+  "init",
   "install",
+  "logs",
   "status",
   "record",
   "say",
@@ -37,6 +41,11 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
     return;
   }
 
+  if (firstArg === "init") {
+    await runMain(initCommand, { rawArgs: restArgs });
+    return;
+  }
+
   if (firstArg === "completions") {
     await runMain(completionsCommand, { rawArgs: restArgs });
     return;
@@ -47,6 +56,11 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
     return;
   }
 
+  if (firstArg === "logs") {
+    await runMain(logsCommand, { rawArgs: restArgs });
+    return;
+  }
+
   if (firstArg === "manpage") {
     await runMain(manpageCommand, { rawArgs: restArgs });
     return;