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

package/README.md

@@ -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 |

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 manpage record say stats status support-bundle"
 
   if [[ "$COMP_CWORD" -eq 1 ]]; then
     if [[ "$cur" == -* ]]; then
@@ -20,6 +20,7 @@ _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" ;;
     manpage) opts="--help -h" ;;
     record) opts="--help -h --out --max-seconds --debug" ;;

package/completions/kesha.fish

@@ -2,6 +2,7 @@
 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 'manpage' -d 'Print the kesha(1) manpage'
 complete -c kesha -n '__fish_use_subcommand' -a 'record' -d 'Record microphone audio to a WAV file'
@@ -30,6 +31,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)'

package/completions/kesha.zsh

@@ -6,6 +6,7 @@ _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'
     'manpage:Print the kesha(1) manpage'
     'record:Record microphone audio to a WAV file'
@@ -49,6 +50,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]' \

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.1" "User Commands"
 .SH NAME
 kesha \- open-source local voice toolkit
 .SH SYNOPSIS
@@ -17,6 +17,9 @@ 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
@@ -79,6 +82,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.18.6",
+  "version": "1.19.0-beta.1",
   "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": {
@@ -32,7 +32,7 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.18.6"
+    "version": "1.19.0-beta.1"
   },
   "scripts": {
     "test": "bun test",

package/src/cli/dispatch.ts

@@ -4,6 +4,7 @@ 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 { manpageCommand } from "./manpage";
 import { recordCommand } from "./record";
@@ -15,6 +16,7 @@ import { mainCommand } from "./main";
 
 const SUBCOMMANDS = [
   "doctor",
+  "init",
   "install",
   "status",
   "record",
@@ -37,6 +39,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;

package/src/cli/init.ts

@@ -0,0 +1,273 @@
+import { defineCommand } from "citty";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { renderInstallPlan } from "../install-plan";
+import { log } from "../log";
+import { performInstall, resolveBackendFlag, resolveNoCacheFlag } from "./install";
+
+export interface InitCommandArgs {
+  coreml: boolean;
+  onnx: boolean;
+  "no-cache": boolean;
+  noCache?: boolean;
+  no_cache?: boolean;
+  tts: boolean;
+  vad: boolean;
+  diarize: boolean;
+  plan: boolean;
+  yes: boolean;
+}
+
+export interface InitSelection {
+  noCache: boolean;
+  backend?: string;
+  tts: boolean;
+  vad: boolean;
+  diarize: boolean;
+}
+
+interface PromptApi {
+  question(prompt: string): Promise<string>;
+}
+
+export function canInstallDiarizeOnPlatform(
+  platform = process.platform,
+  arch = process.arch,
+): boolean {
+  return platform === "darwin" && arch === "arm64";
+}
+
+export function resolveInitSelection(
+  args: InitCommandArgs,
+  backend = resolveBackendFlag(args.coreml, args.onnx),
+  noCache = resolveNoCacheFlag(args),
+): InitSelection {
+  return {
+    noCache,
+    backend,
+    tts: args.tts,
+    vad: args.vad,
+    diarize: args.diarize,
+  };
+}
+
+export function initInstallArgs(selection: InitSelection): string[] {
+  return [
+    "kesha",
+    "install",
+    selection.noCache ? "--no-cache" : "",
+    selection.backend === "coreml" ? "--coreml" : "",
+    selection.backend === "onnx" ? "--onnx" : "",
+    selection.tts ? "--tts" : "",
+    selection.vad ? "--vad" : "",
+    selection.diarize ? "--diarize" : "",
+  ].filter(Boolean);
+}
+
+export function initSuggestionCommands(
+  selection: InitSelection,
+  canDiarize = canInstallDiarizeOnPlatform(),
+): string[][] {
+  const variants: InitSelection[] = [
+    selection,
+    { ...selection, tts: false, vad: true, diarize: false },
+    { ...selection, tts: true, vad: true, diarize: false },
+  ];
+
+  if (canDiarize) {
+    variants.push({ ...selection, tts: false, vad: true, diarize: true });
+  }
+
+  const seen = new Set<string>();
+  return variants.map(initInstallArgs).filter((command) => {
+    const key = command.join("\0");
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function omitUnsupportedDiarize(
+  selection: InitSelection,
+  canDiarize = canInstallDiarizeOnPlatform(),
+): InitSelection {
+  return selection.diarize && !canDiarize ? { ...selection, diarize: false } : selection;
+}
+
+export function renderInitOverview(canDiarize = canInstallDiarizeOnPlatform()): string {
+  const lines = [
+    "Kesha init",
+    "",
+    "Kesha is a local voice toolkit. The base install downloads the engine, speech-to-text models, and language detection models.",
+    "",
+    "Optional features:",
+    "  - Text-to-speech: enables `kesha say` with Kokoro English and Vosk-TTS Russian voices (~990MB).",
+    "  - VAD: skips silence in long audio and improves meeting, lecture, and podcast transcripts (~2.3MB).",
+    canDiarize
+      ? "  - Speaker diarization: labels speakers in JSON/TOON transcript segments (~245MB, darwin-arm64)."
+      : "  - Speaker diarization: labels speakers, but the install is currently darwin-arm64 only.",
+    "",
+    "Nothing downloads until you confirm the final install plan.",
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+export async function promptInitSelection(
+  args: InitCommandArgs,
+  prompt: PromptApi,
+  backend = resolveBackendFlag(args.coreml, args.onnx),
+  canDiarize = canInstallDiarizeOnPlatform(),
+  noCache = resolveNoCacheFlag(args),
+): Promise<InitSelection> {
+  const tts = await askYesNo(prompt, "Install text-to-speech models for `kesha say`?", args.tts);
+  const vad = await askYesNo(prompt, "Install VAD for long or silence-heavy audio?", args.vad);
+  let diarize = false;
+  if (canDiarize) {
+    diarize = await askYesNo(prompt, "Install speaker diarization for `--speakers`?", args.diarize);
+  } else if (args.diarize) {
+    log.warn("--diarize is currently darwin-arm64 only; omitting it from the interactive install.");
+  }
+
+  return {
+    noCache,
+    backend,
+    tts,
+    vad,
+    diarize,
+  };
+}
+
+async function askYesNo(prompt: PromptApi, message: string, defaultValue: boolean): Promise<boolean> {
+  const suffix = defaultValue ? "Y/n" : "y/N";
+  for (;;) {
+    const answer = (await prompt.question(`${message} [${suffix}] `)).trim().toLowerCase();
+    if (answer === "") return defaultValue;
+    if (answer === "y" || answer === "yes") return true;
+    if (answer === "n" || answer === "no") return false;
+    log.warn("Please answer yes or no.");
+  }
+}
+
+async function printPlan(selection: InitSelection): Promise<void> {
+  log.info(
+    await renderInstallPlan({
+      noCache: selection.noCache,
+      backend: selection.backend,
+      tts: selection.tts,
+      vad: selection.vad,
+      diarize: selection.diarize,
+    }),
+  );
+}
+
+async function runNonInteractive(selection: InitSelection): Promise<void> {
+  const canDiarize = canInstallDiarizeOnPlatform();
+  const printableSelection = omitUnsupportedDiarize(selection, canDiarize);
+  if (selection.diarize && !canDiarize) {
+    log.warn("--diarize is currently darwin-arm64 only; omitting it from non-interactive examples.");
+  }
+  log.info(renderInitOverview(canDiarize));
+  await printPlan(printableSelection);
+  log.info("Run one of these commands from an interactive terminal:");
+  for (const command of initSuggestionCommands(printableSelection, canDiarize)) {
+    log.info(`  ${command.join(" ")}`);
+  }
+}
+
+export const initCommand = defineCommand({
+  meta: {
+    name: "init",
+    description: "Interactive setup guide for Kesha features",
+  },
+  args: {
+    coreml: {
+      type: "boolean",
+      description: "Preselect CoreML backend (macOS arm64)",
+      default: false,
+    },
+    onnx: {
+      type: "boolean",
+      description: "Preselect ONNX backend",
+      default: false,
+    },
+    "no-cache": {
+      type: "boolean",
+      description: "Re-download even if cached",
+      default: false,
+    },
+    plan: {
+      type: "boolean",
+      description: "Show the selected install plan without downloading",
+      default: false,
+    },
+    yes: {
+      type: "boolean",
+      description: "Accept defaults and run without prompts",
+      default: false,
+    },
+    tts: {
+      type: "boolean",
+      description: "Preselect TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)",
+      default: false,
+    },
+    vad: {
+      type: "boolean",
+      description: "Preselect Silero VAD (~2.3MB) for long-audio preprocessing",
+      default: false,
+    },
+    diarize: {
+      type: "boolean",
+      description: "Preselect Sortformer speaker diarization (~245MB, darwin-arm64 only)",
+      default: false,
+    },
+  },
+  async run({ args, rawArgs }: { args: InitCommandArgs; rawArgs: string[] }) {
+    const backend = resolveBackendFlag(args.coreml, args.onnx);
+    const noCache = resolveNoCacheFlag(args, rawArgs);
+    const selection = resolveInitSelection(args, backend, noCache);
+
+    if (args.plan) {
+      log.info(renderInitOverview());
+      await printPlan(selection);
+      return;
+    }
+
+    if (args.yes) {
+      const installSelection = omitUnsupportedDiarize(selection);
+      if (selection.diarize && !installSelection.diarize) {
+        log.warn("--diarize is currently darwin-arm64 only; omitting it from the --yes install.");
+      }
+      await performInstall(
+        installSelection.noCache,
+        installSelection.backend,
+        installSelection.tts,
+        installSelection.vad,
+        installSelection.diarize,
+      );
+      return;
+    }
+
+    const stdinIsTty = process.stdin.isTTY === true;
+    const stdoutIsTty = process.stdout.isTTY === true;
+    if (!stdinIsTty || !stdoutIsTty) {
+      await runNonInteractive(selection);
+      return;
+    }
+
+    log.info(renderInitOverview());
+    const rl = createInterface({ input, output });
+    try {
+      const prompted = await promptInitSelection(args, rl, backend, canInstallDiarizeOnPlatform(), noCache);
+      log.info("");
+      await printPlan(prompted);
+      const confirmed = await askYesNo(rl, `Run \`${initInstallArgs(prompted).join(" ")}\` now?`, true);
+      if (!confirmed) {
+        log.info(`Skipped install. Run later: ${initInstallArgs(prompted).join(" ")}`);
+        return;
+      }
+      await performInstall(prompted.noCache, prompted.backend, prompted.tts, prompted.vad, prompted.diarize);
+    } finally {
+      rl.close();
+    }
+  },
+});

package/src/cli/install.ts

@@ -6,17 +6,31 @@ import { maybeAskForStar } from "../star";
 import { log } from "../log";
 import { packageVersion } from "../package-info";
 
-interface InstallCommandArgs {
+export interface InstallCommandArgs {
   coreml: boolean;
   onnx: boolean;
   "no-cache": boolean;
+  noCache?: boolean;
+  no_cache?: boolean;
   tts: boolean;
   vad: boolean;
   diarize: boolean;
   plan: boolean;
 }
 
-function resolveBackendFlag(coreml: boolean, onnx: boolean): string | undefined {
+export function resolveNoCacheFlag(
+  args: Pick<InstallCommandArgs, "no-cache" | "noCache" | "no_cache">,
+  rawArgs: string[] = [],
+): boolean {
+  return (
+    rawArgs.includes("--no-cache") ||
+    args["no-cache"] === true ||
+    args.noCache === true ||
+    args.no_cache === true
+  );
+}
+
+export function resolveBackendFlag(coreml: boolean, onnx: boolean): string | undefined {
   if (coreml && onnx) {
     log.error('Choose only one backend: "--coreml" or "--onnx".');
     process.exit(1);
@@ -32,7 +46,7 @@ function defaultBackendForPlatform(): string | undefined {
   return undefined;
 }
 
-async function performInstall(
+export async function performInstall(
   noCache: boolean,
   backend?: string,
   tts = false,
@@ -111,8 +125,8 @@ export const installCommand = defineCommand({
       default: false,
     },
   },
-  async run({ args }: { args: InstallCommandArgs }) {
+  async run({ args, rawArgs }: { args: InstallCommandArgs; rawArgs: string[] }) {
     const backend = resolveBackendFlag(args.coreml, args.onnx);
-    await performInstall(args["no-cache"], backend, args.tts, args.vad, args.diarize, args.plan);
+    await performInstall(resolveNoCacheFlag(args, rawArgs), backend, args.tts, args.vad, args.diarize, args.plan);
   },
 });

package/src/cli/main.ts

@@ -147,6 +147,7 @@ export const mainCommand = defineCommand({
       "Commands:\n" +
       "  completions  Print shell completion script.\n" +
       "  doctor     Collect support diagnostics.\n" +
+      "  init       Interactive setup guide for Kesha features.\n" +
       "  install    Download engine and models.\n" +
       "  manpage    Print the kesha(1) manpage.\n" +
       "  record     Record microphone audio to a WAV file.\n" +

package/src/cli.ts

@@ -5,6 +5,17 @@
 // public surface is unchanged.
 export { doctorCommand } from "./cli/doctor";
 export { completionsCommand } from "./cli/completions";
+export {
+  canInstallDiarizeOnPlatform,
+  initCommand,
+  initInstallArgs,
+  initSuggestionCommands,
+  omitUnsupportedDiarize,
+  promptInitSelection,
+  renderInitOverview,
+  resolveInitSelection,
+} from "./cli/init";
+export type { InitCommandArgs, InitSelection } from "./cli/init";
 export { installCommand } from "./cli/install";
 export { manpageCommand } from "./cli/manpage";
 export { recordCommand, resolveRecordArgs } from "./cli/record";

package/src/doctor.ts

@@ -257,20 +257,19 @@ function collectOptionalComponents(redact: boolean): OptionalComponent[] {
       ...pathSummary(join(cache, "models/vosk-ru")),
     },
     {
-      name: "Diarization sidecar",
-      note: "darwin-arm64 only",
-      ...pathSummary(join(sidecarDir, "kesha-diarize-darwin-arm64")),
+      // Diarization (#199) and Kokoro (#207) run in-engine now (native
+      // fluidaudio-rs) — no Swift sidecar binaries. The Sortformer model is
+      // the only installable diarization artifact; Kokoro is covered by the
+      // "TTS (Kokoro)" entry above.
+      name: "Diarization (Sortformer)",
+      note: "enabled with `kesha install --diarize` (darwin-arm64); runs in-engine",
+      ...pathSummary(join(cache, "models/diarize")),
     },
     {
       name: "AVSpeech sidecar",
       note: "macOS voices",
       ...pathSummary(join(sidecarDir, "say-avspeech")),
     },
-    {
-      name: "FluidAudio Kokoro sidecar",
-      note: "darwin-arm64 Kokoro",
-      ...pathSummary(join(sidecarDir, "kesha-kokoro")),
-    },
     {
       name: "Text language sidecar",
       note: "darwin text language fast path",

package/src/engine-install.ts

@@ -69,20 +69,9 @@ const SIDECARS: SidecarSpec[] = [
     availableHint: "macOS voices available",
     unavailableHint: "macos-* voices unavailable",
   },
-  {
-    fileBasename: "kesha-diarize-darwin-arm64",
-    assetName: "kesha-diarize-darwin-arm64",
-    displayName: "Diarization sidecar",
-    availableHint: "--speakers available",
-    unavailableHint: "--speakers unavailable",
-  },
-  {
-    fileBasename: "kesha-kokoro",
-    assetName: "kesha-kokoro-darwin-arm64",
-    displayName: "FluidAudio Kokoro sidecar",
-    availableHint: "Kokoro uses FluidAudio CoreML",
-    unavailableHint: "en-* Kokoro voices unavailable on Darwin",
-  },
+  // Kokoro TTS (#207) and speaker diarization (#199) no longer ship as Swift
+  // sidecars — both run in-engine via the native `fluidaudio-rs` binding. Only
+  // the AVSpeech and text-lang sidecars remain.
   {
     // Runtime resolver looks for plain `kesha-textlang` next to the engine
     // (see `rust/src/text_lang.rs::helper_path`), not the platform-suffixed
@@ -99,6 +88,40 @@ const SIDECARS: SidecarSpec[] = [
   },
 ];
 
+const RETIRED_SIDECAR_FILENAMES = [
+  // Historical installed filenames.
+  "kesha-kokoro",
+  "kesha-diarize",
+  // Historical release-asset filenames. Keep these explicit: AVSpeech and
+  // text-lang helpers are still active and must not be swept up by a glob.
+  "kesha-kokoro-darwin-arm64",
+  "kesha-diarize-darwin-arm64",
+];
+
+export function cleanupRetiredSidecars(engineDir: string): string[] {
+  const removed: string[] = [];
+
+  for (const filename of RETIRED_SIDECAR_FILENAMES) {
+    const path = join(engineDir, filename);
+    if (!existsSync(path)) continue;
+
+    try {
+      rmSync(path);
+      removed.push(filename);
+    } catch (e) {
+      log.warn(
+        `Could not remove retired sidecar ${filename} (${e instanceof Error ? e.message : e}); continuing.`,
+      );
+    }
+  }
+
+  if (removed.length > 0) {
+    log.success(`Removed retired sidecars: ${removed.join(", ")}.`);
+  }
+
+  return removed;
+}
+
 /**
  * Make a freshly-downloaded Mach-O runnable on macOS 15+ Sequoia.
  *
@@ -232,8 +255,10 @@ async function downloadSidecar(
 
 async function warmDarwinKokoro(binPath: string): Promise<void> {
   if (process.platform !== "darwin" || process.arch !== "arm64") return;
-  const sidecarPath = join(dirname(binPath), "kesha-kokoro");
-  if (!existsSync(sidecarPath)) return;
+  // Kokoro now runs in-engine (FluidAudio CoreML, system_kokoro) — warm it by
+  // exercising the engine's own `say`, not a sidecar. The first synthesis
+  // compiles/fetches FluidAudio's CoreML Kokoro cache.
+  if (!existsSync(binPath)) return;
 
   const outPath = join(tmpdir(), `kesha-kokoro-warmup-${process.pid}.wav`);
   log.progress("Warming FluidAudio Kokoro CoreML cache...");
@@ -499,6 +524,10 @@ export async function downloadEngine(
     await warmDarwinKokoro(binPath);
   }
 
+  if (canWriteEngineDir) {
+    cleanupRetiredSidecars(engineDir);
+  }
+
   log.success("Backend installed successfully.");
   return binPath;
 }

package/src/install-plan.ts

@@ -81,10 +81,10 @@ const DIARIZE_FILES: PlanFile[] = [
   },
 ];
 
+// Kokoro (#207) and diarization (#199) are in-engine now (native fluidaudio-rs),
+// so only AVSpeech and text-lang ship as separate Swift-sidecar assets.
 const DARWIN_SIDECARS: ReleaseAssetSpec[] = [
   { assetName: "say-avspeech-darwin-arm64", sizeBytes: 63_056 },
-  { assetName: "kesha-diarize-darwin-arm64", sizeBytes: 7_228_000 },
-  { assetName: "kesha-kokoro-darwin-arm64", sizeBytes: 7_189_648 },
   { assetName: "kesha-textlang-darwin-arm64", sizeBytes: 57_648 },
 ];
 
@@ -123,8 +123,6 @@ function engineAssetForPlatform(): ReleaseAssetSpec | null {
 
 function sidecarFilename(assetName: string): string {
   if (assetName === "say-avspeech-darwin-arm64") return "say-avspeech";
-  if (assetName === "kesha-diarize-darwin-arm64") return "kesha-diarize-darwin-arm64";
-  if (assetName === "kesha-kokoro-darwin-arm64") return "kesha-kokoro";
   if (assetName === "kesha-textlang-darwin-arm64") return "kesha-textlang";
   return assetName;
 }
@@ -234,11 +232,11 @@ export async function renderInstallPlan(options: InstallPlanOptions = {}): Promi
       );
       components.push({
         name: "TTS Kokoro EN",
-        source: "FluidAudio CoreML sidecar",
+        source: "FluidAudio CoreML (in-engine)",
         sizeBytes: 0,
-        cached: existsSync(join(engineDir, "kesha-kokoro")),
+        cached: existsSync(binPath),
         refresh: false,
-        note: "no Kokoro ONNX model is downloaded by Kesha on darwin-arm64; warm-up may compile/update FluidAudio's CoreML cache",
+        note: "Kokoro runs in-engine via FluidAudio CoreML; no Kokoro ONNX model is downloaded by Kesha on darwin-arm64; warm-up may compile/update FluidAudio's CoreML cache",
       });
     } else {
       components.push(

package/src/shell-artifacts.ts

@@ -1,6 +1,7 @@
 import type { ArgDef, ArgsDef, CommandDef, CommandMeta, Resolvable } from "citty";
 import { completionsCommand } from "./cli/completions";
 import { doctorCommand } from "./cli/doctor";
+import { initCommand } from "./cli/init";
 import { installCommand } from "./cli/install";
 import { mainCommand } from "./cli/main";
 import { manpageCommand } from "./cli/manpage";
@@ -44,6 +45,7 @@ export interface ShellArtifact {
 const CLI_COMMANDS: CliCommand[] = [
   { name: "completions", command: completionsCommand },
   { name: "doctor", command: doctorCommand },
+  { name: "init", command: initCommand },
   { name: "install", command: installCommand },
   { name: "manpage", command: manpageCommand },
   { name: "record", command: recordCommand },