From 4d4520aea47e477ffe130be57b4d8e25ed9e3a93 Mon Sep 17 00:00:00 2001
From: andyhtran <76441965+andyhtran@users.noreply.github.com>
Date: Tue, 7 Jul 2026 20:25:43 -0400
Subject: [PATCH 1/2] Rework CLI help tiers, add multi-target skill install,
 and Codex support

Introduce bare/standard/full help levels with --full flag for the complete
command reference. Add --target/--codex/--skill-dir flags to skill commands
for Codex and custom skill directory support. Replace document-skills path
with per-agent skill directories, add dry-run preview for skill install,
and restructure skills list/get with JSON output and runtime skill registry.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 Sources/MiniWhisperCLI/CLI.swift           | 131 ++++-
 Sources/MiniWhisperCLI/DoctorCommand.swift |   9 +-
 Sources/MiniWhisperCLI/ModelsCommand.swift |   2 +-
 Sources/MiniWhisperCLI/Paths.swift         |  35 +-
 Sources/MiniWhisperCLI/SkillsCommand.swift | 643 +++++++++++++++------
 5 files changed, 633 insertions(+), 187 deletions(-)

diff --git a/Sources/MiniWhisperCLI/CLI.swift b/Sources/MiniWhisperCLI/CLI.swift
index 569d14f..1b6e310 100644
--- a/Sources/MiniWhisperCLI/CLI.swift
+++ b/Sources/MiniWhisperCLI/CLI.swift
@@ -3,16 +3,24 @@ import Foundation
 enum CLI {
     static func run(arguments: [String]) async -> Int32 {
         guard let command = arguments.first else {
-            Help.printRoot()
+            Help.printBareRoot()
+            return 0
+        }
+
+        if Help.isRootFullHelp(arguments) {
+            Help.printFull()
             return 0
         }
 
         let rest = Array(arguments.dropFirst())
 
         switch command {
-        case "-h", "--help", "help":
+        case "-h", "--help":
             Help.printRoot()
             return 0
+        case "-V", "--version":
+            Console.out(Version.current)
+            return 0
         case "transcribe":
             return await TranscribeCommand.run(arguments: rest)
         case "models":
@@ -37,6 +45,39 @@ enum CLI {
 }
 
 enum Help {
+    static func isRootFullHelp(_ arguments: [String]) -> Bool {
+        guard arguments.count == 2 else { return false }
+        return arguments.contains { $0 == "--help" || $0 == "-h" }
+            && arguments.contains("--full")
+    }
+
+    static func printBareRoot() {
+        Console.out(
+            """
+            MiniWhisper CLI
+            Local audio transcription with Parakeet and Whisper.
+
+            Usage:
+              miniwhispercli <command> [options]
+
+            Start here (for AI agents):
+              miniwhispercli skills get core
+              miniwhispercli skills list --json
+
+            Version-matched guidance. Load core first; use the JSON list for available guides.
+
+            Next:
+              miniwhispercli transcribe <audio>
+              miniwhispercli models status
+              miniwhispercli skill install --apply
+
+            More:
+              miniwhispercli skills list
+              miniwhispercli --help
+            """
+        )
+    }
+
     static func printRoot() {
         Console.out(
             """
@@ -45,6 +86,12 @@ enum Help {
             Usage:
               miniwhispercli <command> [options]
 
+            Start here (for AI agents):
+              miniwhispercli skills get core
+              miniwhispercli skills list --json
+
+            Version-matched guidance. Load core first; use the JSON list for available guides.
+
             Common commands:
               transcribe <audio>       Transcribe audio with Parakeet or Whisper
               models status            Show local model readiness
@@ -54,10 +101,13 @@ enum Help {
               doctor                   Check local CLI readiness
 
             Agent integration:
-              skills get core          Print the agent-facing core skill
+              skills list              List bundled runtime guides
+              skills get core          Print the agent-facing core guide
               skill status             Show agent skill install status
-              skill install            Install the Claude Code discovery skill
-              skill uninstall          Remove the managed discovery skill
+              skill install            Preview discovery-stub install
+              skill install --apply    Install the discovery stub
+              skill show               Print the bundled discovery stub
+              skill uninstall          Remove the managed discovery stub
 
             Useful examples:
               miniwhispercli transcribe audio.wav
@@ -68,7 +118,76 @@ enum Help {
               miniwhispercli transcribe audio.wav --json
               miniwhispercli transcribe audio.wav --source system
               miniwhispercli models status
-              miniwhispercli skill install
+              miniwhispercli skill install --apply
+
+            More help:
+              miniwhispercli <command> --help
+              miniwhispercli --help --full
+              miniwhispercli skills list
+              miniwhispercli skills get core
+            """
+        )
+    }
+
+    static func printFull() {
+        Console.out(
+            """
+            Usage: miniwhispercli <command> [flags]
+
+            MiniWhisper CLI local audio transcription.
+
+            Flags:
+              -h, --help                              Show help
+              -V, --version                           Show version
+                  --full                              With --help, show this full command reference
+
+            Commands:
+              transcribe <audio>                      Transcribe audio with Parakeet or Whisper
+              models                                  Show local model readiness
+              models status [--json]                  Show local model readiness
+              models install <parakeet|whisper>       Install or verify a model
+              paths [--json]                          Show model, skill, and binary paths
+              doctor [--json]                         Check local CLI readiness
+              skills                                  List bundled runtime guides
+              skills list [--json]                    List bundled runtime guides
+              skills get <name> [--json]              Print bundled runtime guidance
+              skill                                   Show discovery-stub install status
+              skill status [--json]                   Show discovery-stub install status
+              skill install [--dry-run|--apply]       Preview or install the managed discovery stub
+              skill show [--json]                     Print the bundled discovery stub
+              skill uninstall [--json]                Remove the managed discovery stub
+              version                                 Show version information
+
+            Target options for skill commands:
+                  --target <claude|codex>             Agent target (default: claude)
+                  --codex                             Shortcut for --target codex
+                  --skill-dir <dir>                   Override the agent skill directory
+
+            Transcribe options:
+                  --model <parakeet|whisper>          Transcription model (default: parakeet)
+                  --source <microphone|system>        Parakeet audio-source normalization
+                  --language <auto|code>              Whisper language (default: auto)
+                  --from <time>                       Start offset; seconds, MM:SS, or HH:MM:SS
+                  --to <time>                         End offset; seconds, MM:SS, or HH:MM:SS
+                  --offset <time>                     Start offset as an alternative to --from
+                  --duration <time>                   Clip duration as an alternative to --to
+                  --streaming                         Force FluidAudio streaming transcription
+                  --timestamps <none|segment|word>    Include clean timestamps in JSON
+                  --word-timestamps                   Legacy stderr word timestamp dump
+                  --metadata                          Print transcription metadata to stderr
+                  --format <text|json|srt|vtt>        Primary output format (default: text)
+              -o, --output <file>                     Write primary output to a file
+                  --json                              Alias for --format json
+                  --output-json <file>                Also write JSON result to a file
+                  --output-srt <file>                 Also write SRT subtitles to a file
+                  --output-vtt <file>                 Also write WebVTT subtitles to a file
+                  --quiet                             Suppress progress messages on stderr
+
+            More help:
+              miniwhispercli <command> --help
+              miniwhispercli skills get core
+
+            Claude skills: \(MiniWhisperPaths.claudeSkills.path)
             """
         )
     }
diff --git a/Sources/MiniWhisperCLI/DoctorCommand.swift b/Sources/MiniWhisperCLI/DoctorCommand.swift
index 155af5e..57e6c43 100644
--- a/Sources/MiniWhisperCLI/DoctorCommand.swift
+++ b/Sources/MiniWhisperCLI/DoctorCommand.swift
@@ -92,11 +92,14 @@ enum DoctorCommand {
             )
         )
 
+        let claudeSkillDirExists = FileManager.default.fileExists(atPath: MiniWhisperPaths.claudeSkills.path)
         checks.append(
             DoctorCheck(
-                name: "Skill directory",
-                status: FileManager.default.fileExists(atPath: MiniWhisperPaths.documentSkills.path) ? "ok" : "warning",
-                detail: MiniWhisperPaths.documentSkills.path
+                name: "Claude skill directory",
+                status: claudeSkillDirExists ? "ok" : "warning",
+                detail: claudeSkillDirExists
+                    ? MiniWhisperPaths.claudeSkills.path
+                    : "Missing. `miniwhispercli skill install --apply` will create it."
             )
         )
 
diff --git a/Sources/MiniWhisperCLI/ModelsCommand.swift b/Sources/MiniWhisperCLI/ModelsCommand.swift
index 6433a7a..2fa693a 100644
--- a/Sources/MiniWhisperCLI/ModelsCommand.swift
+++ b/Sources/MiniWhisperCLI/ModelsCommand.swift
@@ -51,7 +51,7 @@ enum ModelsCommand {
         let rest = Array(arguments.dropFirst())
 
         switch subcommand {
-        case "-h", "--help", "help":
+        case "-h", "--help":
             printHelp()
             return 0
         case "status":
diff --git a/Sources/MiniWhisperCLI/Paths.swift b/Sources/MiniWhisperCLI/Paths.swift
index 9ff6904..733ce16 100644
--- a/Sources/MiniWhisperCLI/Paths.swift
+++ b/Sources/MiniWhisperCLI/Paths.swift
@@ -38,26 +38,25 @@ enum MiniWhisperPaths {
         whisperModels.appendingPathComponent("ggml-silero-v6.2.0.bin")
     }
 
-    static var documentSkills: URL {
+    static var claudeSkills: URL {
         FileManager.default.homeDirectoryForCurrentUser
-            .appendingPathComponent("Documents", isDirectory: true)
-            .appendingPathComponent("MiniWhisper", isDirectory: true)
+            .appendingPathComponent(".claude", isDirectory: true)
             .appendingPathComponent("skills", isDirectory: true)
     }
 
-    static var coreSkillCopy: URL {
-        documentSkills.appendingPathComponent(CoreSkill.directoryName, isDirectory: true)
-    }
-
-    static var claudeSkills: URL {
+    static var codexSkills: URL {
         FileManager.default.homeDirectoryForCurrentUser
-            .appendingPathComponent(".claude", isDirectory: true)
+            .appendingPathComponent(".codex", isDirectory: true)
             .appendingPathComponent("skills", isDirectory: true)
     }
 
     static var coreSkillClaudeInstall: URL {
         claudeSkills.appendingPathComponent(CoreSkill.directoryName, isDirectory: true)
     }
+
+    static var coreSkillCodexInstall: URL {
+        codexSkills.appendingPathComponent(CoreSkill.directoryName, isDirectory: true)
+    }
 }
 
 struct PathsOutput: Encodable {
@@ -70,8 +69,10 @@ struct PathsOutput: Encodable {
     let whisperModelInstalled: Bool
     let whisperVADModel: String
     let whisperVADModelInstalled: Bool
-    let documentSkills: String
     let claudeSkills: String
+    let claudeSkill: String
+    let codexSkills: String
+    let codexSkill: String
 
     enum CodingKeys: String, CodingKey {
         case executable
@@ -83,8 +84,10 @@ struct PathsOutput: Encodable {
         case whisperModelInstalled = "whisper_model_installed"
         case whisperVADModel = "whisper_vad_model"
         case whisperVADModelInstalled = "whisper_vad_model_installed"
-        case documentSkills = "document_skills"
         case claudeSkills = "claude_skills"
+        case claudeSkill = "claude_skill"
+        case codexSkills = "codex_skills"
+        case codexSkill = "codex_skill"
     }
 }
 
@@ -112,8 +115,10 @@ enum PathsCommand {
             whisperModelInstalled: FileManager.default.fileExists(atPath: MiniWhisperPaths.whisperModel.path),
             whisperVADModel: MiniWhisperPaths.whisperVADModel.path,
             whisperVADModelInstalled: FileManager.default.fileExists(atPath: MiniWhisperPaths.whisperVADModel.path),
-            documentSkills: MiniWhisperPaths.documentSkills.path,
-            claudeSkills: MiniWhisperPaths.claudeSkills.path
+            claudeSkills: MiniWhisperPaths.claudeSkills.path,
+            claudeSkill: MiniWhisperPaths.coreSkillClaudeInstall.path,
+            codexSkills: MiniWhisperPaths.codexSkills.path,
+            codexSkill: MiniWhisperPaths.coreSkillCodexInstall.path
         )
 
         if emitJSON {
@@ -136,8 +141,10 @@ enum PathsCommand {
             MiniWhisper Whisper models: \(output.miniWhisperWhisperModels)
             Whisper model: \(status(output.whisperModelInstalled)) \(output.whisperModel)
             Whisper VAD model: \(status(output.whisperVADModelInstalled)) \(output.whisperVADModel)
-            Document skills: \(output.documentSkills)
             Claude skills: \(output.claudeSkills)
+            Claude discovery skill: \(output.claudeSkill)
+            Codex skills: \(output.codexSkills)
+            Codex discovery skill: \(output.codexSkill)
             """
         )
         return 0
diff --git a/Sources/MiniWhisperCLI/SkillsCommand.swift b/Sources/MiniWhisperCLI/SkillsCommand.swift
index e0c47de..865c82d 100644
--- a/Sources/MiniWhisperCLI/SkillsCommand.swift
+++ b/Sources/MiniWhisperCLI/SkillsCommand.swift
@@ -1,30 +1,58 @@
 import Foundation
 
+struct RuntimeSkillInfo: Encodable {
+    let name: String
+    let description: String
+}
+
+enum RuntimeSkills {
+    static let visible = [
+        RuntimeSkillInfo(
+            name: "core",
+            description: "Local transcription routing, model choice, output artifacts, and diagnostics"
+        )
+    ]
+
+    static var names: [String] {
+        visible.map { $0.name }
+    }
+
+    static func markdown(named name: String) -> String? {
+        switch name {
+        case "core": return CoreSkill.text
+        default: return nil
+        }
+    }
+}
+
 enum CoreSkill {
-    static let directoryName = "miniwhisper-core"
+    static let directoryName = "miniwhisper"
     static let managedMarkerFileName = ".miniwhisper-managed-skill"
     static let managedMarkerText = "miniwhispercli managed discovery stub\n"
 
     static let discoveryStub =
         """
         ---
-        name: miniwhisper-core
-        description: Use MiniWhisper CLI for local audio transcription with Parakeet or Whisper. Use when the user asks to transcribe a local audio file with MiniWhisper, Parakeet, Whisper, or local multilingual speech-to-text.
+        name: miniwhisper
+        description: MiniWhisper automation via the `miniwhispercli` CLI. Use when the user asks to work with local audio transcription, Parakeet, Whisper, speech-to-text, transcripts, subtitles, or timestamped local audio files. This stub points at the CLI's own runtime guides so instructions always match the installed version.
         ---
 
-        # MiniWhisper Core
-
-        Use MiniWhisper CLI when the user asks to transcribe a local audio file with MiniWhisper, Parakeet, or local Whisper.
-
-        Before transcribing, run:
+        # miniwhisper discovery stub
 
-        `miniwhispercli skills get core`
+        Start here:
+          miniwhispercli skills get core
+          miniwhispercli skills list --json
 
-        That command prints the version-matched workflow for the installed CLI, including when to choose Parakeet versus Whisper.
+        Version-matched guidance lives in the installed binary.
         """
 
     static let text =
         """
+        ---
+        name: miniwhisper-core
+        description: Runtime guidance for MiniWhisper CLI local audio transcription with Parakeet and Whisper.
+        ---
+
         # MiniWhisper Core
 
         Use MiniWhisper CLI when the user asks to transcribe a local audio file with MiniWhisper, Parakeet, or local Whisper.
@@ -35,7 +63,7 @@ enum CoreSkill {
         2. Choose the model from the language and user request.
         3. Choose the output shape based on the requested artifact.
         4. Run `miniwhispercli transcribe <audio>` with the smallest flag set that satisfies the request.
-        5. Use the diagnostics/setup commands only if transcription fails or model readiness is uncertain.
+        5. Use diagnostics/setup commands only if transcription fails or model readiness is uncertain.
 
         ## Model Routing
 
@@ -130,19 +158,35 @@ enum CoreSkill {
         """
 }
 
+struct SkillsListOutput: Encodable {
+    let ok: Bool
+    let skills: [RuntimeSkillInfo]
+}
+
+struct SkillsGetOutput: Encodable {
+    let ok: Bool
+    let name: String
+    let markdown: String
+}
+
 enum SkillsCommand {
     static func run(arguments: [String]) -> Int32 {
         guard let subcommand = arguments.first else {
+            return list(arguments: [])
+        }
+
+        if subcommand == "-h" || subcommand == "--help" {
             printHelp()
             return 0
         }
 
+        if subcommand.hasPrefix("-") {
+            return list(arguments: arguments)
+        }
+
         let rest = Array(arguments.dropFirst())
 
         switch subcommand {
-        case "-h", "--help", "help":
-            printHelp()
-            return 0
         case "list":
             return list(arguments: rest)
         case "get":
@@ -154,6 +198,11 @@ enum SkillsCommand {
     }
 
     private static func list(arguments: [String]) -> Int32 {
+        if arguments.contains("-h") || arguments.contains("--help") {
+            printHelp()
+            return 0
+        }
+
         let emitJSON = arguments.contains("--json")
         let unknown = arguments.first { $0 != "--json" }
         if let unknown {
@@ -162,75 +211,56 @@ enum SkillsCommand {
         }
 
         if emitJSON {
-            Console.out("{\"skills\":[\"core\"]}")
-        } else {
-            Console.out("core")
-        }
-        return 0
-    }
-
-    private static func get(arguments: [String]) -> Int32 {
-        guard arguments.count == 1 else {
-            Console.error("Usage: miniwhispercli skills get core")
-            return 2
-        }
-
-        guard arguments[0] == "core" else {
-            Console.error("Unknown skill: \(arguments[0])")
-            return 2
+            do {
+                Console.out(try JSONPrinter.string(from: SkillsListOutput(ok: true, skills: RuntimeSkills.visible)))
+                return 0
+            } catch {
+                Console.error(error.localizedDescription)
+                return 1
+            }
         }
 
-        Console.out(CoreSkill.text)
+        Console.out(renderSkillsList(RuntimeSkills.visible))
         return 0
     }
 
-    private static func printHelp() {
-        Console.out(
-            """
-            Usage:
-              miniwhispercli skills list [--json]
-              miniwhispercli skills get core
-            """
-        )
-    }
-}
-
-enum SkillCommand {
-    static func run(arguments: [String]) -> Int32 {
-        guard let subcommand = arguments.first else {
-            return status(arguments: [])
+    private static func get(arguments: [String]) -> Int32 {
+        var emitJSON = false
+        var name: String?
+
+        for argument in arguments {
+            if argument == "--json" {
+                emitJSON = true
+            } else if argument.hasPrefix("-") {
+                Console.error("Unknown skills get option: \(argument)")
+                return 2
+            } else if name == nil {
+                name = argument
+            } else {
+                Console.error("Unexpected extra argument: \(argument)")
+                Console.error("Usage: miniwhispercli skills get <name> [--json]")
+                return 2
+            }
         }
 
-        let rest = Array(arguments.dropFirst())
-
-        switch subcommand {
-        case "-h", "--help", "help":
-            printHelp()
-            return 0
-        case "status":
-            return status(arguments: rest)
-        case "install":
-            return install(arguments: rest)
-        case "uninstall":
-            return uninstall(arguments: rest)
-        default:
-            Console.error("Unknown skill command: \(subcommand)")
+        guard let name else {
+            Console.error("Missing skill name. Available: \(RuntimeSkills.names.joined(separator: ", "))")
+            Console.error("Usage: miniwhispercli skills get <name>")
+            Console.error("Examples:")
+            Console.error("  miniwhispercli skills list")
+            Console.error("  miniwhispercli skills get core")
             return 2
         }
-    }
 
-    private static func status(arguments: [String]) -> Int32 {
-        let emitJSON = arguments.contains("--json")
-        let unknown = arguments.first { $0 != "--json" }
-        if let unknown {
-            Console.error("Unknown skill status option: \(unknown)")
+        guard let markdown = RuntimeSkills.markdown(named: name) else {
+            Console.error("Unknown skill: \(name). Available: \(RuntimeSkills.names.joined(separator: ", "))")
+            Console.error("Try: miniwhispercli skills list")
             return 2
         }
 
-        let status = SkillStatus.current()
         if emitJSON {
             do {
-                Console.out(try JSONPrinter.string(from: status))
+                Console.out(try JSONPrinter.string(from: SkillsGetOutput(ok: true, name: name, markdown: markdown)))
                 return 0
             } catch {
                 Console.error(error.localizedDescription)
@@ -238,163 +268,236 @@ enum SkillCommand {
             }
         }
 
-        Console.out(
-            """
-            MiniWhisper skill status
-
-            Target: \(status.target)
-            Strategy: \(status.strategy)
-            Skill path: \(status.skillPath)
-            State: \(status.state)
-            Repairable: \(status.repairable ? "yes" : "no")
-            Runtime guidance: \(status.runtimeGuidanceCommand)
-
-            Next:
-              \(status.nextCommand)
-            """
-        )
+        Console.write(markdown)
+        if !markdown.hasSuffix("\n") {
+            Console.out()
+        }
         return 0
     }
 
-    private static func install(arguments: [String]) -> Int32 {
-        guard arguments.isEmpty else {
-            Console.error("Usage: miniwhispercli skill install")
-            return 2
+    private static func renderSkillsList(_ skills: [RuntimeSkillInfo]) -> String {
+        let nameWidth = max("NAME".count, skills.map { $0.name.count }.max() ?? 0)
+        let header = "  \(pad("NAME", to: nameWidth))  DESCRIPTION"
+        let separator = "  \(String(repeating: "-", count: nameWidth))  -----------"
+        let rows = skills.map { skill in
+            "  \(pad(skill.name, to: nameWidth))  \(skill.description)"
         }
+        let next = skillsListNextCommands(skills).map { "  \($0)" }
 
-        do {
-            try SkillInstaller.install()
-            Console.out("Installed MiniWhisper core discovery skill.")
-            Console.out("Claude skill: \(MiniWhisperPaths.coreSkillClaudeInstall.path)")
-            Console.out("Runtime guidance: miniwhispercli skills get core")
-            return 0
-        } catch {
-            Console.error(error.localizedDescription)
-            return 1
-        }
+        return (["Skills", "", header, separator] + rows + ["", "Next:"] + next)
+            .joined(separator: "\n")
     }
 
-    private static func uninstall(arguments: [String]) -> Int32 {
-        guard arguments.isEmpty else {
-            Console.error("Usage: miniwhispercli skill uninstall")
-            return 2
-        }
+    private static func skillsListNextCommands(_ skills: [RuntimeSkillInfo]) -> [String] {
+        let available = Set(skills.map { $0.name })
+        return ["core", "setup", "auth"]
+            .filter { available.contains($0) }
+            .map { "miniwhispercli skills get \($0)" }
+    }
 
-        do {
-            try SkillInstaller.uninstall()
-            Console.out("Uninstalled MiniWhisper core skill.")
-            return 0
-        } catch {
-            Console.error(error.localizedDescription)
-            return 1
-        }
+    private static func pad(_ value: String, to width: Int) -> String {
+        let count = value.count
+        guard count < width else { return value }
+        return value + String(repeating: " ", count: width - count)
     }
 
     private static func printHelp() {
         Console.out(
             """
             Usage:
-              miniwhispercli skill
-              miniwhispercli skill status [--json]
-              miniwhispercli skill install
-              miniwhispercli skill uninstall
+              miniwhispercli skills
+              miniwhispercli skills list [--json]
+              miniwhispercli skills get <name> [--json]
 
-            Installs a managed Claude Code discovery stub at:
-              \(MiniWhisperPaths.coreSkillClaudeInstall.path)
+            Examples:
+              miniwhispercli skills list
+              miniwhispercli skills list --json
+              miniwhispercli skills get core
             """
         )
     }
 }
 
-struct SkillStatus: Encodable {
-    let target: String
+struct SkillTarget: Encodable {
+    let name: String
+    let source: String
+    let skillDir: String
+
+    var skillPath: String {
+        URL(fileURLWithPath: skillDir)
+            .appendingPathComponent(CoreSkill.directoryName, isDirectory: true)
+            .path
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case name
+        case source
+        case skillDir = "skill_dir"
+    }
+}
+
+struct SkillCommandOptions {
+    var emitJSON = false
+    var apply = false
+    var dryRun = false
+    var codex = false
+    var targetName: String?
+    var skillDir: String?
+
+    func resolvedTarget() throws -> SkillTarget {
+        if let skillDir, !skillDir.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            let url = PathResolver.fileURL(for: skillDir)
+            return SkillTarget(name: "custom", source: "flag", skillDir: url.path)
+        }
+
+        var target = targetName ?? "claude"
+        if codex {
+            if targetName == "claude" {
+                throw CLIError.usage("--target claude and --codex contradict; choose one target.")
+            }
+            target = "codex"
+        }
+
+        switch target {
+        case "claude":
+            if let override = ProcessInfo.processInfo.environment["MINIWHISPER_CLAUDE_SKILL_DIR"],
+               !override.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                return SkillTarget(name: "claude", source: "env:MINIWHISPER_CLAUDE_SKILL_DIR", skillDir: PathResolver.fileURL(for: override).path)
+            }
+            return SkillTarget(name: "claude", source: "default", skillDir: MiniWhisperPaths.claudeSkills.path)
+        case "codex":
+            if let override = ProcessInfo.processInfo.environment["MINIWHISPER_CODEX_SKILL_DIR"],
+               !override.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                return SkillTarget(name: "codex", source: "env:MINIWHISPER_CODEX_SKILL_DIR", skillDir: PathResolver.fileURL(for: override).path)
+            }
+            return SkillTarget(name: "codex", source: "default", skillDir: MiniWhisperPaths.codexSkills.path)
+        default:
+            throw CLIError.usage("Unknown skill target: \(target). Expected claude or codex.")
+        }
+    }
+}
+
+struct SkillStatusOutput: Encodable {
+    let ok: Bool
+    let target: SkillTarget
     let strategy: String
     let skillPath: String
+    let skillFile: String
     let markerPath: String
     let state: String
     let installed: Bool
+    let managed: Bool
     let repairable: Bool
     let needsRefresh: Bool
     let runtimeGuidanceCommand: String
+    let dryRun: Bool?
+    let wouldWrite: Bool?
+    let removed: Bool?
+    let nextActions: [String]
 
     enum CodingKeys: String, CodingKey {
+        case ok
         case target
         case strategy
         case skillPath = "skill_path"
+        case skillFile = "skill_file"
         case markerPath = "marker_path"
         case state
         case installed
+        case managed
         case repairable
         case needsRefresh = "needs_refresh"
         case runtimeGuidanceCommand = "runtime_guidance_command"
+        case dryRun = "dry_run"
+        case wouldWrite = "would_write"
+        case removed
+        case nextActions = "next_actions"
     }
 
-    static func current() -> SkillStatus {
-        let installURL = MiniWhisperPaths.coreSkillClaudeInstall
+    static func current(target: SkillTarget, dryRun: Bool? = nil, removed: Bool? = nil) -> SkillStatusOutput {
+        let installURL = URL(fileURLWithPath: target.skillPath)
         let state = SkillInstallState.current(at: installURL)
-        return SkillStatus(
-            target: "Claude Code",
+        let installed = state.installed
+        let repairable = state.repairable
+        let needsRefresh = state.needsRefresh
+        let commandSuffix = targetCommandSuffix(for: target)
+        let nextActions: [String]
+
+        if !repairable {
+            nextActions = ["Move the existing skill path, then run miniwhispercli skill status\(commandSuffix)."]
+        } else if !installed || needsRefresh {
+            nextActions = ["miniwhispercli skill install\(commandSuffix) --apply"]
+        } else {
+            nextActions = ["miniwhispercli skills get core"]
+        }
+
+        return SkillStatusOutput(
+            ok: true,
+            target: target,
             strategy: "managed_discovery_stub",
             skillPath: installURL.path,
+            skillFile: installURL.appendingPathComponent("SKILL.md").path,
             markerPath: installURL.appendingPathComponent(CoreSkill.managedMarkerFileName).path,
             state: state.rawValue,
-            installed: state.installed,
-            repairable: state.repairable,
-            needsRefresh: state.needsRefresh,
-            runtimeGuidanceCommand: "miniwhispercli skills get core"
+            installed: installed,
+            managed: state.managed,
+            repairable: repairable,
+            needsRefresh: needsRefresh,
+            runtimeGuidanceCommand: "miniwhispercli skills get core",
+            dryRun: dryRun,
+            wouldWrite: dryRun == true ? repairable && (!installed || needsRefresh) : nil,
+            removed: removed,
+            nextActions: nextActions
         )
     }
 
-    var nextCommand: String {
-        if !repairable {
-            return "Move the existing skill path, then run `miniwhispercli skill install`."
+    private static func targetCommandSuffix(for target: SkillTarget) -> String {
+        switch target.name {
+        case "codex":
+            return " --codex"
+        case "custom":
+            return " --skill-dir \(shellQuote(target.skillDir))"
+        default:
+            return ""
         }
-        if !installed || needsRefresh {
-            return "miniwhispercli skill install"
+    }
+
+    private static func shellQuote(_ value: String) -> String {
+        let safe = CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_./:-")
+        if value.unicodeScalars.allSatisfy({ safe.contains($0) }) {
+            return value
         }
-        return "miniwhispercli skills get core"
+        return "'" + value.replacingOccurrences(of: "'", with: "'\\''") + "'"
     }
 }
 
 private enum SkillInstallState: String {
     case missing
-    case managedStub = "managed_stub"
-    case staleManagedStub = "stale_managed_stub"
-    case legacySymlink = "legacy_symlink"
+    case managed
+    case stale
     case foreignSymlink = "foreign_symlink"
     case foreignPath = "foreign_path"
 
     var installed: Bool {
-        self == .managedStub || self == .staleManagedStub
+        self == .managed || self == .stale
+    }
+
+    var managed: Bool {
+        self == .managed || self == .stale
     }
 
     var repairable: Bool {
-        switch self {
-        case .missing, .managedStub, .staleManagedStub, .legacySymlink:
-            return true
-        case .foreignSymlink, .foreignPath:
-            return false
-        }
+        self == .missing || self == .managed || self == .stale
     }
 
     var needsRefresh: Bool {
-        self == .staleManagedStub || self == .legacySymlink
+        self == .stale
     }
 
     static func current(at url: URL) -> SkillInstallState {
         let fileManager = FileManager.default
 
-        if let destination = try? fileManager.destinationOfSymbolicLink(atPath: url.path) {
-            let destinationURL: URL
-            if destination.hasPrefix("/") {
-                destinationURL = URL(fileURLWithPath: destination)
-            } else {
-                destinationURL = url.deletingLastPathComponent().appendingPathComponent(destination)
-            }
-
-            if destinationURL.standardizedFileURL.path == MiniWhisperPaths.coreSkillCopy.standardizedFileURL.path {
-                return .legacySymlink
-            }
+        if (try? fileManager.destinationOfSymbolicLink(atPath: url.path)) != nil {
             return .foreignSymlink
         }
 
@@ -413,25 +516,237 @@ private enum SkillInstallState: String {
 
         let skillURL = url.appendingPathComponent("SKILL.md")
         let skillText = try? String(contentsOf: skillURL, encoding: .utf8)
-        return skillText == CoreSkill.discoveryStub ? .managedStub : .staleManagedStub
+        return skillText == CoreSkill.discoveryStub ? .managed : .stale
     }
 }
 
+enum SkillCommand {
+    static func run(arguments: [String]) -> Int32 {
+        guard let subcommand = arguments.first else {
+            return status(arguments: [])
+        }
+
+        if subcommand == "-h" || subcommand == "--help" {
+            printHelp()
+            return 0
+        }
+
+        if subcommand.hasPrefix("-") {
+            return status(arguments: arguments)
+        }
+
+        let rest = Array(arguments.dropFirst())
+
+        switch subcommand {
+        case "status":
+            return status(arguments: rest)
+        case "install":
+            return install(arguments: rest)
+        case "show":
+            return show(arguments: rest)
+        case "uninstall":
+            return uninstall(arguments: rest)
+        default:
+            Console.error("Unknown skill command: \(subcommand)")
+            return 2
+        }
+    }
+
+    private static func status(arguments: [String]) -> Int32 {
+        do {
+            let options = try parseOptions(arguments, allowJSON: true)
+            let target = try options.resolvedTarget()
+            let status = SkillStatusOutput.current(target: target)
+            return emitStatus(status, title: "Skill status", emitJSON: options.emitJSON)
+        } catch {
+            return report(error)
+        }
+    }
+
+    private static func install(arguments: [String]) -> Int32 {
+        do {
+            let options = try parseOptions(arguments, allowJSON: true, allowApply: true, allowDryRun: true)
+            if options.apply && options.dryRun {
+                throw CLIError.usage("--dry-run and --apply are mutually exclusive.")
+            }
+
+            let target = try options.resolvedTarget()
+            if !options.apply {
+                let status = SkillStatusOutput.current(target: target, dryRun: true)
+                return emitStatus(status, title: "Skill install preview", emitJSON: options.emitJSON)
+            }
+
+            try SkillInstaller.install(target: target)
+            let status = SkillStatusOutput.current(target: target, dryRun: false)
+            return emitStatus(status, title: "Skill install", emitJSON: options.emitJSON)
+        } catch {
+            return report(error)
+        }
+    }
+
+    private static func show(arguments: [String]) -> Int32 {
+        do {
+            let options = try parseOptions(arguments, allowJSON: true, allowTarget: false)
+            if options.emitJSON {
+                let output = SkillShowOutput(ok: true, content: CoreSkill.discoveryStub)
+                Console.out(try JSONPrinter.string(from: output))
+            } else {
+                Console.write(CoreSkill.discoveryStub)
+                if !CoreSkill.discoveryStub.hasSuffix("\n") {
+                    Console.out()
+                }
+            }
+            return 0
+        } catch {
+            return report(error)
+        }
+    }
+
+    private static func uninstall(arguments: [String]) -> Int32 {
+        do {
+            let options = try parseOptions(arguments, allowJSON: true)
+            let target = try options.resolvedTarget()
+            let removed = try SkillInstaller.uninstall(target: target)
+            let status = SkillStatusOutput.current(target: target, removed: removed)
+            return emitStatus(status, title: "Skill uninstall", emitJSON: options.emitJSON)
+        } catch {
+            return report(error)
+        }
+    }
+
+    private static func parseOptions(
+        _ arguments: [String],
+        allowJSON: Bool = false,
+        allowApply: Bool = false,
+        allowDryRun: Bool = false,
+        allowTarget: Bool = true
+    ) throws -> SkillCommandOptions {
+        var options = SkillCommandOptions()
+        var index = 0
+
+        while index < arguments.count {
+            let argument = arguments[index]
+            switch argument {
+            case "--json" where allowJSON:
+                options.emitJSON = true
+            case "--apply" where allowApply:
+                options.apply = true
+            case "--dry-run" where allowDryRun:
+                options.dryRun = true
+            case "--codex" where allowTarget:
+                options.codex = true
+            case "--target" where allowTarget:
+                index += 1
+                guard index < arguments.count else {
+                    throw CLIError.usage("Missing value for --target. Expected claude or codex.")
+                }
+                options.targetName = arguments[index]
+            case "--skill-dir" where allowTarget:
+                index += 1
+                guard index < arguments.count else {
+                    throw CLIError.usage("Missing value for --skill-dir.")
+                }
+                options.skillDir = arguments[index]
+            default:
+                throw CLIError.usage("Unknown skill option: \(argument)")
+            }
+            index += 1
+        }
+
+        if let target = options.targetName,
+           target != "claude" && target != "codex" {
+            throw CLIError.usage("Unknown skill target: \(target). Expected claude or codex.")
+        }
+
+        return options
+    }
+
+    private static func emitStatus(_ status: SkillStatusOutput, title: String, emitJSON: Bool) -> Int32 {
+        if emitJSON {
+            do {
+                Console.out(try JSONPrinter.string(from: status))
+                return 0
+            } catch {
+                Console.error(error.localizedDescription)
+                return 1
+            }
+        }
+
+        let actions = status.nextActions.map { "  \($0)" }.joined(separator: "\n")
+        let modeLine = status.dryRun == true ? "\nMode: preview; pass --apply to write files" : ""
+        Console.out(
+            """
+            \(title)
+
+            Target: \(status.target.name) (\(status.target.source))
+            Path: \(status.skillPath)
+            State: \(status.state)
+            Strategy: \(status.strategy)\(modeLine)
+
+            Next:
+            \(actions)
+            """
+        )
+        return 0
+    }
+
+    private static func report(_ error: Error) -> Int32 {
+        if case CLIError.usage(let message) = error {
+            Console.error(message)
+            Console.error("Run `miniwhispercli skill --help` for usage.")
+            return 2
+        }
+        Console.error(error.localizedDescription)
+        return 1
+    }
+
+    private static func printHelp() {
+        Console.out(
+            """
+            Usage:
+              miniwhispercli skill
+              miniwhispercli skill status [--json] [target options]
+              miniwhispercli skill install [--dry-run|--apply] [target options]
+              miniwhispercli skill show [--json]
+              miniwhispercli skill uninstall [--json] [target options]
+
+            Target options:
+              --target <claude|codex>   Agent target (default: claude)
+              --codex                   Shortcut for --target codex
+              --skill-dir <dir>         Override the agent skill directory
+
+            Examples:
+              miniwhispercli skill install
+              miniwhispercli skill install --apply
+              miniwhispercli skill status --json
+              miniwhispercli skill show
+            """
+        )
+    }
+}
+
+struct SkillShowOutput: Encodable {
+    let ok: Bool
+    let content: String
+}
+
 enum SkillInstaller {
-    static func install() throws {
+    static func install(target: SkillTarget) throws {
         let fileManager = FileManager.default
-        let installURL = MiniWhisperPaths.coreSkillClaudeInstall
+        let installURL = URL(fileURLWithPath: target.skillPath)
 
         switch SkillInstallState.current(at: installURL) {
         case .foreignSymlink, .foreignPath:
             throw CLIError.runtime("Refusing to replace unmanaged skill path: \(installURL.path)")
-        case .managedStub, .staleManagedStub, .legacySymlink:
+        case .managed:
+            return
+        case .stale:
             try fileManager.removeItem(at: installURL)
         case .missing:
             break
         }
 
-        try fileManager.createDirectory(at: MiniWhisperPaths.claudeSkills, withIntermediateDirectories: true)
+        try fileManager.createDirectory(atPath: target.skillDir, withIntermediateDirectories: true)
         try fileManager.createDirectory(at: installURL, withIntermediateDirectories: true)
 
         try CoreSkill.discoveryStub.write(
@@ -446,15 +761,17 @@ enum SkillInstaller {
         )
     }
 
-    static func uninstall() throws {
+    @discardableResult
+    static func uninstall(target: SkillTarget) throws -> Bool {
         let fileManager = FileManager.default
-        let installURL = MiniWhisperPaths.coreSkillClaudeInstall
+        let installURL = URL(fileURLWithPath: target.skillPath)
 
         switch SkillInstallState.current(at: installURL) {
-        case .managedStub, .staleManagedStub, .legacySymlink:
+        case .managed, .stale:
             try fileManager.removeItem(at: installURL)
+            return true
         case .missing:
-            return
+            return false
         case .foreignSymlink, .foreignPath:
             throw CLIError.runtime("Refusing to remove unmanaged skill path: \(installURL.path)")
         }

From 2a7520df2b479b2d5454ed096bc368ad9a7c2ffd Mon Sep 17 00:00:00 2001
From: andyhtran <76441965+andyhtran@users.noreply.github.com>
Date: Tue, 7 Jul 2026 22:27:59 -0400
Subject: [PATCH 2/2] Add Whisper word-timing alignment, timestamps skill, and
 refactored core skill

Add --align flag (whisper-token, whisper-dtw) for Whisper word-level timing
with DTW/flash-attention mutual exclusion and VAD bypass when token timestamps
are active. Extract token timings from whisper.cpp and merge into word-level
outputs. Split agent skill into core and timestamps guides. Allow --align none
as a no-op with Parakeet.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 Sources/MiniWhisperCLI/CLI.swift              |  10 +
 Sources/MiniWhisperCLI/SkillsCommand.swift    | 181 ++++++++++--------
 .../MiniWhisperCLI/TranscribeCommand.swift    |  38 +++-
 .../WhisperCLITranscriber.swift               | 176 +++++++++++++++--
 4 files changed, 314 insertions(+), 91 deletions(-)

diff --git a/Sources/MiniWhisperCLI/CLI.swift b/Sources/MiniWhisperCLI/CLI.swift
index 1b6e310..c2a5a8a 100644
--- a/Sources/MiniWhisperCLI/CLI.swift
+++ b/Sources/MiniWhisperCLI/CLI.swift
@@ -62,6 +62,7 @@ enum Help {
 
             Start here (for AI agents):
               miniwhispercli skills get core
+              miniwhispercli skills get timestamps
               miniwhispercli skills list --json
 
             Version-matched guidance. Load core first; use the JSON list for available guides.
@@ -88,6 +89,7 @@ enum Help {
 
             Start here (for AI agents):
               miniwhispercli skills get core
+              miniwhispercli skills get timestamps
               miniwhispercli skills list --json
 
             Version-matched guidance. Load core first; use the JSON list for available guides.
@@ -103,6 +105,7 @@ enum Help {
             Agent integration:
               skills list              List bundled runtime guides
               skills get core          Print the agent-facing core guide
+              skills get timestamps    Print timed-transcript guidance
               skill status             Show agent skill install status
               skill install            Preview discovery-stub install
               skill install --apply    Install the discovery stub
@@ -125,6 +128,7 @@ enum Help {
               miniwhispercli --help --full
               miniwhispercli skills list
               miniwhispercli skills get core
+              miniwhispercli skills get timestamps
             """
         )
     }
@@ -167,6 +171,8 @@ enum Help {
                   --model <parakeet|whisper>          Transcription model (default: parakeet)
                   --source <microphone|system>        Parakeet audio-source normalization
                   --language <auto|code>              Whisper language (default: auto)
+                  --align <none|whisper-token|whisper-dtw>
+                                                          Whisper word-timing source
                   --from <time>                       Start offset; seconds, MM:SS, or HH:MM:SS
                   --to <time>                         End offset; seconds, MM:SS, or HH:MM:SS
                   --offset <time>                     Start offset as an alternative to --from
@@ -186,6 +192,7 @@ enum Help {
             More help:
               miniwhispercli <command> --help
               miniwhispercli skills get core
+              miniwhispercli skills get timestamps
 
             Claude skills: \(MiniWhisperPaths.claudeSkills.path)
             """
@@ -206,6 +213,8 @@ enum Help {
               --source <microphone|system>
                                         Parakeet audio-source normalization (default: microphone)
               --language <auto|code>     Whisper language (default: auto)
+              --align <none|whisper-token|whisper-dtw>
+                                        Whisper word-timing source; non-none implies --timestamps word
               --from <time>              Start offset; accepts seconds, MM:SS, or HH:MM:SS
               --to <time>                End offset; accepts seconds, MM:SS, or HH:MM:SS
               --offset <time>            Start offset as an alternative to --from
@@ -229,6 +238,7 @@ enum Help {
               miniwhispercli transcribe audio.wav
               miniwhispercli transcribe audio.wav --model whisper
               miniwhispercli transcribe audio.wav --model whisper --language ja --json
+              miniwhispercli transcribe audio.wav --model whisper --align whisper-dtw --json
               miniwhispercli transcribe audio.wav --format json -o out.json --quiet
               miniwhispercli transcribe audio.wav --format srt -o out.srt
               miniwhispercli transcribe audio.wav --from 01:20 --duration 50
diff --git a/Sources/MiniWhisperCLI/SkillsCommand.swift b/Sources/MiniWhisperCLI/SkillsCommand.swift
index 865c82d..f92db21 100644
--- a/Sources/MiniWhisperCLI/SkillsCommand.swift
+++ b/Sources/MiniWhisperCLI/SkillsCommand.swift
@@ -10,6 +10,10 @@ enum RuntimeSkills {
         RuntimeSkillInfo(
             name: "core",
             description: "Local transcription routing, model choice, output artifacts, and diagnostics"
+        ),
+        RuntimeSkillInfo(
+            name: "timestamps",
+            description: "Timed transcripts, subtitles, captions, overlays, and edit-boundary timing"
         )
     ]
 
@@ -20,6 +24,7 @@ enum RuntimeSkills {
     static func markdown(named name: String) -> String? {
         switch name {
         case "core": return CoreSkill.text
+        case "timestamps": return TimestampsSkill.text
         default: return nil
         }
     }
@@ -41,6 +46,7 @@ enum CoreSkill {
 
         Start here:
           miniwhispercli skills get core
+          miniwhispercli skills get timestamps  # for subtitles, captions, overlays, or edit timing
           miniwhispercli skills list --json
 
         Version-matched guidance lives in the installed binary.
@@ -55,106 +61,127 @@ enum CoreSkill {
 
         # MiniWhisper Core
 
-        Use MiniWhisper CLI when the user asks to transcribe a local audio file with MiniWhisper, Parakeet, or local Whisper.
+        Use MiniWhisper CLI for local transcription of an audio file.
 
         ## Core Workflow
 
-        1. Confirm the audio file path exists before running transcription.
+        1. Confirm the audio file path exists.
         2. Choose the model from the language and user request.
-        3. Choose the output shape based on the requested artifact.
-        4. Run `miniwhispercli transcribe <audio>` with the smallest flag set that satisfies the request.
-        5. Use diagnostics/setup commands only if transcription fails or model readiness is uncertain.
+        3. Run `miniwhispercli transcribe <audio>` with the smallest flag set that satisfies the request.
+        4. Treat stdout or the requested output file as the transcript artifact.
 
         ## Model Routing
 
-        Default to Parakeet v3:
-
-        - Use `miniwhispercli transcribe <audio>` for English and supported European languages.
-        - Parakeet v3 is the fast default and supports 25 European languages with automatic language detection.
-        - If Parakeet is missing, `miniwhispercli models install parakeet` installs it. First transcription also downloads it automatically.
+        Use Parakeet for speed. Use Whisper Turbo when every word needs to make it through.
 
-        Use Whisper when broader language coverage matters:
+        Default to Parakeet v3 for fast drafts, notes, search, rough summaries, and low-risk local transcription. Parakeet supports 25 European languages with automatic language detection.
 
-        - Use `miniwhispercli transcribe <audio> --model whisper` for non-European languages or when the user asks for multilingual/broad language coverage.
-        - Whisper uses `whisper-large-v3-turbo` through whisper.cpp and defaults to `--language auto`.
-        - Pass `--language <code>` only when the user gives a known language and wants to avoid auto-detection.
-        - If Whisper is missing, `miniwhispercli models install whisper` installs the model and VAD helper. First Whisper transcription also downloads them automatically.
+        Use Whisper Turbo for published transcripts, quotes, handoffs, edit decisions, broad language coverage, or anything where dropped words are unacceptable. Whisper uses `whisper-large-v3-turbo` through whisper.cpp and defaults to `--language auto`.
 
-        ## Transcription Choices
+        ## Common Commands
 
-        - Plain transcript for chat or clipboard use:
+        - Fast plain transcript:
           `miniwhispercli transcribe <audio>`
-        - Non-European or broad multilingual transcription:
+        - Word-complete transcript:
           `miniwhispercli transcribe <audio> --model whisper`
-        - Structured result for agent parsing:
-          `miniwhispercli transcribe <audio> --format json`
-        - Save structured result as an artifact:
+        - JSON artifact:
           `miniwhispercli transcribe <audio> --format json -o <file> --quiet`
-        - Include word timings and performance details:
-          `miniwhispercli transcribe <audio> --timestamps word --metadata --format json -o <file>`
-        - Transcribe only part of a longer file:
+        - Transcribe part of a file:
           `miniwhispercli transcribe <audio> --from 01:20 --duration 50`
-        - Save subtitles:
-          `miniwhispercli transcribe <audio> --format srt -o <file>`
 
-        ## Advanced Source Flag
+        ## Output Contract
 
-        `--source` is Parakeet-only. It does not choose an input device and does not capture audio. The CLI always transcribes the file path passed to `transcribe`.
+        Treat stdout as the user-requested artifact. Progress, metadata, diagnostics, and native library logs may go to stderr; do not parse stderr as transcript content.
 
-        - `--source microphone` is the default and matches MiniWhisper app behavior.
-        - `--source system` matches FluidAudio's file-transcription default more closely.
+        Prefer `--format json -o <file> --quiet` when creating a JSON artifact.
 
-        Do not change `--source` unless comparing MiniWhisper output against FluidAudio behavior. Do not pass `--source` with `--model whisper`.
+        ## Timed Outputs
 
-        ## Output Rules
+        For timestamps, word timings, SRT/VTT, captions, overlays, or edit-boundary candidates, load:
 
-        Treat stdout as the user-requested artifact. Progress, word timings, metadata, and diagnostics are stderr-only unless `--json` is explicitly requested.
-        Use `--json` when the agent needs the structured result on stdout.
-        Prefer `--format json -o <file> --quiet` when creating a JSON artifact.
-        `--output-json <file>` is a compatibility sidecar that also writes JSON while preserving the primary output.
-        Native transcription libraries may still emit diagnostics to stderr; do not parse stderr as transcript content.
-
-        Use `--timestamps segment` or `--timestamps word` for clean timestamp data in JSON. Avoid `--word-timestamps` unless the user specifically wants the legacy stderr dump.
-
-        Use `--format srt` or `--format vtt` for subtitle artifacts. `--output-srt <file>` and `--output-vtt <file>` can create subtitle sidecars while keeping the primary output as text or JSON.
-
-        Time ranges accept seconds, `MM:SS`, or `HH:MM:SS`:
-
-        - `--from 01:20 --to 02:10`
-        - `--offset 80 --duration 50`
-
-        JSON output has this shape:
-
-        ```json
-        {
-          "audio_file": "/path/to/audio.wav",
-          "engine": "parakeet",
-          "mode": "batch",
-          "model_version": "v3",
-          "model": "parakeet-tdt-v3",
-          "source": "microphone",
-          "language": "auto",
-          "range": null,
-          "text": "transcribed text",
-          "duration_seconds": 3.2,
-          "processing_time_seconds": 0.6,
-          "rtfx": 5.3,
-          "confidence": 0.97,
-          "confidence_available": true,
-          "segments": [],
-          "word_timings": []
-        }
+        `miniwhispercli skills get timestamps`
+
+        Prefer Whisper Turbo for final timed artifacts.
+
+        ## Setup And Diagnostics
+
+        If transcription fails or model readiness is uncertain, run `miniwhispercli doctor --json` or `miniwhispercli models status --json`.
+
+        ## Help
+
+        For the full command surface, run:
+
+        `miniwhispercli transcribe --help`
+        """
+}
+
+enum TimestampsSkill {
+    static let text =
+        """
+        ---
+        name: miniwhisper-timestamps
+        description: Runtime guidance for MiniWhisper timed transcripts, subtitles, captions, overlays, and edit-boundary timing.
+        ---
+
+        # MiniWhisper Timestamps
+
+        Load this after `miniwhispercli skills get core` when the output needs timing data: JSON segments, JSON words, SRT/VTT subtitles, captions, overlays, clips, or edit-boundary candidates.
+
+        ## Model Routing
+
+        Use Parakeet for speed. Use Whisper Turbo when every word needs to make it through.
+
+        - Prefer Whisper Turbo for subtitles, captions, published transcripts, quotes, edit decisions, overlays, timeline handoffs, and any source-of-truth timed artifact.
+        - Use Parakeet for quick drafts, rough timing, search, and low-risk local transcription.
+        - If Parakeet is explicitly requested for a durable timed artifact, verify the ending with a tail check before handing it off.
+
+        ## Timestamp Commands
+
+        - Segment-timed JSON:
+          `miniwhispercli transcribe <audio> --model whisper --timestamps segment --format json -o <file>`
+        - Word-timed JSON:
+          `miniwhispercli transcribe <audio> --model whisper --timestamps word --format json -o <file>`
+        - Whisper DTW token timing experiment:
+          `miniwhispercli transcribe <audio> --model whisper --align whisper-dtw --format json -o <file>`
+        - SRT subtitles:
+          `miniwhispercli transcribe <audio> --model whisper --format srt -o <file>`
+        - WebVTT subtitles:
+          `miniwhispercli transcribe <audio> --model whisper --format vtt -o <file>`
+        - Timed slice of a longer file:
+          `miniwhispercli transcribe <audio> --model whisper --from 01:20 --duration 50 --timestamps word --format json -o <file>`
+
+        Use `--output-json <file>`, `--output-srt <file>`, or `--output-vtt <file>` when a sidecar is needed while keeping the primary output as text or another format.
+
+        ## Parakeet Tail Check
+
+        Parakeet can occasionally omit the final words of a full-file transcription even when a tail-only retry can hear them. For any durable Parakeet transcript, check the ending:
+
+        ```bash
+        miniwhispercli transcribe <audio> --model parakeet -o full.txt
+        miniwhispercli transcribe <audio> --model parakeet --from <tail-start-time> -o tail.txt
         ```
 
-        ## Diagnostics And Setup
+        Compare the final sentence. If `tail.txt` contains words missing from `full.txt`, use Whisper Turbo for the final artifact or repair the Parakeet transcript only after explicit review.
+
+        ## Timing Safety
+
+        Treat word timestamps as edit-boundary candidates, not frame-safe cut points.
+
+        - For captions and overlays, word/segment timestamps are usually enough, then review the rendered result.
+        - For edit cuts, validate boundaries against silence, RMS/energy, and the frame grid before cutting.
+        - Do not cut solely because a word timestamp says speech ended; keep a small acoustic handle unless the downstream editor explicitly wants a hard boundary.
+        - Preserve the original audio timeline for timing work. Avoid preprocessing that removes or compacts silence before generating timestamps.
+        - If a command uses `--from`, `--to`, or `--duration`, keep the range metadata with the artifact so later tools can map the timed result back to the source file.
+
+        ## Handoff Checklist
 
-        Use these only when setup is uncertain or a transcription command fails:
+        Report:
 
-        - `miniwhispercli models status --json` checks installed model readiness.
-        - `miniwhispercli models install parakeet` installs the default fast local model.
-        - `miniwhispercli models install whisper` installs optional broad multilingual support.
-        - `miniwhispercli doctor --json` checks local environment problems.
-        - `miniwhispercli transcribe --help` shows the full flag list when a needed option is unclear.
+        - command run,
+        - model used,
+        - output files written,
+        - whether a Parakeet tail check was needed or performed,
+        - any uncertain words or timing spans that need human review.
         """
 }
 
@@ -249,6 +276,7 @@ enum SkillsCommand {
             Console.error("Examples:")
             Console.error("  miniwhispercli skills list")
             Console.error("  miniwhispercli skills get core")
+            Console.error("  miniwhispercli skills get timestamps")
             return 2
         }
 
@@ -290,7 +318,7 @@ enum SkillsCommand {
 
     private static func skillsListNextCommands(_ skills: [RuntimeSkillInfo]) -> [String] {
         let available = Set(skills.map { $0.name })
-        return ["core", "setup", "auth"]
+        return ["core", "timestamps"]
             .filter { available.contains($0) }
             .map { "miniwhispercli skills get \($0)" }
     }
@@ -313,6 +341,7 @@ enum SkillsCommand {
               miniwhispercli skills list
               miniwhispercli skills list --json
               miniwhispercli skills get core
+              miniwhispercli skills get timestamps
             """
         )
     }
diff --git a/Sources/MiniWhisperCLI/TranscribeCommand.swift b/Sources/MiniWhisperCLI/TranscribeCommand.swift
index b43e69f..662e1c0 100644
--- a/Sources/MiniWhisperCLI/TranscribeCommand.swift
+++ b/Sources/MiniWhisperCLI/TranscribeCommand.swift
@@ -26,6 +26,8 @@ struct TranscribeOptions {
     var sourceSpecified = false
     var whisperLanguage: WhisperLanguageChoice = .auto
     var whisperLanguageSpecified = false
+    var whisperAlignmentMode: WhisperAlignmentMode = .none
+    var whisperAlignmentModeSpecified = false
     var forceStreaming = false
     var timestampMode: TimestampMode = .none
     var legacyWordTimestamps = false
@@ -146,6 +148,13 @@ enum TranscribeCommand {
                 options.whisperLanguageSpecified = true
             case "--streaming":
                 options.forceStreaming = true
+            case "--align":
+                let value = try value(after: argument, in: arguments, at: &index)
+                options.whisperAlignmentMode = try WhisperAlignmentMode.parse(value)
+                options.whisperAlignmentModeSpecified = true
+                if options.whisperAlignmentMode != .none {
+                    options.timestampMode = .word
+                }
             case "--word-timestamps":
                 options.timestampMode = .word
                 options.legacyWordTimestamps = true
@@ -234,6 +243,15 @@ enum TranscribeCommand {
             }
         }
 
+        if options.model == .parakeet,
+           options.whisperAlignmentModeSpecified,
+           options.whisperAlignmentMode != .none {
+            throw CLIError.usage("`--align` applies only to `--model whisper`.")
+        }
+        if options.whisperAlignmentModeSpecified, options.whisperAlignmentMode != .none {
+            options.timestampMode = .word
+        }
+
         return options
     }
 
@@ -373,7 +391,7 @@ enum TranscribeCommand {
                 segments: jsonSegments,
                 subtitleSegments: subtitleSegments,
                 wordTimings: jsonWordTimings,
-                timingsConfirmed: nil
+                timingsConfirmed: jsonWordTimings.isEmpty ? nil : true
             )
         } catch {
             await manager.cleanup()
@@ -390,8 +408,13 @@ enum TranscribeCommand {
         let result = try await WhisperCLITranscriber.transcribe(
             audioURL: audioURL,
             language: options.whisperLanguage,
+            alignmentMode: effectiveWhisperAlignmentMode(for: options),
             quiet: options.quiet
         )
+        let jsonWordTimings = options.timestampMode == .word ? result.wordTimings : []
+        let subtitleSegments = jsonWordTimings.isEmpty
+            ? result.segments
+            : SubtitleCueBuilder.cues(text: result.text, duration: result.audioDuration, words: jsonWordTimings)
 
         return TranscriptionJSONOutput(
             audioFile: displayAudioURL.path,
@@ -411,12 +434,19 @@ enum TranscribeCommand {
             segments: options.timestampMode == .segment || options.timestampMode == .word
                 ? result.segments
                 : [],
-            subtitleSegments: result.segments,
-            wordTimings: [],
-            timingsConfirmed: nil
+            subtitleSegments: subtitleSegments,
+            wordTimings: jsonWordTimings,
+            timingsConfirmed: jsonWordTimings.isEmpty ? nil : true
         )
     }
 
+    private static func effectiveWhisperAlignmentMode(for options: TranscribeOptions) -> WhisperAlignmentMode {
+        if options.whisperAlignmentModeSpecified {
+            return options.whisperAlignmentMode
+        }
+        return options.timestampMode == .word ? .token : .none
+    }
+
     private static func value(after option: String, in arguments: [String], at index: inout Int) throws -> String {
         let valueIndex = index + 1
         guard valueIndex < arguments.count else {
diff --git a/Sources/MiniWhisperCLI/WhisperCLITranscriber.swift b/Sources/MiniWhisperCLI/WhisperCLITranscriber.swift
index d8f47b9..d4157fd 100644
--- a/Sources/MiniWhisperCLI/WhisperCLITranscriber.swift
+++ b/Sources/MiniWhisperCLI/WhisperCLITranscriber.swift
@@ -27,6 +27,30 @@ enum WhisperLanguageChoice: Equatable {
     }
 }
 
+enum WhisperAlignmentMode: String, Equatable {
+    case none
+    case token = "whisper-token"
+    case dtw = "whisper-dtw"
+
+    var displayValue: String { rawValue }
+    var needsWordTimestamps: Bool { self != .none }
+    var needsDTW: Bool { self == .dtw }
+
+    static func parse(_ value: String) throws -> WhisperAlignmentMode {
+        guard let mode = WhisperAlignmentMode(rawValue: value) else {
+            throw CLIError.usage("Invalid align mode: \(value). Expected none, whisper-token, or whisper-dtw.")
+        }
+        return mode
+    }
+}
+
+private struct WhisperTokenTiming {
+    let text: String
+    let startTime: Double
+    let endTime: Double
+    let confidence: Float
+}
+
 struct WhisperCLIResult {
     let text: String
     let language: String
@@ -34,6 +58,7 @@ struct WhisperCLIResult {
     let processingTime: Double
     let model: String
     let segments: [SegmentTimingOutput]
+    let wordTimings: [WordTimingOutput]
 }
 
 private final class CLIWhisperInputState: @unchecked Sendable {
@@ -54,10 +79,18 @@ private final class CLIWhisperContext: @unchecked Sendable {
         self.vadModelPath = vadModelPath
     }
 
-    static func load(modelPath: String, vadModelPath: String?) throws -> CLIWhisperContext {
+    static func load(
+        modelPath: String,
+        vadModelPath: String?,
+        alignmentMode: WhisperAlignmentMode
+    ) throws -> CLIWhisperContext {
         var params = whisper_context_default_params()
         params.use_gpu = true
-        params.flash_attn = true
+        params.flash_attn = !alignmentMode.needsDTW
+        params.dtw_token_timestamps = alignmentMode.needsDTW
+        if alignmentMode.needsDTW {
+            params.dtw_aheads_preset = WHISPER_AHEADS_LARGE_V3_TURBO
+        }
 
         guard let context = whisper_init_from_file_with_params(modelPath, params) else {
             throw WhisperCLIError.modelLoadFailed
@@ -69,8 +102,9 @@ private final class CLIWhisperContext: @unchecked Sendable {
     func transcribe(
         samples: [Float],
         language: WhisperLanguageChoice,
+        alignmentMode: WhisperAlignmentMode,
         useVAD: Bool
-    ) throws -> (text: String, language: String, segments: [SegmentTimingOutput]) {
+    ) throws -> (text: String, language: String, segments: [SegmentTimingOutput], wordTimings: [WordTimingOutput]) {
         var params = whisper_full_default_params(WHISPER_SAMPLING_GREEDY)
         var languageCString: UnsafeMutablePointer<CChar>?
         var vadCString: UnsafeMutablePointer<CChar>?
@@ -113,6 +147,7 @@ private final class CLIWhisperContext: @unchecked Sendable {
         params.no_timestamps = false
         params.single_segment = false
         params.no_context = true
+        params.token_timestamps = alignmentMode.needsWordTimestamps
         params.temperature = 0.0
         params.n_threads = max(1, Int32(ProcessInfo.processInfo.activeProcessorCount - 2))
 
@@ -138,6 +173,10 @@ private final class CLIWhisperContext: @unchecked Sendable {
             }
         }
 
+        let wordTimings = alignmentMode.needsWordTimestamps
+            ? extractWordTimings(segmentCount: segmentCount)
+            : []
+
         let languageID = whisper_full_lang_id(context)
         let detectedLanguage: String
         if let languageString = whisper_lang_str(languageID) {
@@ -146,7 +185,48 @@ private final class CLIWhisperContext: @unchecked Sendable {
             detectedLanguage = language.displayValue
         }
 
-        return (text, detectedLanguage, segments)
+        return (text, detectedLanguage, segments, wordTimings)
+    }
+
+    private func extractWordTimings(segmentCount: Int32) -> [WordTimingOutput] {
+        var tokenTimings: [WhisperTokenTiming] = []
+
+        for segmentIndex in 0..<segmentCount {
+            let tokenCount = whisper_full_n_tokens(context, segmentIndex)
+            for tokenIndex in 0..<tokenCount {
+                guard let tokenCString = whisper_full_get_token_text(context, segmentIndex, tokenIndex) else {
+                    continue
+                }
+
+                let text = String(cString: tokenCString)
+                guard shouldUseToken(text) else { continue }
+
+                let tokenData = whisper_full_get_token_data(context, segmentIndex, tokenIndex)
+                let startTime = Double(tokenData.t0) / 100
+                let endTime = Double(tokenData.t1) / 100
+                guard startTime.isFinite, endTime.isFinite, endTime > startTime else {
+                    continue
+                }
+
+                tokenTimings.append(
+                    WhisperTokenTiming(
+                        text: text,
+                        startTime: startTime,
+                        endTime: endTime,
+                        confidence: tokenData.p
+                    )
+                )
+            }
+        }
+
+        return WhisperWordTimingBuilder.mergeTokensIntoWords(tokenTimings)
+    }
+
+    private func shouldUseToken(_ text: String) -> Bool {
+        guard !text.isEmpty else { return false }
+        if text.hasPrefix("[") && text.hasSuffix("]") { return false }
+        if text.allSatisfy({ $0.isWhitespace }) { return false }
+        return true
     }
 
     deinit {
@@ -154,6 +234,68 @@ private final class CLIWhisperContext: @unchecked Sendable {
     }
 }
 
+private enum WhisperWordTimingBuilder {
+    private static let tokenBoundaryCharacters = CharacterSet(charactersIn: " \n\t▁")
+
+    static func mergeTokensIntoWords(_ tokenTimings: [WhisperTokenTiming]) -> [WordTimingOutput] {
+        guard !tokenTimings.isEmpty else { return [] }
+
+        var words: [WordTimingOutput] = []
+        var currentWord = ""
+        var currentStart: Double?
+        var currentEnd = 0.0
+        var confidences: [Float] = []
+
+        for timing in tokenTimings {
+            let startsNewWord = timing.text.hasPrefix(" ")
+                || timing.text.hasPrefix("\n")
+                || timing.text.hasPrefix("\t")
+                || timing.text.hasPrefix("▁")
+
+            if startsNewWord, !currentWord.isEmpty, let start = currentStart {
+                words.append(
+                    WordTimingOutput(
+                        word: currentWord,
+                        startTime: start,
+                        endTime: currentEnd,
+                        confidence: average(confidences)
+                    )
+                )
+                currentWord = ""
+                confidences = []
+                currentStart = nil
+            }
+
+            let cleanToken = timing.text.trimmingCharacters(in: tokenBoundaryCharacters)
+            guard !cleanToken.isEmpty else { continue }
+            if currentStart == nil || currentWord.isEmpty {
+                currentStart = timing.startTime
+            }
+            currentWord += cleanToken
+            currentEnd = timing.endTime
+            confidences.append(timing.confidence)
+        }
+
+        if !currentWord.isEmpty, let start = currentStart {
+            words.append(
+                WordTimingOutput(
+                    word: currentWord,
+                    startTime: start,
+                    endTime: currentEnd,
+                    confidence: average(confidences)
+                )
+            )
+        }
+
+        return words
+    }
+
+    private static func average(_ confidences: [Float]) -> Float {
+        guard !confidences.isEmpty else { return 0 }
+        return confidences.reduce(0, +) / Float(confidences.count)
+    }
+}
+
 enum WhisperCLITranscriber {
     static let modelName = "whisper-large-v3-turbo"
 
@@ -161,7 +303,12 @@ enum WhisperCLITranscriber {
         try await ensureModels(quiet: quiet)
     }
 
-    static func transcribe(audioURL: URL, language: WhisperLanguageChoice, quiet: Bool) async throws -> WhisperCLIResult {
+    static func transcribe(
+        audioURL: URL,
+        language: WhisperLanguageChoice,
+        alignmentMode: WhisperAlignmentMode,
+        quiet: Bool
+    ) async throws -> WhisperCLIResult {
         try await ensureModels(quiet: quiet)
 
         if !quiet {
@@ -171,18 +318,24 @@ enum WhisperCLITranscriber {
         let vadPath = FileManager.default.fileExists(atPath: MiniWhisperPaths.whisperVADModel.path)
             ? MiniWhisperPaths.whisperVADModel.path
             : nil
-        let context = try CLIWhisperContext.load(modelPath: MiniWhisperPaths.whisperModel.path, vadModelPath: vadPath)
+        let context = try CLIWhisperContext.load(
+            modelPath: MiniWhisperPaths.whisperModel.path,
+            vadModelPath: vadPath,
+            alignmentMode: alignmentMode
+        )
 
         if !quiet {
-            Console.error("Transcribing \(audioURL.path) (batch, model: whisper, language: \(language.displayValue))...")
+            let alignment = alignmentMode == .none ? "none" : alignmentMode.displayValue
+            Console.error("Transcribing \(audioURL.path) (batch, model: whisper, language: \(language.displayValue), align: \(alignment))...")
         }
 
         let samples = try resampleTo16kHz(audioURL: audioURL)
         let audioDuration = AudioMetadata.durationSeconds(for: audioURL) ?? 0
         let start = Date()
-        let useVAD = vadPath != nil
+        // VAD compacts audio before decode, and whisper.cpp token timestamps stay on that compacted timeline.
+        let useVAD = vadPath != nil && !alignmentMode.needsWordTimestamps
         var result = try await Task.detached {
-            try context.transcribe(samples: samples, language: language, useVAD: useVAD)
+            try context.transcribe(samples: samples, language: language, alignmentMode: alignmentMode, useVAD: useVAD)
         }.value
         if result.text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
            useVAD,
@@ -191,7 +344,7 @@ enum WhisperCLITranscriber {
                 Console.error("Whisper VAD produced an empty transcript; retrying without VAD...")
             }
             result = try await Task.detached {
-                try context.transcribe(samples: samples, language: language, useVAD: false)
+                try context.transcribe(samples: samples, language: language, alignmentMode: alignmentMode, useVAD: false)
             }.value
         }
         let processingTime = Date().timeIntervalSince(start)
@@ -202,7 +355,8 @@ enum WhisperCLITranscriber {
             audioDuration: audioDuration,
             processingTime: processingTime,
             model: modelName,
-            segments: result.segments
+            segments: result.segments,
+            wordTimings: result.wordTimings
         )
     }