@drakulavich/kesha-voice-kit 1.19.0-beta.1 → 1.19.0

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)
 ```
@@ -288,7 +288,7 @@ are missing.
 | 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.
 
@@ -321,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

@@ -25,6 +25,7 @@ Local voice toolkit: transcribe voice messages to text, synthesize speech, detec
 - **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.
+- **Need to capture your own voice** for transcription or as a voice-note source: `kesha record --out clip.wav` records up to 120s (override with `--max-seconds`) of mono 16 kHz WAV from the default microphone. Pipe straight into `kesha --json clip.wav` to close the loop.
 
 ## OpenClaw plugin setup
 
@@ -150,9 +151,12 @@ Each `segment.speaker` is a number (cluster id, stable within one file). On Linu
 - `kesha audio.ogg` — plain transcript on stdout
 - `kesha --format transcript audio.ogg` — transcript + `[lang: ru, confidence: 0.99]` footer
 - `kesha --json --timestamps audio.ogg` — JSON with timestamped `segments`
+- `kesha --toon audio.ogg` — TOON (compact, LLM-friendly JSON encoding); preferred when piping multi-file results to an LLM/agent
 - `kesha --verbose audio.ogg` — human-readable with language info
 - `kesha --lang en audio.ogg` — warn if detected language differs (useful sanity check)
 
+**Long audio:** files ≥ 120 s auto-engage Silero VAD chunking; force on with `--vad` or off with `--no-vad`. Short files use full-file ASR by default.
+
 ## TTS: synthesize speech
 
 ```bash
