@drakulavich/kesha-voice-kit 1.19.0-beta.1 → 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)
 ```
@@ -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/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-beta.2" "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-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.19.0-beta.1"
+    "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

@@ -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";
@@ -18,6 +19,7 @@ const SUBCOMMANDS = [
   "doctor",
   "init",
   "install",
+  "logs",
   "status",
   "record",
   "say",
@@ -54,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;

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);
   }

package/src/cli/logs.ts

@@ -0,0 +1,107 @@
+import { defineCommand } from "citty";
+import {
+  getDiagnosticLogStatus,
+  humanBytes,
+  parseDiagnosticLogMode,
+  resetDiagnosticLogs,
+  resolveDiagnosticLogPath,
+  setDiagnosticLogMode,
+} from "../diagnostic-log";
+import { log } from "../log";
+
+interface LogsCommandArgs {
+  action?: string;
+  value?: string;
+  json?: boolean;
+}
+
+export const logsCommand = defineCommand({
+  meta: {
+    name: "logs",
+    description: "Manage local privacy-safe diagnostic logs",
+  },
+  args: {
+    action: {
+      type: "positional",
+      required: false,
+      description: "Action: status | enable | disable | mode | path | reset",
+    },
+    value: {
+      type: "positional",
+      required: false,
+      description: "Action value: off | on | retain-on-failure",
+    },
+    json: {
+      type: "boolean",
+      description: "Output status as JSON",
+      default: false,
+    },
+  },
+  run({ args }: { args: LogsCommandArgs }) {
+    const action = args.action ?? "status";
+    if (args.json && action !== "status") {
+      log.error("usage: kesha logs status --json");
+      process.exit(2);
+    }
+    switch (action) {
+      case "enable": {
+        const status = setDiagnosticLogMode("on");
+        log.success("Kesha diagnostic logs enabled");
+        log.info(`Mode: ${status.mode}`);
+        log.info(`Path: ${status.activePath}`);
+        log.info(`Rotation: ${humanBytes(status.maxBytes)}, keep ${status.retain}`);
+        return;
+      }
+      case "disable": {
+        const status = setDiagnosticLogMode("off");
+        log.info("Kesha diagnostic logs disabled");
+        log.info(`Mode: ${status.mode}`);
+        log.info(`Path: ${status.activePath}`);
+        return;
+      }
+      case "status": {
+        const status = getDiagnosticLogStatus();
+        if (args.json) {
+          console.log(JSON.stringify(status, null, 2));
+          return;
+        }
+        log.info(`Kesha diagnostic logs: ${status.mode === "off" ? "disabled" : "enabled"}`);
+        log.info(`Mode: ${status.mode}`);
+        log.info(`Path: ${status.activePath}`);
+        log.info(`Size: ${humanBytes(status.totalSizeBytes)}`);
+        log.info(`Rotated files: ${status.rotatedFiles.length}`);
+        log.info(`Rotation: ${humanBytes(status.maxBytes)}, keep ${status.retain}`);
+        return;
+      }
+      case "mode": {
+        if (!args.value) {
+          const status = getDiagnosticLogStatus();
+          log.info(`Kesha diagnostic log mode: ${status.mode}`);
+          return;
+        }
+        const mode = parseDiagnosticLogMode(args.value);
+        if (!mode) {
+          log.error("usage: kesha logs mode <off|on|retain-on-failure>");
+          process.exit(2);
+        }
+        const status = setDiagnosticLogMode(mode);
+        log.info(`Kesha diagnostic log mode set to ${status.mode}`);
+        log.info(`Path: ${status.activePath}`);
+        return;
+      }
+      case "path": {
+        log.info(resolveDiagnosticLogPath());
+        return;
+      }
+      case "reset": {
+        const result = resetDiagnosticLogs();
+        log.info(`Kesha diagnostic logs reset: ${result.deleted} file(s), ${humanBytes(result.bytes)} deleted`);
+        return;
+      }
+      default:
+        log.error(`unknown logs action '${action}'`);
+        log.warn("supported: enable, disable, mode, status, path, reset");
+        process.exit(2);
+    }
+  },
+});

package/src/cli/main.ts

@@ -18,6 +18,8 @@ import { artifactFromFile, createStatsRecorder } from "../stats";
 import { createPercentProgress } from "../progress";
 import { getPendingSignalExitCode, waitForPendingSignalCleanup } from "../process-tree";
 import type { TranscriptionSegment } from "../types";
+import { createDiagnosticLogSession } from "../diagnostic-log";
+import { diagnosticSizeBucket } from "../diagnostic-events";
 
 interface MainCommandArgs {
   _: string[];
@@ -149,6 +151,7 @@ export const mainCommand = defineCommand({
       "  doctor     Collect support diagnostics.\n" +
       "  init       Interactive setup guide for Kesha features.\n" +
       "  install    Download engine and models.\n" +
+      "  logs       Manage local privacy-safe diagnostic logs.\n" +
       "  manpage    Print the kesha(1) manpage.\n" +
       "  record     Record microphone audio to a WAV file.\n" +
       "  status     Inspect installed backend.\n" +
@@ -253,6 +256,7 @@ export const mainCommand = defineCommand({
       process.exit(2);
     }
     const vadMode = vad ? "on" : noVad ? "off" : "auto";
+    const outputFormat = wantsJson ? "json" : wantsToon ? "toon" : wantsTranscript ? "transcript" : "text";
 
     if (files.length === 0) {
       log.info(
@@ -260,6 +264,7 @@ export const mainCommand = defineCommand({
           "       kesha completions <bash|zsh|fish>\n" +
           "       kesha doctor [--json] [--redact]\n" +
           "       kesha install [--no-cache]\n" +
+          "       kesha logs [enable|disable|mode|status|path|reset]\n" +
           "       kesha manpage\n" +
           "       kesha record --out path.wav [--max-seconds 120]\n" +
           "       kesha status\n" +
@@ -274,6 +279,17 @@ export const mainCommand = defineCommand({
     const results: TranscribeResult[] = [];
     const errors: TranscribeErrorRecord[] = [];
     const stats = createStatsRecorder("transcribe");
+    const diagnosticLog = createDiagnosticLogSession();
+    diagnosticLog.event("command.start", {
+      command: "transcribe",
+      itemCount: files.length,
+      outputFormat,
+      vadMode,
+      timestamps: args.timestamps,
+      speakers: args.speakers,
+      includeErrors: args["include-errors"],
+      hasExpectedLang: Boolean(args.lang),
+    });
 
     const wantsLangId = !!(args.lang || args.verbose || wantsJson || wantsToon || wantsTranscript);
     const reportProgress = shouldReportTranscribeProgress({
@@ -286,12 +302,20 @@ export const mainCommand = defineCommand({
       if (!existsSync(file)) {
         hasError = true;
         stats.recordError("input", new Error("File not found"), "file_not_found");
+        diagnosticLog.event("input.missing", { command: "transcribe" });
         errors.push({ file, code: "file_not_found", message: "File not found" });
         log.error(`${file}: File not found`);
         continue;
       }
       const inputArtifact = artifactFromFile(file, "input_audio");
-      if (inputArtifact) stats.recordArtifact(inputArtifact);
+      if (inputArtifact) {
+        stats.recordArtifact(inputArtifact);
+        diagnosticLog.event("input.audio", {
+          command: "transcribe",
+          format: inputArtifact.format || null,
+          sizeBucket: diagnosticSizeBucket(inputArtifact.sizeBytes),
+        });
+      }
 
       const startedAt = performance.now();
       let progress: ReturnType<typeof createPercentProgress> | null = null;
@@ -368,11 +392,24 @@ export const mainCommand = defineCommand({
           result.segments = segments;
         }
         results.push(result);
+        diagnosticLog.event("engine.exit", {
+          command: "transcribe",
+          status: "success",
+          durationMs: sttTimeMs,
+          segmentCount: segments.length,
+          ranAudioLangId: audioResult !== null,
+          ranTxtLangId: textLanguage !== undefined,
+        });
         progress?.finish(`Transcribed ${file}`);
       } catch (err: unknown) {
         progress?.stop();
         hasError = true;
         stats.recordError("transcribe", err);
+        diagnosticLog.event("engine.exit", {
+          command: "transcribe",
+          status: "failed",
+          errorKind: "transcribe_failed",
+        });
         const message = err instanceof Error ? err.message : String(err);
         errors.push({ file, code: "transcribe_failed", message });
         log.error(`${file}: ${message}`);
@@ -392,6 +429,14 @@ export const mainCommand = defineCommand({
     }
 
     stats.finish(hasError ? "failed" : "success", files.length);
+    diagnosticLog.event("command.finish", {
+      command: "transcribe",
+      status: hasError ? "failed" : "success",
+      itemCount: files.length,
+      resultCount: results.length,
+      errorCount: errors.length,
+    });
+    diagnosticLog.finish(hasError ? "failed" : "success");
 
     if (hasError) {
       const signalExitCode = getPendingSignalExitCode();