@@ -188,12 +192,25 @@ Format is also inferred from `--out` extension (`.ogg` / `.opus` / `.oga` → OG
 
 ## Install
 
+**Humans use `kesha init` (guided). Agents and scripts use `kesha install` (deterministic).**
+
 ```bash
-bun add -g @drakulavich/kesha-voice-kit          # global CLI install
-kesha install                                    # downloads engine (~350 MB)
-kesha install --tts                              # adds Kokoro + Vosk-TTS RU (~990 MB more, for TTS)
+bun add -g @drakulavich/kesha-voice-kit          # global CLI install (always first)
+
+# For humans: interactive setup that prompts for backend / TTS / VAD / diarize
+kesha init
+
+# For agents and CI: explicit, scriptable install commands
+kesha install                                    # engine only (~350 MB)
+kesha install --tts                              # + Kokoro + Vosk-TTS RU (~990 MB more)
+kesha install --tts --vad                        # + Silero VAD (long-audio chunking)
+kesha install --tts --vad --diarize              # + speaker diarization (darwin-arm64 only)
 ```
 
+Kesha's runtime error/warning messages adapt to the same split: when `kesha` is invoked from a TTY, hints suggest `kesha init`; when stderr is piped (CI logs, OpenClaw, agent subprocess), hints suggest the equivalent `kesha install [...flags]`. Both run the same install code under the hood — pick the one your caller is.
+
+For pre-release builds: `bun add -g @drakulavich/kesha-voice-kit@beta` (current `beta` channel; `@latest` stays on the last stable release).
+
 No system deps — English G2P is embedded (`misaki-rs`); Russian G2P is bundled inside Vosk-TTS. `macos-*` voices need no install either — they use voices already on the Mac.
 
 ## Supported languages
@@ -207,6 +224,13 @@ No system deps — English G2P is embedded (`misaki-rs`); Russian G2P is bundled
 - ASR: ~19× faster than OpenAI Whisper on Apple Silicon (CoreML via FluidAudio), ~2.5× on CPU (ONNX via `ort`).
 - TTS: sub-second latency for short utterances on Apple Silicon.
 
+## Troubleshooting
+
+- `kesha doctor` — collect support diagnostics without changing local state. Add `--json` for machine-readable output, `--redact` to scrub secrets and home paths before sharing.
+- `kesha logs` — manage privacy-safe local diagnostic logs. Default mode is `retain-on-failure` (events buffered in memory, flushed to disk only when a command fails). `kesha logs mode on` captures every run, `kesha logs path` prints the NDJSON file, `kesha logs disable` turns it off entirely.
+- `kesha support-bundle --output bundle.tar.gz` — produce a redacted `.tar.gz` for filing an issue. Add `--include-logs` to bundle a bounded tail of diagnostic logs.
+- `kesha stats` — manage local anonymous performance stats (per-command latency percentiles). Actions: `enable | disable | status | week | errors | export | reset | vacuum | retention`. Stays on the machine.
+
 ## Why local
 
 No API keys to manage. No per-minute billing. Voice data never leaves the machine — important for regulated industries, personal messaging, and anything that shouldn't be in a third-party log.

package/completions/kesha.bash

@@ -6,7 +6,7 @@ _kesha_completion() {
   COMPREPLY=()
   cur="${COMP_WORDS[COMP_CWORD]}"
   command="${COMP_WORDS[1]}"
-  commands="completions doctor init 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
@@ -22,12 +22,13 @@ _kesha_completion() {
     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

@@ -4,6 +4,7 @@ complete -c kesha -n '__fish_use_subcommand' -a 'completions' -d 'Print shell co
 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.'
@@ -50,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'
@@ -80,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

@@ -8,6 +8,7 @@ _kesha() {
     '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.'
@@ -73,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]'
@@ -113,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.19.0-beta.1" "User Commands"
+.TH KESHA 1 "May 2026" "kesha 1.19.0" "User Commands"
 .SH NAME
 kesha \- open-source local voice toolkit
 .SH SYNOPSIS
@@ -23,6 +23,9 @@ Interactive setup guide for Kesha features
 .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
@@ -129,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
@@ -188,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.19.0-beta.1",
+  "version": "1.19.0",
   "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.19.0-beta.1"
+    "version": "1.19.0"
   },
   "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

@@ -1,4 +1,4 @@
-import { runMain } from "citty";
+import { runMain, type CommandDef } from "citty";
 import { existsSync } from "fs";
 import { log } from "../log";
 import { suggestCommand } from "../suggest-command";
@@ -6,6 +6,7 @@ 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";
@@ -14,18 +15,23 @@ import { statusCommand } from "./status";
 import { supportBundleCommand } from "./support-bundle";
 import { mainCommand } from "./main";
 
-const SUBCOMMANDS = [
-  "doctor",
-  "init",
-  "install",
-  "status",
-  "record",
-  "say",
-  "stats",
-  "support-bundle",
-  "completions",
-  "manpage",
-];
+// Single source of truth: keyed lookup also feeds the `did you mean` suggester.
+// `CommandDef<any>` is intentional — citty's generic is invariant in the args
+// shape, and each subcommand has its own arg schema; the value here is only
+// passed back to `runMain`, which re-reads the schema from the def itself.
+const SUBCOMMANDS: Record<string, CommandDef<any>> = {
+  doctor: doctorCommand,
+  init: initCommand,
+  install: installCommand,
+  logs: logsCommand,
+  status: statusCommand,
+  record: recordCommand,
+  say: sayCommand,
+  stats: statsCommand,
+  "support-bundle": supportBundleCommand,
+  completions: completionsCommand,
+  manpage: manpageCommand,
+};
 
 function isPathLike(arg: string): boolean {
   return arg.includes(".") || arg.includes("/") || existsSync(arg);
@@ -34,53 +40,8 @@ function isPathLike(arg: string): boolean {
 export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
   const [firstArg, ...restArgs] = rawArgs;
 
-  if (firstArg === "doctor") {
-    await runMain(doctorCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "init") {
-    await runMain(initCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "completions") {
-    await runMain(completionsCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "install") {
-    await runMain(installCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "manpage") {
-    await runMain(manpageCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "status") {
-    await runMain(statusCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "record") {
-    await runMain(recordCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "say") {
-    await runMain(sayCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "stats") {
-    await runMain(statsCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "support-bundle") {
-    await runMain(supportBundleCommand, { rawArgs: restArgs });
+  if (firstArg && Object.hasOwn(SUBCOMMANDS, firstArg)) {
+    await runMain(SUBCOMMANDS[firstArg], { rawArgs: restArgs });
     return;
   }
 
@@ -88,7 +49,7 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
   // Extensionless existing files remain valid transcription inputs; missing
   // bare tokens are more likely command typos and should not start the engine.
   if (firstArg && !firstArg.startsWith("-") && !isPathLike(firstArg)) {
-    const suggestion = suggestCommand(firstArg, SUBCOMMANDS);
+    const suggestion = suggestCommand(firstArg, Object.keys(SUBCOMMANDS));
     log.error(`unknown command '${firstArg}'`);
     if (suggestion && suggestion !== firstArg) {
       log.warn(`(Did you mean ${suggestion}?)`);

package/src/cli/install.ts

@@ -5,6 +5,7 @@ import { renderInstallPlan } from "../install-plan";
 import { maybeAskForStar } from "../star";
 import { log } from "../log";
 import { packageVersion } from "../package-info";
+import { createDiagnosticLogSession, type DiagnosticLogSession } from "../diagnostic-log";
 
 export interface InstallCommandArgs {
   coreml: boolean;
@@ -46,6 +47,28 @@ function defaultBackendForPlatform(): string | undefined {
   return undefined;
 }
 
+type InstallDiagnosticErrorKind = "validation_failed" | "install_failed";
+
+function finishInstallDiagnostic(
+  diagnosticLog: DiagnosticLogSession | null,
+  startedAt: number,
+  status: "success" | "failed",
+  errorKind?: InstallDiagnosticErrorKind,
+): void {
+  if (!diagnosticLog) return;
+  try {
+    diagnosticLog.event("command.finish", {
+      command: "install",
+      status,
+      durationMs: Math.round(performance.now() - startedAt),
+      ...(errorKind ? { errorKind } : {}),
+    });
+    diagnosticLog.finish(status);
+  } catch (err) {
+    log.debug(`install diagnostic log finish dropped: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 export async function performInstall(
   noCache: boolean,
   backend?: string,
@@ -58,26 +81,42 @@ export async function performInstall(
     log.info(await renderInstallPlan({ noCache, backend, tts, vad, diarize }));
     return;
   }
-  if (diarize && !(process.platform === "darwin" && process.arch === "arm64")) {
-    log.error(
-      "--diarize is currently darwin-arm64 only " +
-      "(see https://github.com/drakulavich/kesha-voice-kit/issues/199).",
-    );
-    process.exit(1);
-  }
-  const platformBackend = defaultBackendForPlatform();
-  if (backend && !process.env.KESHA_ENGINE_BIN && platformBackend && backend !== platformBackend) {
-    log.error(
-      `Requested backend "${backend}" is not available on this platform; ` +
-        `the release engine uses "${platformBackend}".`,
-    );
-    process.exit(1);
-  }
+
+  let diagnosticLog: DiagnosticLogSession | null = null;
+  let errorKind: InstallDiagnosticErrorKind = "install_failed";
+  const startedAt = performance.now();
   try {
+    diagnosticLog = createDiagnosticLogSession();
+    diagnosticLog.event("command.start", {
+      command: "install",
+      backend: backend ?? "auto",
+      noCache,
+      tts,
+      vad,
+      diarize,
+    });
+
+    if (diarize && !(process.platform === "darwin" && process.arch === "arm64")) {
+      errorKind = "validation_failed";
+      throw new Error(
+        "--diarize is currently darwin-arm64 only " +
+        "(see https://github.com/drakulavich/kesha-voice-kit/issues/199).",
+      );
+    }
+    const platformBackend = defaultBackendForPlatform();
+    if (backend && !process.env.KESHA_ENGINE_BIN && platformBackend && backend !== platformBackend) {
+      errorKind = "validation_failed";
+      throw new Error(
+        `Requested backend "${backend}" is not available on this platform; ` +
+          `the release engine uses "${platformBackend}".`,
+      );
+    }
     await downloadEngine(noCache, backend, { tts, vad, diarize });
     await maybeAskForStar(getEngineBinPath(), packageVersion, log);
+    finishInstallDiagnostic(diagnosticLog, startedAt, "success");
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);
+    finishInstallDiagnostic(diagnosticLog, startedAt, "failed", errorKind);
     log.error(message);
     process.exit(1);
   }