[refactor] rename and simplify ProgressManager to FileProgress, enhance caching logic, update Hugging Face API integration, and clean up unused comments

docs: align CLI docs to models subcommands; host: scan XDG plugin dir; ci: add GitHub Actions; chore: add CHANGELOG
[refactor] improve code readability, streamline initialization, update error handling, and format multi-line statements for consistency
2025-08-15 11:24:50 +02:00 · 2025-08-14 11:16:50 +02:00 · 2025-08-14 11:06:37 +02:00 · 2025-08-14 10:34:52 +02:00 · 2025-08-14 03:31:00 +02:00 · 2025-08-13 22:44:51 +02:00
41 changed files with 4165 additions and 4057 deletions
--- a/.cargo/config.toml
+++ b/.cargo/config.toml
@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: MIT
+
+[build]
+# Make target-dir consistent across workspace for better cache reuse.
+target-dir = "target"
+
+[profile.dev]
+opt-level = 1
+debug = true
+incremental = true
+
+[profile.release]
+# Reasonable defaults for CLI apps/libraries
+lto = "thin"
+codegen-units = 1
+strip = "debuginfo"
+opt-level = 3
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [ dev, main ]
+  pull_request:
+    branches: [ dev, main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo registry and target
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install components
+        run: rustup component add clippy rustfmt
+
+      - name: Cargo fmt
+        run: cargo fmt --all -- --check
+
+      - name: Clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+
+      - name: Test
+        run: cargo test --workspace --all --locked
+
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
+
+## Unreleased
+
+### Changed
+- Docs: Replace `--download-models`/`--update-models` flags with `models download`/`models update` subcommands in `README.md`, `docs/usage.md`, and `docs/development.md`.
+- Host: Plugin discovery now scans `$XDG_DATA_HOME/polyscribe/plugins` (platform equivalent via `directories`) in addition to `PATH`.
+- CI: Add GitHub Actions workflow to run fmt, clippy (warnings as errors), and tests for pushes and PRs.
+
+
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,32 +1,26 @@
-# Contributing to PolyScribe
+# Contributing

-Thanks for your interest in contributing! This guide explains the workflow and the checklist to follow before opening a Pull Request.
+Thank you for your interest in contributing!

-Workflow (fork → branch → PR)
-1) Fork the repository to your account.
-2) Create a feature branch:
- git checkout -b feat/short-description
-3) Make changes with focused commits and good messages.
-4) Run the checklist below.
-5) Push and open a Pull Request against the main repository.
+Development setup
+- Install Rust via rustup.
+- Ensure ffmpeg is installed and available on PATH.
+- For GPU builds, install the appropriate runtime (CUDA/ROCm/Vulkan) and enable the matching features.

-Developer checklist (before opening a PR)
- Build:
-  - cargo build (preferably without warnings)
- Tests:
-  - cargo test (all tests pass)
- Lints:
-  - cargo clippy --all-targets -- -D warnings (fix warnings)
- Documentation:
-  - Update README/docs for user-visible changes
-  - Update CHANGELOG.md if applicable
- Tests for changes:
-  - Add or update tests for bug fixes and new features where reasonable
+Coding guidelines
+- Prefer small, focused changes.
+- Add tests where reasonable.
+- Keep user-facing changes documented in README/docs.
+- Run clippy and fix warnings.

-Local development tips
- Use `cargo run -- <args>` during development.
- For faster feedback, keep examples in the examples/ folder handy.
- Keep functions small and focused; prefer clear error messages with context.
+CI checklist
+- Build: cargo build --all-targets --locked
+- Tests: cargo test --all --locked
+- Lints: cargo clippy --all-targets -- -D warnings
+- Optional: smoke-run examples inline (from README):
+  - ./target/release/polyscribe --update-models --no-interaction -q
+  - ./target/release/polyscribe -o output samples/podcast_clip.mp3

-Code of conduct
- Be respectful and constructive. Assume good intent.
+Notes
+- For GPU features, use --features gpu-cuda|gpu-hip|gpu-vulkan as needed in your local runs.
+- For docs-only changes, please still ensure the project builds.
--- a/Cargo.lock
+++ b/Cargo.lock
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,34 +1,39 @@
-[package]
-name = "polyscribe"
-version = "0.1.0"
-edition = "2024"
-license = "MIT"
-license-file = "LICENSE"
+[workspace]
+members = [
+    "crates/polyscribe-core",
+    "crates/polyscribe-protocol",
+    "crates/polyscribe-host",
+    "crates/polyscribe-cli",
+]
+resolver = "3"

-[features]
-# Default: CPU only; no GPU features enabled
-default = []
-# GPU backends map to whisper-rs features or FFI stub for Vulkan
-gpu-cuda = ["whisper-rs/cuda"]
-gpu-hip = ["whisper-rs/hipblas"]
-gpu-vulkan = []
-# explicit CPU fallback feature (no effect at build time, used for clarity)
-cpu-fallback = []
-
-[dependencies]
-anyhow = "1.0.98"
-clap = { version = "4.5.43", features = ["derive"] }
-clap_complete = "4.5.28"
-clap_mangen = "0.2"
+# Optional: Keep dependency versions consistent across members
+[workspace.dependencies]
+thiserror = "1.0.69"
 serde = { version = "1.0.219", features = ["derive"] }
+anyhow = "1.0.99"
+libc = "0.2.175"
+toml = "0.8.23"
 serde_json = "1.0.142"
-toml = "0.8"
-chrono = { version = "0.4", features = ["clock"] }
-reqwest = { version = "0.12", features = ["blocking", "json"] }
-sha2 = "0.10"
-# whisper-rs is always used (CPU-only by default); GPU features map onto it
-whisper-rs = { git = "https://github.com/tazz4843/whisper-rs" }
-libc = "0.2"
+chrono = "0.4.41"
+sha2 = "0.10.9"
+which = "6.0.3"
+tokio = { version = "1.47.1", features = ["rt-multi-thread", "macros"] }
+clap = { version = "4.5.44", features = ["derive"] }
+directories = "5.0.1"
+whisper-rs = "0.14.3"
+cliclack = "0.3.6"
+clap_complete = "4.5.57"
+clap_mangen = "0.2.29"

-[dev-dependencies]
-tempfile = "3"
+[workspace.lints.rust]
+unused_imports = "deny"
+dead_code = "warn"
+
+[profile.release]
+lto = "fat"
+codegen-units = 1
+panic = "abort"
+
+[profile.dev]
+panic = "unwind"
--- a/README.md
+++ b/README.md
@@ -1,88 +1,68 @@
 # PolyScribe

-PolyScribe is a fast, local-first CLI for transcribing audio/video and merging existing JSON transcripts. It uses whisper-rs under the hood, can discover and download Whisper models automatically, and supports CPU and optional GPU backends (CUDA, ROCm/HIP, Vulkan).
+Local-first transcription and plugins.

-Key features
- Transcribe audio and common video files using ffmpeg for audio extraction.
- Merge multiple JSON transcripts, or merge and also keep per-file outputs.
- Model management: interactive downloader and non-interactive updater with hash verification.
- GPU backend selection at runtime; auto-detects available accelerators.
- Clean outputs (JSON and SRT), speaker naming prompts, and useful logging controls.
+## Features

-Prerequisites
- Rust toolchain (rustup recommended)
- ffmpeg available on PATH
- Optional for GPU acceleration at runtime: CUDA, ROCm/HIP, or Vulkan drivers (match your build features)
+- **Local-first**: Works offline with downloaded models
+- **Multiple backends**: CPU, CUDA, ROCm/HIP, and Vulkan support
+- **Plugin system**: Extensible via JSON-RPC plugins
+- **Model management**: Automatic download and verification of Whisper models
+- **Manifest caching**: Local cache for Hugging Face model manifests to reduce network requests

-Installation
- Build from source (CPU-only by default):
-  - rustup install stable
-  - rustup default stable
-  - cargo build --release
- Binary path: ./target/release/polyscribe
- GPU builds (optional): build with features
-  - CUDA: cargo build --release --features gpu-cuda
-  - HIP: cargo build --release --features gpu-hip
-  - Vulkan: cargo build --release --features gpu-vulkan
+## Model Management

-Quickstart
-1) Download a model (first run can prompt you):
- ./target/release/polyscribe --download-models
+PolyScribe automatically manages Whisper models from Hugging Face:

-2) Transcribe a file:
- ./target/release/polyscribe -v -o output my_audio.mp3
-This writes JSON and SRT into the output directory with a date prefix.
+```bash
+# Download models interactively
+polyscribe models download

-Shell completions and man page
- Completions: ./target/release/polyscribe completions <bash|zsh|fish|powershell|elvish> > polyscribe.<ext>
-  - Then install into your shell’s completion directory.
- Man page: ./target/release/polyscribe man > polyscribe.1 (then copy to your manpath)
+# Update existing models
+polyscribe models update

-Model locations
- Development (debug builds): ./models next to the project.
- Packaged/release builds: $XDG_DATA_HOME/polyscribe/models or ~/.local/share/polyscribe/models.
- Override via env var: POLYSCRIBE_MODELS_DIR=/path/to/models.
- Force a specific model file via env var: WHISPER_MODEL=/path/to/model.bin.
+# Clear manifest cache (force fresh fetch)
+polyscribe models clear-cache
+```

-Most-used CLI flags
- -o, --output FILE_OR_DIR: Output path base (date prefix added). If omitted, JSON prints to stdout.
- -m, --merge: Merge all inputs into one output; otherwise one output per input.
- --merge-and-separate: Write both merged output and separate per-input outputs (requires -o dir).
- --set-speaker-names: Prompt for a speaker label per input file.
- --update-models: Verify/update local models by size/hash against the upstream manifest.
- --download-models: Interactive model list + multi-select download.
- --language LANG: Language code hint (e.g., en, de). English-only models reject non-en hints.
- --gpu-backend [auto|cpu|cuda|hip|vulkan]: Select backend (auto by default).
- --gpu-layers N: Offload N layers to GPU when supported.
- -v/--verbose (repeatable): Increase log verbosity. -vv shows very detailed logs.
- -q/--quiet: Suppress non-error logs (stderr); does not silence stdout results.
- --no-interaction: Never prompt; suitable for CI.
+### Manifest Caching

-Minimal usage examples
- Transcribe an audio file to JSON/SRT:
-  - ./target/release/polyscribe -o output samples/podcast_clip.mp3
- Merge multiple transcripts into one:
-  - ./target/release/polyscribe -m -o output merged input/a.json input/b.json
- Update local models non-interactively (good for CI):
-  - ./target/release/polyscribe --update-models --no-interaction -q
+The Hugging Face model manifest is cached locally to avoid repeated network requests:

-Troubleshooting & docs
- docs/faq.md – common issues and solutions (missing ffmpeg, GPU selection, model paths)
- docs/usage.md – complete CLI reference and workflows
- docs/development.md – build, run, and contribute locally
- docs/design.md – architecture overview and decisions
- docs/release-packaging.md – packaging notes for distributions
- docs/ci.md – minimal CI checklist and job outline
- CONTRIBUTING.md – PR checklist and workflow
+- **Default TTL**: 24 hours
+- **Cache location**: `$XDG_CACHE_HOME/polyscribe/manifest/` (or platform equivalent)
+- **Environment variables**:
+  - `POLYSCRIBE_NO_CACHE_MANIFEST=1`: Disable caching
+  - `POLYSCRIBE_MANIFEST_TTL_SECONDS=3600`: Set custom TTL (in seconds)

-CI status: [CI badge placeholder]
+## Installation

-Examples
-See the examples/ directory for copy-paste scripts:
- examples/transcribe_file.sh
- examples/update_models.sh
- examples/download_models_interactive.sh
+```bash
+cargo install --path .
+```

-License
-------
-This project is licensed under the MIT License — see the LICENSE file for details.
+## Usage
+
+```bash
+# Transcribe audio/video
+polyscribe transcribe input.mp4
+
+# Merge multiple transcripts
+polyscribe transcribe --merge input1.json input2.json
+
+# Use specific GPU backend
+polyscribe transcribe --gpu-backend cuda input.mp4
+```
+
+## Development
+
+```bash
+# Build
+cargo build
+
+# Run tests
+cargo test
+
+# Run with verbose logging
+cargo run -- --verbose transcribe input.mp4
+```
--- a/crates/polyscribe-cli/Cargo.toml
+++ b/crates/polyscribe-cli/Cargo.toml
@@ -0,0 +1,32 @@
+[package]
+name = "polyscribe-cli"
+version = "0.1.0"
+edition = "2024"
+
+[[bin]]
+name = "polyscribe"
+path = "src/main.rs"
+
+[dependencies]
+anyhow = "1.0.99"
+clap = { version = "4.5.44", features = ["derive"] }
+clap_complete = "4.5.57"
+clap_mangen = "0.2.29"
+directories = "5.0.1"
+serde = { version = "1.0.219", features = ["derive"] }
+serde_json = "1.0.142"
+tokio = { version = "1.47.1", features = ["rt-multi-thread", "macros", "process", "fs"] }
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["fmt", "env-filter"] }
+which = "6.0.3"
+
+polyscribe-core = { path = "../polyscribe-core" }
+polyscribe-host = { path = "../polyscribe-host" }
+polyscribe-protocol = { path = "../polyscribe-protocol" }
+
+[features]
+# Optional GPU-specific flags can be forwarded down to core/host if needed
+default = []
+
+[dev-dependencies]
+assert_cmd = "2.0.16"
--- a/crates/polyscribe-cli/src/cli.rs
+++ b/crates/polyscribe-cli/src/cli.rs
@@ -0,0 +1,129 @@
+use clap::{Parser, Subcommand, ValueEnum};
+use std::path::PathBuf;
+
+#[derive(Debug, Clone, ValueEnum)]
+pub enum GpuBackend {
+    Auto,
+    Cpu,
+    Cuda,
+    Hip,
+    Vulkan,
+}
+
+#[derive(Debug, Parser)]
+#[command(
+    name = "polyscribe",
+    version,
+    about = "PolyScribe – local-first transcription and plugins"
+)]
+pub struct Cli {
+    /// Increase verbosity (-v, -vv)
+    #[arg(short, long, action = clap::ArgAction::Count)]
+    pub verbose: u8,
+
+    /// Quiet mode (suppresses non-error logs)
+    #[arg(short, long, default_value_t = false)]
+    pub quiet: bool,
+
+    /// Never prompt for user input (non-interactive mode)
+    #[arg(long, default_value_t = false)]
+    pub no_interaction: bool,
+
+    /// Disable progress bars/spinners
+    #[arg(long, default_value_t = false)]
+    pub no_progress: bool,
+
+    #[command(subcommand)]
+    pub command: Commands,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum Commands {
+    /// Transcribe audio/video files or merge existing transcripts
+    Transcribe {
+        /// Output file or directory (date prefix is added when directory)
+        #[arg(short, long)]
+        output: Option<PathBuf>,
+
+        /// Merge multiple inputs into one output
+        #[arg(short = 'm', long, default_value_t = false)]
+        merge: bool,
+
+        /// Write both merged and per-input outputs (requires -o dir)
+        #[arg(long, default_value_t = false)]
+        merge_and_separate: bool,
+
+        /// Language code hint, e.g. en, de
+        #[arg(long)]
+        language: Option<String>,
+
+        /// Prompt for a speaker label per input file
+        #[arg(long, default_value_t = false)]
+        set_speaker_names: bool,
+
+        /// GPU backend selection
+        #[arg(long, value_enum, default_value_t = GpuBackend::Auto)]
+        gpu_backend: GpuBackend,
+
+        /// Offload N layers to GPU (when supported)
+        #[arg(long, default_value_t = 0)]
+        gpu_layers: usize,
+
+        /// Input paths: audio/video files or JSON transcripts
+        #[arg(required = true)]
+        inputs: Vec<PathBuf>,
+    },
+
+    /// Manage Whisper models
+    Models {
+        #[command(subcommand)]
+        cmd: ModelsCmd,
+    },
+
+    /// Discover and run plugins
+    Plugins {
+        #[command(subcommand)]
+        cmd: PluginsCmd,
+    },
+
+    /// Generate shell completions to stdout
+    Completions {
+        /// Shell to generate completions for
+        #[arg(value_parser = ["bash", "zsh", "fish", "powershell", "elvish"])]
+        shell: String,
+    },
+
+    /// Generate a man page to stdout
+    Man,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum ModelsCmd {
+    /// Verify or update local models non-interactively
+    Update,
+    /// Interactive multi-select downloader
+    Download,
+    /// Clear the cached Hugging Face manifest
+    ClearCache,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum PluginsCmd {
+    /// List installed plugins
+    List,
+    /// Show a plugin's capabilities (as JSON)
+    Info {
+        /// Plugin short name, e.g., "tubescribe"
+        name: String,
+    },
+    /// Run a plugin command (JSON-RPC over NDJSON via stdio)
+    Run {
+        /// Plugin short name
+        name: String,
+        /// Command name in plugin's API
+        command: String,
+        /// JSON payload string
+        #[arg(long)]
+        json: Option<String>,
+    },
+}
--- a/crates/polyscribe-cli/src/main.rs
+++ b/crates/polyscribe-cli/src/main.rs
@@ -0,0 +1,177 @@
+mod cli;
+
+use anyhow::{Context, Result, anyhow};
+use clap::{CommandFactory, Parser};
+use cli::{Cli, Commands, GpuBackend, ModelsCmd, PluginsCmd};
+use polyscribe_core::models;
+use polyscribe_core::ui::progress::ProgressReporter;
+use polyscribe_host::PluginManager;
+use tokio::io::AsyncWriteExt;
+use tracing_subscriber::EnvFilter;
+
+fn init_tracing(quiet: bool, verbose: u8) {
+    let log_level = if quiet {
+        "error"
+    } else {
+        match verbose {
+            0 => "info",
+            1 => "debug",
+            _ => "trace",
+        }
+    };
+
+    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new(log_level));
+    tracing_subscriber::fmt()
+        .with_env_filter(filter)
+        .with_target(false)
+        .with_level(true)
+        .compact()
+        .init();
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let args = Cli::parse();
+
+    init_tracing(args.quiet, args.verbose);
+
+    polyscribe_core::set_quiet(args.quiet);
+    polyscribe_core::set_no_interaction(args.no_interaction);
+    polyscribe_core::set_verbose(args.verbose);
+    polyscribe_core::set_no_progress(args.no_progress);
+
+    match args.command {
+        Commands::Transcribe {
+            gpu_backend,
+            gpu_layers,
+            inputs,
+            ..
+        } => {
+            polyscribe_core::ui::info("starting transcription workflow");
+            let mut progress = ProgressReporter::new(args.no_interaction);
+
+            progress.step("Validating inputs");
+            if inputs.is_empty() {
+                return Err(anyhow!("no inputs provided"));
+            }
+
+            progress.step("Selecting backend and preparing model");
+            match gpu_backend {
+                GpuBackend::Auto => {}
+                GpuBackend::Cpu => {}
+                GpuBackend::Cuda => {
+                    let _ = gpu_layers;
+                }
+                GpuBackend::Hip => {}
+                GpuBackend::Vulkan => {}
+            }
+
+            progress.finish_with_message("Transcription completed (stub)");
+            Ok(())
+        }
+
+        Commands::Models { cmd } => {
+            match cmd {
+                ModelsCmd::Update => {
+                    polyscribe_core::ui::info("verifying/updating local models");
+                    tokio::task::spawn_blocking(models::update_local_models)
+                        .await
+                        .map_err(|e| anyhow!("blocking task join error: {e}"))?
+                        .context("updating models")?;
+                }
+                ModelsCmd::Download => {
+                    polyscribe_core::ui::info("interactive model selection and download");
+                    tokio::task::spawn_blocking(models::run_interactive_model_downloader)
+                        .await
+                        .map_err(|e| anyhow!("blocking task join error: {e}"))?
+                        .context("running downloader")?;
+                    polyscribe_core::ui::success("Model download complete.");
+                }
+                ModelsCmd::ClearCache => {
+                    polyscribe_core::ui::info("clearing manifest cache");
+                    tokio::task::spawn_blocking(models::clear_manifest_cache)
+                        .await
+                        .map_err(|e| anyhow!("blocking task join error: {e}"))?
+                        .context("clearing cache")?;
+                    polyscribe_core::ui::success("Manifest cache cleared.");
+                }
+            }
+            Ok(())
+        }
+
+        Commands::Plugins { cmd } => {
+            let plugin_manager = PluginManager;
+
+            match cmd {
+                PluginsCmd::List => {
+                    let list = plugin_manager.list().context("discovering plugins")?;
+                    for item in list {
+                        polyscribe_core::ui::info(item.name);
+                    }
+                    Ok(())
+                }
+                PluginsCmd::Info { name } => {
+                    let info = plugin_manager
+                        .info(&name)
+                        .with_context(|| format!("getting info for {}", name))?;
+                    let info_json = serde_json::to_string_pretty(&info)?;
+                    polyscribe_core::ui::info(info_json);
+                    Ok(())
+                }
+                PluginsCmd::Run {
+                    name,
+                    command,
+                    json,
+                } => {
+                    let payload = json.unwrap_or_else(|| "{}".to_string());
+                    let mut child = plugin_manager
+                        .spawn(&name, &command)
+                        .with_context(|| format!("spawning plugin {name} {command}"))?;
+
+                    if let Some(mut stdin) = child.stdin.take() {
+                        stdin
+                            .write_all(payload.as_bytes())
+                            .await
+                            .context("writing JSON payload to plugin stdin")?;
+                    }
+
+                    let status = plugin_manager.forward_stdio(&mut child).await?;
+                    if !status.success() {
+                        polyscribe_core::ui::error(format!(
+                            "plugin returned non-zero exit code: {}",
+                            status
+                        ));
+                        return Err(anyhow!("plugin failed"));
+                    }
+                    Ok(())
+                }
+            }
+        }
+
+        Commands::Completions { shell } => {
+            use clap_complete::{generate, shells};
+            use std::io;
+
+            let mut cmd = Cli::command();
+            let name = cmd.get_name().to_string();
+
+            match shell.as_str() {
+                "bash" => generate(shells::Bash, &mut cmd, name, &mut io::stdout()),
+                "zsh" => generate(shells::Zsh, &mut cmd, name, &mut io::stdout()),
+                "fish" => generate(shells::Fish, &mut cmd, name, &mut io::stdout()),
+                "powershell" => generate(shells::PowerShell, &mut cmd, name, &mut io::stdout()),
+                "elvish" => generate(shells::Elvish, &mut cmd, name, &mut io::stdout()),
+                _ => return Err(anyhow!("unsupported shell: {shell}")),
+            }
+            Ok(())
+        }
+
+        Commands::Man => {
+            use clap_mangen::Man;
+            let cmd = Cli::command();
+            let man = Man::new(cmd);
+            man.render(&mut std::io::stdout())?;
+            Ok(())
+        }
+    }
+}
--- a/crates/polyscribe-cli/tests/integration_aux.rs
+++ b/crates/polyscribe-cli/tests/integration_aux.rs
@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2025 <COPYRIGHT HOLDER>. All rights reserved.

+use assert_cmd::cargo::cargo_bin;
 use std::process::Command;

-fn bin() -> &'static str {
-    env!("CARGO_BIN_EXE_polyscribe")
+fn bin() -> std::path::PathBuf {
+    cargo_bin("polyscribe")
 }

 #[test]
--- a/crates/polyscribe-core/Cargo.toml
+++ b/crates/polyscribe-core/Cargo.toml
@@ -0,0 +1,22 @@
+[package]
+name = "polyscribe-core"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+anyhow = "1.0.99"
+thiserror = "1.0.69"
+serde = { version = "1.0.219", features = ["derive"] }
+serde_json = "1.0.142"
+toml = "0.8.23"
+directories = "5.0.1"
+chrono = "0.4.41"
+libc = "0.2.175"
+whisper-rs = "0.14.3"
+# UI and progress
+cliclack = { workspace = true }
+# New: HTTP downloads + hashing
+reqwest = { version = "0.12.7", default-features = false, features = ["blocking", "rustls-tls", "gzip", "json"] }
+sha2 = "0.10.8"
+hex = "0.4.3"
+tempfile = "3.12.0"
--- a/crates/polyscribe-core/build.rs
+++ b/crates/polyscribe-core/build.rs
@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+
+fn main() {
+    let vulkan_enabled = std::env::var("CARGO_FEATURE_GPU_VULKAN").is_ok();
+    println!("cargo:rerun-if-changed=extern/whisper.cpp");
+    if !vulkan_enabled {
+        println!(
+            "cargo:warning=gpu-vulkan feature is disabled; skipping Vulkan-dependent build steps."
+        );
+        return;
+    }
+    println!(
+        "cargo:warning=Building with gpu-vulkan: ensure Vulkan SDK/loader are installed. Future versions will compile whisper.cpp via CMake."
+    );
+}
--- a/crates/polyscribe-core/src/backend.rs
+++ b/crates/polyscribe-core/src/backend.rs
@@ -0,0 +1,303 @@
+// SPDX-License-Identifier: MIT
+
+use crate::OutputEntry;
+use crate::prelude::*;
+use crate::{decode_audio_to_pcm_f32_ffmpeg, find_model_file};
+use anyhow::{Context, anyhow};
+use std::env;
+use std::path::Path;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BackendKind {
+    Auto,
+    Cpu,
+    Cuda,
+    Hip,
+    Vulkan,
+}
+
+pub trait TranscribeBackend {
+    fn kind(&self) -> BackendKind;
+    fn transcribe(
+        &self,
+        audio_path: &Path,
+        speaker: &str,
+        language: Option<&str>,
+        gpu_layers: Option<u32>,
+        progress: Option<&(dyn Fn(i32) + Send + Sync)>,
+    ) -> Result<Vec<OutputEntry>>;
+}
+
+fn is_library_available(_names: &[&str]) -> bool {
+    #[cfg(test)]
+    {
+        false
+    }
+    #[cfg(not(test))]
+    {
+        false
+    }
+}
+
+fn cuda_available() -> bool {
+    if let Ok(x) = env::var("POLYSCRIBE_TEST_FORCE_CUDA") {
+        return x == "1";
+    }
+    is_library_available(&[
+        "libcudart.so",
+        "libcudart.so.12",
+        "libcudart.so.11",
+        "libcublas.so",
+        "libcublas.so.12",
+    ])
+}
+
+fn hip_available() -> bool {
+    if let Ok(x) = env::var("POLYSCRIBE_TEST_FORCE_HIP") {
+        return x == "1";
+    }
+    is_library_available(&["libhipblas.so", "librocblas.so"])
+}
+
+fn vulkan_available() -> bool {
+    if let Ok(x) = env::var("POLYSCRIBE_TEST_FORCE_VULKAN") {
+        return x == "1";
+    }
+    is_library_available(&["libvulkan.so.1", "libvulkan.so"])
+}
+
+#[derive(Default)]
+pub struct CpuBackend;
+#[derive(Default)]
+pub struct CudaBackend;
+#[derive(Default)]
+pub struct HipBackend;
+#[derive(Default)]
+pub struct VulkanBackend;
+
+macro_rules! impl_whisper_backend {
+    ($ty:ty, $kind:expr) => {
+        impl TranscribeBackend for $ty {
+            fn kind(&self) -> BackendKind {
+                $kind
+            }
+            fn transcribe(
+                &self,
+                audio_path: &Path,
+                speaker: &str,
+                language: Option<&str>,
+                _gpu_layers: Option<u32>,
+                progress: Option<&(dyn Fn(i32) + Send + Sync)>,
+            ) -> Result<Vec<OutputEntry>> {
+                transcribe_with_whisper_rs(audio_path, speaker, language, progress)
+            }
+        }
+    };
+}
+
+impl_whisper_backend!(CpuBackend, BackendKind::Cpu);
+impl_whisper_backend!(CudaBackend, BackendKind::Cuda);
+impl_whisper_backend!(HipBackend, BackendKind::Hip);
+
+impl TranscribeBackend for VulkanBackend {
+    fn kind(&self) -> BackendKind {
+        BackendKind::Vulkan
+    }
+    fn transcribe(
+        &self,
+        _audio_path: &Path,
+        _speaker: &str,
+        _language: Option<&str>,
+        _gpu_layers: Option<u32>,
+        _progress: Option<&(dyn Fn(i32) + Send + Sync)>,
+    ) -> Result<Vec<OutputEntry>> {
+        Err(anyhow!(
+            "Vulkan backend not yet wired to whisper.cpp FFI. Build with --features gpu-vulkan and ensure Vulkan SDK is installed. How to fix: install Vulkan loader (libvulkan), set VULKAN_SDK, and run cargo build --features gpu-vulkan."
+        ).into())
+    }
+}
+
+pub struct BackendSelection {
+    pub backend: Box<dyn TranscribeBackend + Send + Sync>,
+    pub chosen: BackendKind,
+    pub detected: Vec<BackendKind>,
+}
+
+pub fn select_backend(requested: BackendKind, verbose: bool) -> Result<BackendSelection> {
+    let mut detected = Vec::new();
+    if cuda_available() {
+        detected.push(BackendKind::Cuda);
+    }
+    if hip_available() {
+        detected.push(BackendKind::Hip);
+    }
+    if vulkan_available() {
+        detected.push(BackendKind::Vulkan);
+    }
+
+    let instantiate_backend = |k: BackendKind| -> Box<dyn TranscribeBackend + Send + Sync> {
+        match k {
+            BackendKind::Cpu => Box::new(CpuBackend),
+            BackendKind::Cuda => Box::new(CudaBackend),
+            BackendKind::Hip => Box::new(HipBackend),
+            BackendKind::Vulkan => Box::new(VulkanBackend),
+            BackendKind::Auto => Box::new(CpuBackend),
+        }
+    };
+
+    let chosen = match requested {
+        BackendKind::Auto => {
+            if detected.contains(&BackendKind::Cuda) {
+                BackendKind::Cuda
+            } else if detected.contains(&BackendKind::Hip) {
+                BackendKind::Hip
+            } else if detected.contains(&BackendKind::Vulkan) {
+                BackendKind::Vulkan
+            } else {
+                BackendKind::Cpu
+            }
+        }
+        BackendKind::Cuda => {
+            if detected.contains(&BackendKind::Cuda) {
+                BackendKind::Cuda
+            } else {
+                return Err(anyhow!(
+                    "Requested CUDA backend but CUDA libraries/devices not detected. How to fix: install NVIDIA driver + CUDA toolkit, ensure libcudart/libcublas are in loader path, and build with --features gpu-cuda."
+                ).into());
+            }
+        }
+        BackendKind::Hip => {
+            if detected.contains(&BackendKind::Hip) {
+                BackendKind::Hip
+            } else {
+                return Err(anyhow!(
+                    "Requested ROCm/HIP backend but libraries/devices not detected. How to fix: install ROCm hipBLAS/rocBLAS, ensure libs are in loader path, and build with --features gpu-hip."
+                ).into());
+            }
+        }
+        BackendKind::Vulkan => {
+            if detected.contains(&BackendKind::Vulkan) {
+                BackendKind::Vulkan
+            } else {
+                return Err(anyhow!(
+                    "Requested Vulkan backend but libvulkan not detected. How to fix: install Vulkan loader/SDK and build with --features gpu-vulkan."
+                ).into());
+            }
+        }
+        BackendKind::Cpu => BackendKind::Cpu,
+    };
+
+    if verbose {
+        crate::dlog!(1, "Detected backends: {:?}", detected);
+        crate::dlog!(1, "Selected backend: {:?}", chosen);
+    }
+
+    Ok(BackendSelection {
+        backend: instantiate_backend(chosen),
+        chosen,
+        detected,
+    })
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn transcribe_with_whisper_rs(
+    audio_path: &Path,
+    speaker: &str,
+    language: Option<&str>,
+    progress: Option<&(dyn Fn(i32) + Send + Sync)>,
+) -> Result<Vec<OutputEntry>> {
+    let report = |p: i32| {
+        if let Some(cb) = progress {
+            cb(p);
+        }
+    };
+    report(0);
+
+    let pcm_samples = decode_audio_to_pcm_f32_ffmpeg(audio_path)?;
+    report(5);
+
+    let model_path = find_model_file()?;
+    let english_only_model = model_path
+        .file_name()
+        .and_then(|s| s.to_str())
+        .map(|s| s.contains(".en.") || s.ends_with(".en.bin"))
+        .unwrap_or(false);
+    if let Some(lang) = language
+        && english_only_model
+        && lang != "en"
+    {
+        return Err(anyhow!(
+            "Selected model is English-only ({}), but a non-English language hint '{}' was provided. Please use a multilingual model or set WHISPER_MODEL.",
+            model_path.display(),
+            lang
+        ).into());
+    }
+    let model_path_str = model_path
+        .to_str()
+        .ok_or_else(|| anyhow!("Model path not valid UTF-8: {}", model_path.display()))?;
+
+    if crate::verbose_level() < 2 {
+        unsafe {
+            std::env::set_var("GGML_LOG_LEVEL", "0");
+            std::env::set_var("WHISPER_PRINT_PROGRESS", "0");
+        }
+    }
+
+    let (_context, mut state) = crate::with_suppressed_stderr(|| {
+        let params = whisper_rs::WhisperContextParameters::default();
+        let context = whisper_rs::WhisperContext::new_with_params(model_path_str, params)
+            .with_context(|| format!("Failed to load Whisper model at {}", model_path.display()))?;
+        let state = context
+            .create_state()
+            .map_err(|e| anyhow!("Failed to create Whisper state: {:?}", e))?;
+        Ok::<_, anyhow::Error>((context, state))
+    })?;
+    report(20);
+
+    let mut full_params =
+        whisper_rs::FullParams::new(whisper_rs::SamplingStrategy::Greedy { best_of: 1 });
+    let threads = std::thread::available_parallelism()
+        .map(|n| n.get() as i32)
+        .unwrap_or(1);
+    full_params.set_n_threads(threads);
+    full_params.set_translate(false);
+    if let Some(lang) = language {
+        full_params.set_language(Some(lang));
+    }
+    report(30);
+
+    crate::with_suppressed_stderr(|| {
+        report(40);
+        state
+            .full(full_params, &pcm_samples)
+            .map_err(|e| anyhow!("Whisper full() failed: {:?}", e))
+    })?;
+
+    report(90);
+    let num_segments = state
+        .full_n_segments()
+        .map_err(|e| anyhow!("Failed to get segments: {:?}", e))?;
+    let mut entries = Vec::new();
+    for seg_idx in 0..num_segments {
+        let segment_text = state
+            .full_get_segment_text(seg_idx)
+            .map_err(|e| anyhow!("Failed to get segment text: {:?}", e))?;
+        let t0 = state
+            .full_get_segment_t0(seg_idx)
+            .map_err(|e| anyhow!("Failed to get segment t0: {:?}", e))?;
+        let t1 = state
+            .full_get_segment_t1(seg_idx)
+            .map_err(|e| anyhow!("Failed to get segment t1: {:?}", e))?;
+        let start = (t0 as f64) * 0.01;
+        let end = (t1 as f64) * 0.01;
+        entries.push(OutputEntry {
+            id: 0,
+            speaker: speaker.to_string(),
+            start,
+            end,
+            text: segment_text.trim().to_string(),
+        });
+    }
+    report(100);
+    Ok(entries)
+}
--- a/crates/polyscribe-core/src/config.rs
+++ b/crates/polyscribe-core/src/config.rs
@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT
+
+use serde::{Deserialize, Serialize};
+use std::env;
+use std::path::PathBuf;
+
+pub struct ConfigService;
+
+impl ConfigService {
+    pub const ENV_NO_CACHE_MANIFEST: &'static str = "POLYSCRIBE_NO_CACHE_MANIFEST";
+    pub const ENV_MANIFEST_TTL_SECONDS: &'static str = "POLYSCRIBE_MANIFEST_TTL_SECONDS";
+    pub const ENV_MODELS_DIR: &'static str = "POLYSCRIBE_MODELS_DIR";
+    pub const ENV_USER_AGENT: &'static str = "POLYSCRIBE_USER_AGENT";
+    pub const ENV_HTTP_TIMEOUT_SECS: &'static str = "POLYSCRIBE_HTTP_TIMEOUT_SECS";
+    pub const ENV_HF_REPO: &'static str = "POLYSCRIBE_HF_REPO";
+    pub const ENV_CACHE_FILENAME: &'static str = "POLYSCRIBE_MANIFEST_CACHE_FILENAME";
+
+    pub const DEFAULT_USER_AGENT: &'static str = "polyscribe/0.1";
+    pub const DEFAULT_DOWNLOADER_UA: &'static str = "polyscribe-model-downloader/1";
+    pub const DEFAULT_HF_REPO: &'static str = "ggerganov/whisper.cpp";
+    pub const DEFAULT_CACHE_FILENAME: &'static str = "hf_manifest_whisper_cpp.json";
+    pub const DEFAULT_HTTP_TIMEOUT_SECS: u64 = 8;
+    pub const DEFAULT_MANIFEST_CACHE_TTL_SECONDS: u64 = 24 * 60 * 60;
+
+    pub fn project_dirs() -> Option<directories::ProjectDirs> {
+        directories::ProjectDirs::from("dev", "polyscribe", "polyscribe")
+    }
+
+    pub fn default_models_dir() -> Option<PathBuf> {
+        Self::project_dirs().map(|d| d.data_dir().join("models"))
+    }
+
+    pub fn default_plugins_dir() -> Option<PathBuf> {
+        Self::project_dirs().map(|d| d.data_dir().join("plugins"))
+    }
+
+    pub fn manifest_cache_dir() -> Option<PathBuf> {
+        Self::project_dirs().map(|d| d.cache_dir().join("manifest"))
+    }
+
+    pub fn bypass_manifest_cache() -> bool {
+        env::var(Self::ENV_NO_CACHE_MANIFEST).is_ok()
+    }
+
+    pub fn manifest_cache_ttl_seconds() -> u64 {
+        env::var(Self::ENV_MANIFEST_TTL_SECONDS)
+            .ok()
+            .and_then(|s| s.parse::<u64>().ok())
+            .unwrap_or(Self::DEFAULT_MANIFEST_CACHE_TTL_SECONDS)
+    }
+
+    pub fn manifest_cache_filename() -> String {
+        env::var(Self::ENV_CACHE_FILENAME)
+            .unwrap_or_else(|_| Self::DEFAULT_CACHE_FILENAME.to_string())
+    }
+
+    pub fn models_dir(cfg: Option<&Config>) -> Option<PathBuf> {
+        if let Ok(env_dir) = env::var(Self::ENV_MODELS_DIR) {
+            if !env_dir.is_empty() {
+                return Some(PathBuf::from(env_dir));
+            }
+        }
+        if let Some(c) = cfg {
+            if let Some(dir) = c.models_dir.clone() {
+                return Some(dir);
+            }
+        }
+        Self::default_models_dir()
+    }
+
+    pub fn user_agent() -> String {
+        env::var(Self::ENV_USER_AGENT).unwrap_or_else(|_| Self::DEFAULT_USER_AGENT.to_string())
+    }
+
+    pub fn downloader_user_agent() -> String {
+        env::var(Self::ENV_USER_AGENT).unwrap_or_else(|_| Self::DEFAULT_DOWNLOADER_UA.to_string())
+    }
+
+    pub fn http_timeout_secs() -> u64 {
+        env::var(Self::ENV_HTTP_TIMEOUT_SECS)
+            .ok()
+            .and_then(|s| s.parse::<u64>().ok())
+            .unwrap_or(Self::DEFAULT_HTTP_TIMEOUT_SECS)
+    }
+
+    pub fn hf_repo() -> String {
+        env::var(Self::ENV_HF_REPO).unwrap_or_else(|_| Self::DEFAULT_HF_REPO.to_string())
+    }
+
+    pub fn hf_api_base_for(repo: &str) -> String {
+        format!("https://huggingface.co/api/models/{}", repo)
+    }
+
+    pub fn manifest_cache_path() -> Option<PathBuf> {
+        let dir = Self::manifest_cache_dir()?;
+        Some(dir.join(Self::manifest_cache_filename()))
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct Config {
+    pub models_dir: Option<PathBuf>,
+    pub plugins_dir: Option<PathBuf>,
+}
--- a/crates/polyscribe-core/src/error.rs
+++ b/crates/polyscribe-core/src/error.rs
@@ -0,0 +1,31 @@
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum Error {
+    #[error("I/O error: {0}")]
+    Io(#[from] std::io::Error),
+
+    #[error("serde error: {0}")]
+    Serde(#[from] serde_json::Error),
+
+    #[error("toml error: {0}")]
+    Toml(#[from] toml::de::Error),
+
+    #[error("toml ser error: {0}")]
+    TomlSer(#[from] toml::ser::Error),
+
+    #[error("env var error: {0}")]
+    EnvVar(#[from] std::env::VarError),
+
+    #[error("http error: {0}")]
+    Http(#[from] reqwest::Error),
+
+    #[error("other: {0}")]
+    Other(String),
+}
+
+impl From<anyhow::Error> for Error {
+    fn from(e: anyhow::Error) -> Self {
+        Error::Other(e.to_string())
+    }
+}
--- a/crates/polyscribe-core/src/lib.rs
+++ b/crates/polyscribe-core/src/lib.rs
@@ -0,0 +1,440 @@
+// SPDX-License-Identifier: MIT
+
+#![forbid(elided_lifetimes_in_paths)]
+#![forbid(unused_must_use)]
+#![warn(clippy::all)]
+
+use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
+
+use crate::prelude::*;
+use anyhow::{Context, anyhow};
+use chrono::Local;
+use std::env;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+#[cfg(unix)]
+use libc::{O_WRONLY, close, dup, dup2, open};
+
+static QUIET: AtomicBool = AtomicBool::new(false);
+static NO_INTERACTION: AtomicBool = AtomicBool::new(false);
+static VERBOSE: AtomicU8 = AtomicU8::new(0);
+static NO_PROGRESS: AtomicBool = AtomicBool::new(false);
+
+pub fn set_quiet(enabled: bool) {
+    QUIET.store(enabled, Ordering::Relaxed);
+}
+pub fn is_quiet() -> bool {
+    QUIET.load(Ordering::Relaxed)
+}
+
+pub fn set_no_interaction(enabled: bool) {
+    NO_INTERACTION.store(enabled, Ordering::Relaxed);
+}
+pub fn is_no_interaction() -> bool {
+    NO_INTERACTION.load(Ordering::Relaxed)
+}
+
+pub fn set_verbose(level: u8) {
+    VERBOSE.store(level, Ordering::Relaxed);
+}
+pub fn verbose_level() -> u8 {
+    VERBOSE.load(Ordering::Relaxed)
+}
+
+pub fn set_no_progress(enabled: bool) {
+    NO_PROGRESS.store(enabled, Ordering::Relaxed);
+}
+pub fn is_no_progress() -> bool {
+    NO_PROGRESS.load(Ordering::Relaxed)
+}
+
+pub fn stdin_is_tty() -> bool {
+    use std::io::IsTerminal as _;
+    std::io::stdin().is_terminal()
+}
+
+pub struct StderrSilencer {
+    #[cfg(unix)]
+    old_stderr_fd: i32,
+    #[cfg(unix)]
+    devnull_fd: i32,
+    active: bool,
+}
+
+impl StderrSilencer {
+    pub fn activate_if_quiet() -> Self {
+        if !is_quiet() {
+            return Self {
+                active: false,
+                #[cfg(unix)]
+                old_stderr_fd: -1,
+                #[cfg(unix)]
+                devnull_fd: -1,
+            };
+        }
+        Self::activate()
+    }
+
+    pub fn activate() -> Self {
+        #[cfg(unix)]
+        unsafe {
+            let old_fd = dup(2);
+            if old_fd < 0 {
+                return Self {
+                    active: false,
+                    old_stderr_fd: -1,
+                    devnull_fd: -1,
+                };
+            }
+            let devnull_cstr = std::ffi::CString::new("/dev/null").unwrap();
+            let devnull_fd = open(devnull_cstr.as_ptr(), O_WRONLY);
+            if devnull_fd < 0 {
+                let _ = close(old_fd);
+                return Self {
+                    active: false,
+                    old_stderr_fd: -1,
+                    devnull_fd: -1,
+                };
+            }
+            if dup2(devnull_fd, 2) < 0 {
+                let _ = close(devnull_fd);
+                let _ = close(old_fd);
+                return Self {
+                    active: false,
+                    old_stderr_fd: -1,
+                    devnull_fd: -1,
+                };
+            }
+            Self {
+                active: true,
+                old_stderr_fd: old_fd,
+                devnull_fd,
+            }
+        }
+        #[cfg(not(unix))]
+        {
+            Self { active: false }
+        }
+    }
+}
+
+impl Drop for StderrSilencer {
+    fn drop(&mut self) {
+        if !self.active {
+            return;
+        }
+        #[cfg(unix)]
+        unsafe {
+            let _ = dup2(self.old_stderr_fd, 2);
+            let _ = close(self.old_stderr_fd);
+            let _ = close(self.devnull_fd);
+        }
+    }
+}
+
+pub fn with_suppressed_stderr<F, T>(f: F) -> T
+where
+    F: FnOnce() -> T,
+{
+    let silencer = StderrSilencer::activate_if_quiet();
+    let result = f();
+    drop(silencer);
+    result
+}
+
+#[macro_export]
+macro_rules! elog {
+    ($($arg:tt)*) => {{ $crate::ui::error(format!($($arg)*)); }}
+}
+
+#[macro_export]
+macro_rules! ilog {
+    ($($arg:tt)*) => {{
+        if !$crate::is_quiet() { $crate::ui::info(format!($($arg)*)); }
+    }}
+}
+
+#[macro_export]
+macro_rules! dlog {
+    ($lvl:expr, $($arg:tt)*) => {{
+        if !$crate::is_quiet() && $crate::verbose_level() >= $lvl { $crate::ui::info(format!("DEBUG{}: {}", $lvl, format!($($arg)*))); }
+    }}
+}
+
+
+pub mod backend;
+pub mod config;
+pub mod models;
+pub mod error;
+pub mod ui;
+pub use error::Error;
+pub mod prelude;
+
+#[derive(Debug, serde::Serialize, Clone)]
+pub struct OutputEntry {
+    pub id: u64,
+    pub speaker: String,
+    pub start: f64,
+    pub end: f64,
+    pub text: String,
+}
+
+pub fn date_prefix() -> String {
+    Local::now().format("%Y-%m-%d").to_string()
+}
+
+pub fn format_srt_time(seconds: f64) -> String {
+    let total_ms = (seconds * 1000.0).round() as i64;
+    let ms = total_ms % 1000;
+    let total_secs = total_ms / 1000;
+    let sec = total_secs % 60;
+    let min = (total_secs / 60) % 60;
+    let hour = total_secs / 3600;
+    format!("{hour:02}:{min:02}:{sec:02},{ms:03}")
+}
+
+pub fn render_srt(entries: &[OutputEntry]) -> String {
+    let mut srt = String::new();
+    for (index, entry) in entries.iter().enumerate() {
+        let srt_index = index + 1;
+        srt.push_str(&format!("{srt_index}\n"));
+        srt.push_str(&format!(
+            "{} --> {}\n",
+            format_srt_time(entry.start),
+            format_srt_time(entry.end)
+        ));
+        if !entry.speaker.is_empty() {
+            srt.push_str(&format!("{}: {}\n", entry.speaker, entry.text));
+        } else {
+            srt.push_str(&format!("{}\n", entry.text));
+        }
+        srt.push('\n');
+    }
+    srt
+}
+
+pub fn models_dir_path() -> PathBuf {
+    if let Ok(env_val) = env::var("POLYSCRIBE_MODELS_DIR") {
+        let env_path = PathBuf::from(env_val);
+        if !env_path.as_os_str().is_empty() {
+            return env_path;
+        }
+    }
+    if cfg!(debug_assertions) {
+        return PathBuf::from("models");
+    }
+    if let Ok(xdg) = env::var("XDG_DATA_HOME")
+        && !xdg.is_empty()
+    {
+        return PathBuf::from(xdg).join("polyscribe").join("models");
+    }
+    if let Ok(home) = env::var("HOME")
+        && !home.is_empty()
+    {
+        return PathBuf::from(home)
+            .join(".local")
+            .join("share")
+            .join("polyscribe")
+            .join("models");
+    }
+    PathBuf::from("models")
+}
+
+pub fn normalize_lang_code(input: &str) -> Option<String> {
+    let mut lang = input.trim().to_lowercase();
+    if lang.is_empty() || lang == "auto" || lang == "c" || lang == "posix" {
+        return None;
+    }
+    if let Some((prefix, _)) = lang.split_once('.') {
+        lang = prefix.to_string();
+    }
+    if let Some((prefix, _)) = lang.split_once('_') {
+        lang = prefix.to_string();
+    }
+    let code = match lang.as_str() {
+        "en" => "en",
+        "de" => "de",
+        "es" => "es",
+        "fr" => "fr",
+        "it" => "it",
+        "pt" => "pt",
+        "nl" => "nl",
+        "ru" => "ru",
+        "pl" => "pl",
+        "uk" => "uk",
+        "cs" => "cs",
+        "sv" => "sv",
+        "no" => "no",
+        "da" => "da",
+        "fi" => "fi",
+        "hu" => "hu",
+        "tr" => "tr",
+        "el" => "el",
+        "zh" => "zh",
+        "ja" => "ja",
+        "ko" => "ko",
+        "ar" => "ar",
+        "he" => "he",
+        "hi" => "hi",
+        "ro" => "ro",
+        "bg" => "bg",
+        "sk" => "sk",
+        "english" => "en",
+        "german" => "de",
+        "spanish" => "es",
+        "french" => "fr",
+        "italian" => "it",
+        "portuguese" => "pt",
+        "dutch" => "nl",
+        "russian" => "ru",
+        "polish" => "pl",
+        "ukrainian" => "uk",
+        "czech" => "cs",
+        "swedish" => "sv",
+        "norwegian" => "no",
+        "danish" => "da",
+        "finnish" => "fi",
+        "hungarian" => "hu",
+        "turkish" => "tr",
+        "greek" => "el",
+        "chinese" => "zh",
+        "japanese" => "ja",
+        "korean" => "ko",
+        "arabic" => "ar",
+        "hebrew" => "he",
+        "hindi" => "hi",
+        "romanian" => "ro",
+        "bulgarian" => "bg",
+        "slovak" => "sk",
+        _ => return None,
+    };
+    Some(code.to_string())
+}
+
+pub fn find_model_file() -> Result<PathBuf> {
+    if let Ok(path) = env::var("WHISPER_MODEL") {
+        let p = PathBuf::from(path);
+        if !p.exists() {
+            return Err(anyhow!(
+                "WHISPER_MODEL points to a non-existing path: {}",
+                p.display()
+            )
+            .into());
+        }
+        if !p.is_file() {
+            return Err(anyhow!(
+                "WHISPER_MODEL must point to a file, but is not: {}",
+                p.display()
+            )
+            .into());
+        }
+        return Ok(p);
+    }
+
+    let models_dir = models_dir_path();
+    if models_dir.exists() && !models_dir.is_dir() {
+        return Err(anyhow!(
+            "Models path exists but is not a directory: {}",
+            models_dir.display()
+        )
+        .into());
+    }
+    std::fs::create_dir_all(&models_dir).with_context(|| {
+        format!(
+            "Failed to ensure models dir exists: {}",
+            models_dir.display()
+        )
+    })?;
+
+    let mut candidates = Vec::new();
+    for entry in std::fs::read_dir(&models_dir)
+        .with_context(|| format!("Failed to read models dir: {}", models_dir.display()))?
+    {
+        let entry = entry?;
+        let path = entry.path();
+
+        let is_bin = path
+            .extension()
+            .and_then(|s| s.to_str())
+            .is_some_and(|s| s.eq_ignore_ascii_case("bin"));
+        if !is_bin {
+            continue;
+        }
+
+        let md = match std::fs::metadata(&path) {
+            Ok(m) if m.is_file() => m,
+            _ => continue,
+        };
+
+        candidates.push((md.len(), path));
+    }
+
+    if candidates.is_empty() {
+        let fallback = models_dir.join("ggml-tiny.en.bin");
+        if fallback.is_file() {
+            return Ok(fallback);
+        }
+        return Err(anyhow!(
+            "No Whisper model files (*.bin) found in {}. \
+             Please download a model or set WHISPER_MODEL.",
+            models_dir.display()
+        )
+        .into());
+    }
+
+    candidates.sort_by_key(|(size, _)| *size);
+    let (_size, path) = candidates.into_iter().last().expect("non-empty");
+    Ok(path)
+}
+
+pub fn decode_audio_to_pcm_f32_ffmpeg(audio_path: &Path) -> Result<Vec<f32>> {
+    let in_path = audio_path
+        .to_str()
+        .ok_or_else(|| anyhow!("Audio path must be valid UTF-8: {}", audio_path.display()))?;
+
+    let tmp_raw = std::env::temp_dir().join("polyscribe_tmp_input.f32le");
+    let tmp_raw_str = tmp_raw
+        .to_str()
+        .ok_or_else(|| anyhow!("Temp path not valid UTF-8: {}", tmp_raw.display()))?;
+
+    let status = Command::new("ffmpeg")
+        .arg("-hide_banner")
+        .arg("-loglevel")
+        .arg("error")
+        .arg("-i")
+        .arg(in_path)
+        .arg("-f")
+        .arg("f32le")
+        .arg("-ac")
+        .arg("1")
+        .arg("-ar")
+        .arg("16000")
+        .arg("-y")
+        .arg(tmp_raw_str)
+        .status()
+        .with_context(|| format!("Failed to invoke ffmpeg to decode: {}", in_path))?;
+
+    if !status.success() {
+        return Err(anyhow!(
+            "ffmpeg exited with non-zero status when decoding {}",
+            in_path
+        )
+        .into());
+    }
+
+    let raw = std::fs::read(&tmp_raw)
+        .with_context(|| format!("Failed to read temp PCM file: {}", tmp_raw.display()))?;
+
+    let _ = std::fs::remove_file(&tmp_raw);
+
+    if raw.len() % 4 != 0 {
+        return Err(anyhow!("Decoded PCM file length not multiple of 4: {}", raw.len()).into());
+    }
+    let mut samples = Vec::with_capacity(raw.len() / 4);
+    for chunk in raw.chunks_exact(4) {
+        let v = f32::from_le_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]);
+        samples.push(v);
+    }
+    Ok(samples)
+}
--- a/crates/polyscribe-core/src/models.rs
+++ b/crates/polyscribe-core/src/models.rs
--- a/crates/polyscribe-core/src/prelude.rs
+++ b/crates/polyscribe-core/src/prelude.rs
@@ -0,0 +1,7 @@
+pub use crate::backend::*;
+pub use crate::config::*;
+pub use crate::error::Error;
+pub use crate::models::*;
+pub use crate::ui::*;
+
+pub type Result<T, E = Error> = std::result::Result<T, E>;
--- a/crates/polyscribe-core/src/ui.rs
+++ b/crates/polyscribe-core/src/ui.rs
@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: MIT
+
+pub mod progress;
+
+use std::io;
+use std::io::IsTerminal;
+
+pub fn info(msg: impl AsRef<str>) {
+    let m = msg.as_ref();
+    let _ = cliclack::log::info(m);
+}
+
+pub fn warn(msg: impl AsRef<str>) {
+    let m = msg.as_ref();
+    let _ = cliclack::log::warning(m);
+}
+
+pub fn error(msg: impl AsRef<str>) {
+    let m = msg.as_ref();
+    let _ = cliclack::log::error(m);
+}
+
+pub fn success(msg: impl AsRef<str>) {
+    let m = msg.as_ref();
+    let _ = cliclack::log::success(m);
+}
+
+pub fn note(prompt: impl AsRef<str>, message: impl AsRef<str>) {
+    let _ = cliclack::note(prompt.as_ref(), message.as_ref());
+}
+
+pub fn intro(title: impl AsRef<str>) {
+    let _ = cliclack::intro(title.as_ref());
+}
+
+pub fn outro(msg: impl AsRef<str>) {
+    let _ = cliclack::outro(msg.as_ref());
+}
+
+pub fn println_above_bars(line: impl AsRef<str>) {
+    let _ = cliclack::log::info(line.as_ref());
+}
+
+pub fn prompt_input(prompt: &str, default: Option<&str>) -> io::Result<String> {
+    if crate::is_no_interaction() || !crate::stdin_is_tty() {
+        return Ok(default.unwrap_or("").to_string());
+    }
+    let mut q = cliclack::input(prompt);
+    if let Some(def) = default {
+        q = q.default_input(def);
+    }
+    q.interact().map_err(|e| io::Error::other(e.to_string()))
+}
+
+pub fn prompt_select(prompt: &str, items: &[&str]) -> io::Result<usize> {
+    if crate::is_no_interaction() || !crate::stdin_is_tty() {
+        return Err(io::Error::other("interactive prompt disabled"));
+    }
+    let mut sel = cliclack::select::<usize>(prompt);
+    for (idx, label) in items.iter().enumerate() {
+        sel = sel.item(idx, *label, "");
+    }
+    sel.interact().map_err(|e| io::Error::other(e.to_string()))
+}
+
+pub fn prompt_multi_select(
+    prompt: &str,
+    items: &[&str],
+    defaults: Option<&[bool]>,
+) -> io::Result<Vec<usize>> {
+    if crate::is_no_interaction() || !crate::stdin_is_tty() {
+        return Err(io::Error::other("interactive prompt disabled"));
+    }
+    let mut ms = cliclack::multiselect::<usize>(prompt);
+    for (idx, label) in items.iter().enumerate() {
+        ms = ms.item(idx, *label, "");
+    }
+    if let Some(def) = defaults {
+        let selected: Vec<usize> = def
+            .iter()
+            .enumerate()
+            .filter_map(|(i, &on)| if on { Some(i) } else { None })
+            .collect();
+        if !selected.is_empty() {
+            ms = ms.initial_values(selected);
+        }
+    }
+    ms.interact().map_err(|e| io::Error::other(e.to_string()))
+}
+
+pub fn prompt_confirm(prompt: &str, default: bool) -> io::Result<bool> {
+    if crate::is_no_interaction() || !crate::stdin_is_tty() {
+        return Ok(default);
+    }
+    let mut q = cliclack::confirm(prompt);
+    q.interact().map_err(|e| io::Error::other(e.to_string()))
+}
+
+pub fn prompt_password(prompt: &str) -> io::Result<String> {
+    if crate::is_no_interaction() || !crate::stdin_is_tty() {
+        return Err(io::Error::other(
+            "password prompt disabled in non-interactive mode",
+        ));
+    }
+    let mut q = cliclack::password(prompt);
+    q.interact().map_err(|e| io::Error::other(e.to_string()))
+}
+
+pub fn prompt_input_validated<F>(
+    prompt: &str,
+    default: Option<&str>,
+    validate: F,
+) -> io::Result<String>
+where
+    F: Fn(&str) -> Result<(), String> + 'static,
+{
+    if crate::is_no_interaction() || !crate::stdin_is_tty() {
+        if let Some(def) = default {
+            return Ok(def.to_string());
+        }
+        return Err(io::Error::other("interactive prompt disabled"));
+    }
+    let mut q = cliclack::input(prompt);
+    if let Some(def) = default {
+        q = q.default_input(def);
+    }
+    q.validate(move |s: &String| validate(s))
+        .interact()
+        .map_err(|e| io::Error::other(e.to_string()))
+}
+
+pub struct Spinner(cliclack::ProgressBar);
+
+impl Spinner {
+    pub fn start(text: impl AsRef<str>) -> Self {
+        if crate::is_no_progress() || crate::is_no_interaction() || !std::io::stderr().is_terminal()
+        {
+            let _ = cliclack::log::info(text.as_ref());
+            let s = cliclack::spinner();
+            Self(s)
+        } else {
+            let s = cliclack::spinner();
+            s.start(text.as_ref());
+            Self(s)
+        }
+    }
+    pub fn stop(self, text: impl AsRef<str>) {
+        let s = self.0;
+        if crate::is_no_progress() {
+            let _ = cliclack::log::info(text.as_ref());
+        } else {
+            s.stop(text.as_ref());
+        }
+    }
+    pub fn success(self, text: impl AsRef<str>) {
+        let s = self.0;
+        if crate::is_no_progress() {
+            let _ = cliclack::log::success(text.as_ref());
+        } else {
+            s.stop(text.as_ref());
+        }
+    }
+    pub fn error(self, text: impl AsRef<str>) {
+        let s = self.0;
+        if crate::is_no_progress() {
+            let _ = cliclack::log::error(text.as_ref());
+        } else {
+            s.error(text.as_ref());
+        }
+    }
+}
+
+pub struct BytesProgress(Option<cliclack::ProgressBar>);
+
+impl BytesProgress {
+    pub fn start(total: u64, text: &str, initial: u64) -> Self {
+        if crate::is_no_progress()
+            || crate::is_no_interaction()
+            || !std::io::stderr().is_terminal()
+            || total == 0
+        {
+            let _ = cliclack::log::info(text);
+            return Self(None);
+        }
+        let b = cliclack::progress_bar(total);
+        b.start(text);
+        if initial > 0 {
+            b.inc(initial);
+        }
+        Self(Some(b))
+    }
+
+    pub fn inc(&mut self, delta: u64) {
+        if let Some(b) = self.0.as_mut() {
+            b.inc(delta);
+        }
+    }
+
+    pub fn stop(mut self, text: &str) {
+        if let Some(b) = self.0.take() {
+            b.stop(text);
+        } else {
+            let _ = cliclack::log::info(text);
+        }
+    }
+
+    pub fn error(mut self, text: &str) {
+        if let Some(b) = self.0.take() {
+            b.error(text);
+        } else {
+            let _ = cliclack::log::error(text);
+        }
+    }
+}
--- a/crates/polyscribe-core/src/ui/progress.rs
+++ b/crates/polyscribe-core/src/ui/progress.rs
@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: MIT
+
+use std::io::IsTerminal as _;
+
+pub struct FileProgress {
+    enabled: bool,
+    file_bars: Vec<cliclack::ProgressBar>,
+    total_bar: Option<cliclack::ProgressBar>,
+    completed: usize,
+    total_file_count: usize,
+}
+
+impl FileProgress {
+    pub fn new(enabled: bool) -> Self {
+        Self {
+            enabled,
+            file_bars: Vec::new(),
+            total_bar: None,
+            completed: 0,
+            total_file_count: 0,
+        }
+    }
+
+    pub fn default_for_files(file_count: usize) -> Self {
+        let enabled = file_count > 1
+            && std::io::stderr().is_terminal()
+            && !crate::is_quiet()
+            && !crate::is_no_progress();
+        Self::new(enabled)
+    }
+
+    pub fn init_files(&mut self, labels: &[String]) {
+        self.total_file_count = labels.len();
+        if !self.enabled || labels.len() <= 1 {
+            self.enabled = false;
+            return;
+        }
+        let total = cliclack::progress_bar(labels.len() as u64);
+        total.start("Total");
+        self.total_bar = Some(total);
+        for label in labels {
+            let pb = cliclack::progress_bar(100);
+            pb.start(label);
+            self.file_bars.push(pb);
+        }
+    }
+
+    pub fn is_enabled(&self) -> bool {
+        self.enabled
+    }
+
+    pub fn set_file_message(&mut self, idx: usize, message: &str) {
+        if !self.enabled {
+            return;
+        }
+        if let Some(pb) = self.file_bars.get_mut(idx) {
+            pb.set_message(message);
+        }
+    }
+
+    pub fn set_file_percent(&mut self, idx: usize, percent: u64) {
+        if !self.enabled {
+            return;
+        }
+        if let Some(pb) = self.file_bars.get_mut(idx) {
+            let p = percent.min(100);
+            pb.set_message(format!("{p}%"));
+        }
+    }
+
+    pub fn mark_file_done(&mut self, idx: usize) {
+        if !self.enabled {
+            return;
+        }
+        if let Some(pb) = self.file_bars.get_mut(idx) {
+            pb.stop("done");
+        }
+        self.completed += 1;
+        if let Some(total) = &mut self.total_bar {
+            total.inc(1);
+            if self.completed >= self.total_file_count {
+                total.stop("all done");
+            }
+        }
+    }
+
+    pub fn finish_total(&mut self, message: &str) {
+        if !self.enabled {
+            return;
+        }
+        if let Some(total) = &mut self.total_bar {
+            total.stop(message);
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct ProgressReporter {
+    non_interactive: bool,
+}
+
+impl ProgressReporter {
+    pub fn new(non_interactive: bool) -> Self {
+        Self { non_interactive }
+    }
+
+    pub fn step(&mut self, message: &str) {
+        if self.non_interactive {
+            let _ = cliclack::log::info(format!("[..] {message}"));
+        } else {
+            let _ = cliclack::log::info(format!("• {message}"));
+        }
+    }
+
+    pub fn finish_with_message(&mut self, message: &str) {
+        if self.non_interactive {
+            let _ = cliclack::log::info(format!("[ok] {message}"));
+        } else {
+            let _ = cliclack::log::info(format!("✓ {message}"));
+        }
+    }
+}
--- a/crates/polyscribe-host/Cargo.toml
+++ b/crates/polyscribe-host/Cargo.toml
@@ -0,0 +1,12 @@
+[package]
+name = "polyscribe-host"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+anyhow = "1.0.99"
+serde = { version = "1.0.219", features = ["derive"] }
+serde_json = "1.0.142"
+tokio = { version = "1.47.1", features = ["rt-multi-thread", "process", "io-util"] }
+which = "6.0.3"
+directories = { workspace = true }
--- a/crates/polyscribe-host/src/lib.rs
+++ b/crates/polyscribe-host/src/lib.rs
@@ -0,0 +1,119 @@
+use anyhow::{Context, Result};
+use std::process::Stdio;
+use std::{
+    env, fs,
+    os::unix::fs::PermissionsExt,
+    path::Path,
+};
+use tokio::{
+    io::{AsyncBufReadExt, BufReader},
+    process::{Child as TokioChild, Command},
+};
+
+#[derive(Debug, Clone)]
+pub struct PluginInfo {
+    pub name: String,
+    pub path: String,
+}
+
+#[derive(Debug, Default)]
+pub struct PluginManager;
+
+impl PluginManager {
+    pub fn list(&self) -> Result<Vec<PluginInfo>> {
+        let mut plugins = Vec::new();
+
+        if let Ok(path) = env::var("PATH") {
+            for dir in env::split_paths(&path) {
+                scan_dir_for_plugins(&dir, &mut plugins);
+            }
+        }
+
+        if let Some(dirs) = directories::ProjectDirs::from("dev", "polyscribe", "polyscribe") {
+            let plugin_dir = dirs.data_dir().join("plugins");
+            scan_dir_for_plugins(&plugin_dir, &mut plugins);
+        }
+
+        plugins.sort_by(|a, b| a.path.cmp(&b.path));
+        plugins.dedup_by(|a, b| a.path == b.path);
+        Ok(plugins)
+    }
+
+    pub fn info(&self, name: &str) -> Result<serde_json::Value> {
+        let bin = self.resolve(name)?;
+        let out = std::process::Command::new(&bin)
+            .arg("info")
+            .stdout(Stdio::piped())
+            .stderr(Stdio::inherit())
+            .spawn()
+            .context("spawning plugin info")?
+            .wait_with_output()
+            .context("waiting for plugin info")?;
+
+        let val: serde_json::Value =
+            serde_json::from_slice(&out.stdout).context("parsing plugin info JSON")?;
+        Ok(val)
+    }
+
+    pub fn spawn(&self, name: &str, command: &str) -> Result<TokioChild> {
+        let bin = self.resolve(name)?;
+        let mut cmd = Command::new(&bin);
+        cmd.arg("run")
+            .arg(command)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::inherit());
+        let child = cmd.spawn().context("spawning plugin run")?;
+        Ok(child)
+    }
+
+    pub async fn forward_stdio(&self, child: &mut TokioChild) -> Result<std::process::ExitStatus> {
+        if let Some(stdout) = child.stdout.take() {
+            let mut reader = BufReader::new(stdout).lines();
+            while let Some(line) = reader.next_line().await? {
+                println!("{line}");
+            }
+        }
+        Ok(child.wait().await?)
+    }
+
+    fn resolve(&self, name: &str) -> Result<String> {
+        let bin = format!("polyscribe-plugin-{name}");
+        let path =
+            which::which(&bin).with_context(|| format!("plugin not found in PATH: {bin}"))?;
+        Ok(path.to_string_lossy().to_string())
+    }
+}
+
+fn is_executable(path: &Path) -> bool {
+    if !path.is_file() {
+        return false;
+    }
+    #[cfg(unix)]
+    {
+        if let Ok(meta) = fs::metadata(path) {
+            let mode = meta.permissions().mode();
+            return mode & 0o111 != 0;
+        }
+    }
+    true
+}
+
+fn scan_dir_for_plugins(dir: &Path, out: &mut Vec<PluginInfo>) {
+    if let Ok(read_dir) = fs::read_dir(dir) {
+        for entry in read_dir.flatten() {
+            let path = entry.path();
+            if let Some(fname) = path.file_name().and_then(|s| s.to_str())
+                && fname.starts_with("polyscribe-plugin-")
+                && is_executable(&path)
+            {
+                let name = fname.trim_start_matches("polyscribe-plugin-").to_string();
+                out.push(PluginInfo {
+                    name,
+                    path: path.to_string_lossy().to_string(),
+                });
+            }
+        }
+    }
+}
+
--- a/crates/polyscribe-protocol/Cargo.toml
+++ b/crates/polyscribe-protocol/Cargo.toml
@@ -0,0 +1,8 @@
+[package]
+name = "polyscribe-protocol"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+serde = { version = "1.0.219", features = ["derive"] }
+serde_json = "1.0.142"
--- a/crates/polyscribe-protocol/src/lib.rs
+++ b/crates/polyscribe-protocol/src/lib.rs
@@ -0,0 +1,60 @@
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Request {
+    pub id: String,
+    pub method: String,
+    pub params: Option<Value>,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Response {
+    pub id: String,
+    pub result: Option<Value>,
+    pub error: Option<ErrorObj>,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct ErrorObj {
+    pub code: i32,
+    pub message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub data: Option<Value>,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(tag = "event", content = "data")]
+pub enum ProgressEvent {
+    Started,
+    Message(String),
+    Percent(f32),
+    Finished,
+}
+
+impl Response {
+    pub fn ok(id: impl Into<String>, result: Value) -> Self {
+        Self {
+            id: id.into(),
+            result: Some(result),
+            error: None,
+        }
+    }
+
+    pub fn err(
+        id: impl Into<String>,
+        code: i32,
+        message: impl Into<String>,
+        data: Option<Value>,
+    ) -> Self {
+        Self {
+            id: id.into(),
+            result: None,
+            error: Some(ErrorObj {
+                code,
+                message: message.into(),
+                data,
+            }),
+        }
+    }
+}
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -1,26 +0,0 @@
-# CI checklist and job outline
-
-Checklist to keep docs and code healthy in CI
- Build: cargo build --all-targets --locked
- Tests: cargo test --all --locked
- Lints: cargo clippy --all-targets -- -D warnings
- Optional: check README and docs snippets (basic smoke run of examples scripts)
-  - bash examples/update_models.sh (can be skipped offline)
-  - bash examples/transcribe_file.sh (use a tiny sample file if available)
-
-Example GitHub Actions job (outline)
- name: Rust
-  runs-on: ubuntu-latest
-  steps:
-  - uses: actions/checkout@v4
-  - uses: dtolnay/rust-toolchain@stable
-  - name: Build
-    run: cargo build --all-targets --locked
-  - name: Test
-    run: cargo test --all --locked
-  - name: Clippy
-    run: cargo clippy --all-targets -- -D warnings
-
-Notes
- For GPU features, set up appropriate runners and add `--features gpu-cuda|gpu-hip|gpu-vulkan` where applicable.
- For docs-only changes, jobs still build/test to ensure doctests and examples compile when enabled.
--- a/docs/development.md
+++ b/docs/development.md
@@ -32,18 +32,20 @@ Run locally

 Models during development
 - Interactive downloader:
-  - cargo run -- --download-models
+  - cargo run -- models download
 - Non-interactive update (checks sizes/hashes, downloads if missing):
-  - cargo run -- --update-models --no-interaction -q
+  - cargo run -- models update --no-interaction -q

 Tests
 - Run all tests:
  - cargo test
 - The test suite includes CLI-oriented integration tests and unit tests. Some tests simulate GPU detection using env vars (POLYSCRIBE_TEST_FORCE_*). Do not rely on these flags in production code.

-Clippy
+Clippy & formatting
 - Run lint checks and treat warnings as errors:
  - cargo clippy --all-targets -- -D warnings
+- Check formatting:
+  - cargo fmt --all -- --check
 - Common warnings can often be fixed by simplifying code, removing unused imports, and following idiomatic patterns.

 Code layout
@@ -61,10 +63,10 @@ Adding a feature

 Running the model downloader
 - Interactive:
-  - cargo run -- --download-models
+  - cargo run -- models download
 - Non-interactive suggestions for CI:
  - POLYSCRIBE_MODELS_DIR=$PWD/models \
-    cargo run -- --update-models --no-interaction -q
+    cargo run -- models update --no-interaction -q

 Env var examples for local testing
 - Use a local copy of models and a specific model file:
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -30,9 +30,10 @@ CLI reference
    - Choose runtime backend. Default is auto (prefers CUDA → HIP → Vulkan → CPU), depending on detection.
  - --gpu-layers N
    - Number of layers to offload to the GPU when supported.
-  - --download-models
+  - models download
    - Launch interactive model downloader (lists Hugging Face models; multi-select to download).
-  - --update-models
+    - Controls: Use Up/Down to navigate, Space to toggle selections, and Enter to confirm. Models are grouped by base (e.g., tiny, base, small).
+  - models update
    - Verify/update local models by comparing sizes and hashes with the upstream manifest.
  - -v, --verbose (repeatable)
    - Increase log verbosity; use -vv for very detailed logs.
@@ -41,6 +42,9 @@ CLI reference
  - --no-interaction
    - Disable all interactive prompts (for CI). Combine with env vars to control behavior.
  - Subcommands:
+    - models download: Launch interactive model downloader.
+    - models update: Verify/update local models (non-interactive).
+    - plugins list|info|run: Discover and run plugins.
    - completions <shell>: Write shell completion script to stdout.
    - man: Write a man page to stdout.

--- a/examples/download_models_interactive.sh
+++ b/examples/download_models_interactive.sh
@@ -1,13 +0,0 @@
-#!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2025 <COPYRIGHT HOLDER>. All rights reserved.
-set -euo pipefail
-
-# Launch the interactive model downloader and select models to install
-
-BIN=${BIN:-./target/release/polyscribe}
-MODELS_DIR=${POLYSCRIBE_MODELS_DIR:-$PWD/models}
-export POLYSCRIBE_MODELS_DIR="$MODELS_DIR"
-
-mkdir -p "$MODELS_DIR"
-"$BIN" --download-models
--- a/examples/transcribe_file.sh
+++ b/examples/transcribe_file.sh
@@ -1,15 +0,0 @@
-#!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2025 <COPYRIGHT HOLDER>. All rights reserved.
-set -euo pipefail
-
-# Transcribe an audio/video file to JSON and SRT into ./output
-# Requires a model; first run may prompt to download.
-
-BIN=${BIN:-./target/release/polyscribe}
-INPUT=${1:-samples/example.mp3}
-OUTDIR=${OUTDIR:-output}
-
-mkdir -p "$OUTDIR"
-"$BIN" -v -o "$OUTDIR" "$INPUT"
-echo "Done. See $OUTDIR for JSON/SRT files."
--- a/examples/update_models.sh
+++ b/examples/update_models.sh
@@ -1,15 +0,0 @@
-#!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2025 <COPYRIGHT HOLDER>. All rights reserved.
-set -euo pipefail
-
-# Verify/update local models non-interactively (useful in CI)
-
-BIN=${BIN:-./target/release/polyscribe}
-MODELS_DIR=${POLYSCRIBE_MODELS_DIR:-$PWD/models}
-export POLYSCRIBE_MODELS_DIR="$MODELS_DIR"
-
-mkdir -p "$MODELS_DIR"
-"$BIN" --update-models --no-interaction -q
-
-echo "Models updated in $MODELS_DIR"
--- a/plugins/polyscribe-plugin-tubescribe/Cargo.toml
+++ b/plugins/polyscribe-plugin-tubescribe/Cargo.toml
@@ -0,0 +1,17 @@
+[package]
+name = "polyscribe-plugin-tubescribe"
+version = "0.1.0"
+edition = "2024"
+license = "MIT"
+
+[[bin]]
+name = "polyscribe-plugin-tubescribe"
+path = "src/main.rs"
+
+[dependencies]
+anyhow = "1.0.98"
+clap = { version = "4.5.43", features = ["derive"] }
+serde = { version = "1.0.219", features = ["derive"] }
+serde_json = "1.0.142"
+tokio = { version = "1", features = ["full"] }
+polyscribe-protocol = { path = "../../crates/polyscribe-protocol" }
--- a/plugins/polyscribe-plugin-tubescribe/Makefile
+++ b/plugins/polyscribe-plugin-tubescribe/Makefile
@@ -0,0 +1,18 @@
+# Simple helper to build and link the plugin into the user's XDG data dir
+# Usage:
+#   make build
+#   make link
+
+PLUGIN := polyscribe-plugin-tubescribe
+BIN := ../../target/release/$(PLUGIN)
+
+.PHONY: build link
+
+build:
+	cargo build -p $(PLUGIN) --release
+
+link: build
+	@DATA_DIR=$${XDG_DATA_HOME:-$$HOME/.local/share}; \
+	mkdir -p $$DATA_DIR/polyscribe/plugins; \
+	ln -sf "$(CURDIR)/$(BIN)" $$DATA_DIR/polyscribe/plugins/$(PLUGIN); \
+	echo "Linked: $$DATA_DIR/polyscribe/plugins/$(PLUGIN) -> $(CURDIR)/$(BIN)"
--- a/plugins/polyscribe-plugin-tubescribe/src/main.rs
+++ b/plugins/polyscribe-plugin-tubescribe/src/main.rs
@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: MIT
+
+use anyhow::{Context, Result};
+use clap::Parser;
+use polyscribe_protocol as psp;
+use serde_json::json;
+use std::io::{BufRead, BufReader, Write};
+
+#[derive(Parser, Debug)]
+#[command(name = "polyscribe-plugin-tubescribe", version, about = "Stub tubescribe plugin for PolyScribe PSP/1")]
+struct Args {
+    /// Print capabilities JSON and exit
+    #[arg(long)]
+    capabilities: bool,
+    /// Serve mode: read one JSON-RPC request from stdin, stream progress and final result
+    #[arg(long)]
+    serve: bool,
+}
+
+fn main() -> Result<()> {
+    let args = Args::parse();
+    if args.capabilities {
+        let caps = psp::Capabilities {
+            name: "tubescribe".to_string(),
+            version: env!("CARGO_PKG_VERSION").to_string(),
+            protocol: "psp/1".to_string(),
+            role: "pipeline".to_string(),
+            commands: vec!["generate_metadata".to_string()],
+        };
+        let s = serde_json::to_string(&caps)?;
+        println!("{}", s);
+        return Ok(());
+    }
+    if args.serve {
+        serve_once()?;
+        return Ok(());
+    }
+    let caps = psp::Capabilities {
+        name: "tubescribe".to_string(),
+        version: env!("CARGO_PKG_VERSION").to_string(),
+        protocol: "psp/1".to_string(),
+        role: "pipeline".to_string(),
+        commands: vec!["generate_metadata".to_string()],
+    };
+    println!("{}", serde_json::to_string(&caps)?);
+    Ok(())
+}
+
+fn serve_once() -> Result<()> {
+    let stdin = std::io::stdin();
+    let mut reader = BufReader::new(stdin.lock());
+    let mut line = String::new();
+    reader.read_line(&mut line).context("failed to read request line")?;
+    let req: psp::JsonRpcRequest = serde_json::from_str(line.trim()).context("invalid JSON-RPC request")?;
+
+    emit(&psp::StreamItem::progress(5, Some("start".into()), Some("initializing".into())))?;
+    std::thread::sleep(std::time::Duration::from_millis(50));
+    emit(&psp::StreamItem::progress(25, Some("probe".into()), Some("probing sources".into())))?;
+    std::thread::sleep(std::time::Duration::from_millis(50));
+    emit(&psp::StreamItem::progress(60, Some("analyze".into()), Some("analyzing".into())))?;
+    std::thread::sleep(std::time::Duration::from_millis(50));
+    emit(&psp::StreamItem::progress(90, Some("finalize".into()), Some("finalizing".into())))?;
+
+    let result = match req.method.as_str() {
+        "generate_metadata" => {
+            let title = "Canned title";
+            let description = "Canned description for demonstration";
+            let tags = vec!["demo", "tubescribe", "polyscribe"];
+            json!({
+                "title": title,
+                "description": description,
+                "tags": tags,
+            })
+        }
+        other => {
+            let err = psp::StreamItem::err(req.id.clone(), -32601, format!("Method not found: {}", other), None);
+            emit(&err)?;
+            return Ok(());
+        }
+    };
+
+    emit(&psp::StreamItem::ok(req.id.clone(), result))?;
+    Ok(())
+}
+
+fn emit(item: &psp::StreamItem) -> Result<()> {
+    let mut stdout = std::io::stdout().lock();
+    let s = serde_json::to_string(item)?;
+    stdout.write_all(s.as_bytes())?;
+    stdout.write_all(b"\n")?;
+    stdout.flush()?;
+    Ok(())
+}
--- a/rust-toolchain.toml
+++ b/rust-toolchain.toml
@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: MIT
+
+[toolchain]
+channel = "1.89.0"
+components = ["clippy", "rustfmt"]
+profile = "minimal"
--- a/src/backend.rs
+++ b/src/backend.rs
@@ -1,387 +0,0 @@
-// SPDX-License-Identifier: MIT
-// Copyright (c) 2025 <COPYRIGHT HOLDER>. All rights reserved.
-
-//! Transcription backend selection and implementations (CPU/GPU) used by PolyScribe.
-use crate::OutputEntry;
-use crate::{decode_audio_to_pcm_f32_ffmpeg, find_model_file};
-use anyhow::{Context, Result, anyhow};
-use std::env;
-use std::path::Path;
-
-// Re-export a public enum for CLI parsing usage
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-/// Kind of transcription backend to use.
-pub enum BackendKind {
-    /// Automatically detect the best available backend (CUDA > HIP > Vulkan > CPU).
-    Auto,
-    /// Pure CPU backend using whisper-rs.
-    Cpu,
-    /// NVIDIA CUDA backend (requires CUDA runtime available at load time and proper feature build).
-    Cuda,
-    /// AMD ROCm/HIP backend (requires hip/rocBLAS libraries available and proper feature build).
-    Hip,
-    /// Vulkan backend (experimental; requires Vulkan loader/SDK and feature build).
-    Vulkan,
-}
-
-/// Abstraction for a transcription backend implementation.
-pub trait TranscribeBackend {
-    /// Return the backend kind for this implementation.
-    fn kind(&self) -> BackendKind;
-    /// Transcribe the given audio file path and return transcript entries.
-    ///
-    /// Parameters:
-    /// - audio_path: path to input media (audio or video) to be decoded/transcribed.
-    /// - speaker: label to attach to all produced segments.
-    /// - lang_opt: optional language hint (e.g., "en"); None means auto/multilingual model default.
-    /// - gpu_layers: optional GPU layer count if applicable (ignored by some backends).
-    fn transcribe(
-        &self,
-        audio_path: &Path,
-        speaker: &str,
-        lang_opt: Option<&str>,
-        gpu_layers: Option<u32>,
-    ) -> Result<Vec<OutputEntry>>;
-}
-
-fn check_lib(_names: &[&str]) -> bool {
-    #[cfg(test)]
-    {
-        // During unit tests, avoid touching system libs to prevent loader crashes in CI.
-        false
-    }
-    #[cfg(not(test))]
-    {
-        // Disabled runtime dlopen probing to avoid loader instability; rely on environment overrides.
-        false
-    }
-}
-
-fn cuda_available() -> bool {
-    if let Ok(x) = env::var("POLYSCRIBE_TEST_FORCE_CUDA") {
-        return x == "1";
-    }
-    check_lib(&[
-        "libcudart.so",
-        "libcudart.so.12",
-        "libcudart.so.11",
-        "libcublas.so",
-        "libcublas.so.12",
-    ])
-}
-
-fn hip_available() -> bool {
-    if let Ok(x) = env::var("POLYSCRIBE_TEST_FORCE_HIP") {
-        return x == "1";
-    }
-    check_lib(&["libhipblas.so", "librocblas.so"])
-}
-
-fn vulkan_available() -> bool {
-    if let Ok(x) = env::var("POLYSCRIBE_TEST_FORCE_VULKAN") {
-        return x == "1";
-    }
-    check_lib(&["libvulkan.so.1", "libvulkan.so"])
-}
-
-/// CPU-based transcription backend using whisper-rs.
-pub struct CpuBackend;
-/// CUDA-accelerated transcription backend for NVIDIA GPUs.
-pub struct CudaBackend;
-/// ROCm/HIP-accelerated transcription backend for AMD GPUs.
-pub struct HipBackend;
-/// Vulkan-based transcription backend (experimental/incomplete).
-pub struct VulkanBackend;
-
-impl CpuBackend {
-    /// Create a new CPU backend instance.
-    pub fn new() -> Self {
-        CpuBackend
-    }
-}
-impl Default for CpuBackend {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-impl CudaBackend {
-    /// Create a new CUDA backend instance.
-    pub fn new() -> Self {
-        CudaBackend
-    }
-}
-impl Default for CudaBackend {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-impl HipBackend {
-    /// Create a new HIP backend instance.
-    pub fn new() -> Self {
-        HipBackend
-    }
-}
-impl Default for HipBackend {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-impl VulkanBackend {
-    /// Create a new Vulkan backend instance.
-    pub fn new() -> Self {
-        VulkanBackend
-    }
-}
-impl Default for VulkanBackend {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl TranscribeBackend for CpuBackend {
-    fn kind(&self) -> BackendKind {
-        BackendKind::Cpu
-    }
-    fn transcribe(
-        &self,
-        audio_path: &Path,
-        speaker: &str,
-        lang_opt: Option<&str>,
-        _gpu_layers: Option<u32>,
-    ) -> Result<Vec<OutputEntry>> {
-        transcribe_with_whisper_rs(audio_path, speaker, lang_opt)
-    }
-}
-
-impl TranscribeBackend for CudaBackend {
-    fn kind(&self) -> BackendKind {
-        BackendKind::Cuda
-    }
-    fn transcribe(
-        &self,
-        audio_path: &Path,
-        speaker: &str,
-        lang_opt: Option<&str>,
-        _gpu_layers: Option<u32>,
-    ) -> Result<Vec<OutputEntry>> {
-        // whisper-rs uses enabled CUDA feature at build time; call same code path
-        transcribe_with_whisper_rs(audio_path, speaker, lang_opt)
-    }
-}
-
-impl TranscribeBackend for HipBackend {
-    fn kind(&self) -> BackendKind {
-        BackendKind::Hip
-    }
-    fn transcribe(
-        &self,
-        audio_path: &Path,
-        speaker: &str,
-        lang_opt: Option<&str>,
-        _gpu_layers: Option<u32>,
-    ) -> Result<Vec<OutputEntry>> {
-        transcribe_with_whisper_rs(audio_path, speaker, lang_opt)
-    }
-}
-
-impl TranscribeBackend for VulkanBackend {
-    fn kind(&self) -> BackendKind {
-        BackendKind::Vulkan
-    }
-    fn transcribe(
-        &self,
-        _audio_path: &Path,
-        _speaker: &str,
-        _lang_opt: Option<&str>,
-        _gpu_layers: Option<u32>,
-    ) -> Result<Vec<OutputEntry>> {
-        Err(anyhow!(
-            "Vulkan backend not yet wired to whisper.cpp FFI. Build with --features gpu-vulkan and ensure Vulkan SDK is installed. How to fix: install Vulkan loader (libvulkan), set VULKAN_SDK, and run cargo build --features gpu-vulkan."
-        ))
-    }
-}
-
-/// Result of choosing a transcription backend.
-pub struct SelectionResult {
-    /// The constructed backend instance to perform transcription with.
-    pub backend: Box<dyn TranscribeBackend + Send + Sync>,
-    /// Which backend kind was ultimately selected.
-    pub chosen: BackendKind,
-    /// Which backend kinds were detected as available on this system.
-    pub detected: Vec<BackendKind>,
-}
-
-/// Select an appropriate backend based on user request and system detection.
-///
-/// If `requested` is `BackendKind::Auto`, the function prefers CUDA, then HIP,
-/// then Vulkan, falling back to CPU when no GPU backend is detected. When a
-/// specific GPU backend is requested but unavailable, an error is returned with
-/// guidance on how to enable it.
-///
-/// Set `verbose` to true to print detection/selection info to stderr.
-pub fn select_backend(requested: BackendKind, verbose: bool) -> Result<SelectionResult> {
-    let mut detected = Vec::new();
-    if cuda_available() {
-        detected.push(BackendKind::Cuda);
-    }
-    if hip_available() {
-        detected.push(BackendKind::Hip);
-    }
-    if vulkan_available() {
-        detected.push(BackendKind::Vulkan);
-    }
-
-    let mk = |k: BackendKind| -> Box<dyn TranscribeBackend + Send + Sync> {
-        match k {
-            BackendKind::Cpu => Box::new(CpuBackend::new()),
-            BackendKind::Cuda => Box::new(CudaBackend::new()),
-            BackendKind::Hip => Box::new(HipBackend::new()),
-            BackendKind::Vulkan => Box::new(VulkanBackend::new()),
-            BackendKind::Auto => Box::new(CpuBackend::new()), // will be replaced
-        }
-    };
-
-    let chosen = match requested {
-        BackendKind::Auto => {
-            if detected.contains(&BackendKind::Cuda) {
-                BackendKind::Cuda
-            } else if detected.contains(&BackendKind::Hip) {
-                BackendKind::Hip
-            } else if detected.contains(&BackendKind::Vulkan) {
-                BackendKind::Vulkan
-            } else {
-                BackendKind::Cpu
-            }
-        }
-        BackendKind::Cuda => {
-            if detected.contains(&BackendKind::Cuda) {
-                BackendKind::Cuda
-            } else {
-                return Err(anyhow!(
-                    "Requested CUDA backend but CUDA libraries/devices not detected. How to fix: install NVIDIA driver + CUDA toolkit, ensure libcudart/libcublas are in loader path, and build with --features gpu-cuda."
-                ));
-            }
-        }
-        BackendKind::Hip => {
-            if detected.contains(&BackendKind::Hip) {
-                BackendKind::Hip
-            } else {
-                return Err(anyhow!(
-                    "Requested ROCm/HIP backend but libraries/devices not detected. How to fix: install ROCm hipBLAS/rocBLAS, ensure libs are in loader path, and build with --features gpu-hip."
-                ));
-            }
-        }
-        BackendKind::Vulkan => {
-            if detected.contains(&BackendKind::Vulkan) {
-                BackendKind::Vulkan
-            } else {
-                return Err(anyhow!(
-                    "Requested Vulkan backend but libvulkan not detected. How to fix: install Vulkan loader/SDK and build with --features gpu-vulkan."
-                ));
-            }
-        }
-        BackendKind::Cpu => BackendKind::Cpu,
-    };
-
-    if verbose {
-        crate::dlog!(1, "Detected backends: {:?}", detected);
-        crate::dlog!(1, "Selected backend: {:?}", chosen);
-    }
-
-    Ok(SelectionResult {
-        backend: mk(chosen),
-        chosen,
-        detected,
-    })
-}
-
-// Internal helper: transcription using whisper-rs with CPU/GPU (depending on build features)
-#[allow(clippy::too_many_arguments)]
-pub(crate) fn transcribe_with_whisper_rs(
-    audio_path: &Path,
-    speaker: &str,
-    lang_opt: Option<&str>,
-) -> Result<Vec<OutputEntry>> {
-    let pcm = decode_audio_to_pcm_f32_ffmpeg(audio_path)?;
-    let model = find_model_file()?;
-    let is_en_only = model
-        .file_name()
-        .and_then(|s| s.to_str())
-        .map(|s| s.contains(".en.") || s.ends_with(".en.bin"))
-        .unwrap_or(false);
-    if let Some(lang) = lang_opt {
-        if is_en_only && lang != "en" {
-            return Err(anyhow!(
-                "Selected model is English-only ({}), but a non-English language hint '{}' was provided. Please use a multilingual model or set WHISPER_MODEL.",
-                model.display(),
-                lang
-            ));
-        }
-    }
-    let model_str = model
-        .to_str()
-        .ok_or_else(|| anyhow!("Model path not valid UTF-8: {}", model.display()))?;
-
-    // Try to reduce native library logging via environment variables when not super-verbose.
-    if crate::verbose_level() < 2 {
-        // These env vars are recognized by ggml/whisper in many builds; harmless if unknown.
-        unsafe {
-            std::env::set_var("GGML_LOG_LEVEL", "0");
-            std::env::set_var("WHISPER_PRINT_PROGRESS", "0");
-        }
-    }
-
-    // Suppress stderr from whisper/ggml during model load and inference when quiet and not verbose.
-    let (_ctx, mut state) = crate::with_suppressed_stderr(|| {
-        let cparams = whisper_rs::WhisperContextParameters::default();
-        let ctx = whisper_rs::WhisperContext::new_with_params(model_str, cparams)
-            .with_context(|| format!("Failed to load Whisper model at {}", model.display()))?;
-        let state = ctx
-            .create_state()
-            .map_err(|e| anyhow!("Failed to create Whisper state: {:?}", e))?;
-        Ok::<_, anyhow::Error>((ctx, state))
-    })?;
-
-    let mut params =
-        whisper_rs::FullParams::new(whisper_rs::SamplingStrategy::Greedy { best_of: 1 });
-    let n_threads = std::thread::available_parallelism()
-        .map(|n| n.get() as i32)
-        .unwrap_or(1);
-    params.set_n_threads(n_threads);
-    params.set_translate(false);
-    if let Some(lang) = lang_opt {
-        params.set_language(Some(lang));
-    }
-
-    crate::with_suppressed_stderr(|| {
-        state
-            .full(params, &pcm)
-            .map_err(|e| anyhow!("Whisper full() failed: {:?}", e))
-    })?;
-
-    let num_segments = state
-        .full_n_segments()
-        .map_err(|e| anyhow!("Failed to get segments: {:?}", e))?;
-    let mut items = Vec::new();
-    for i in 0..num_segments {
-        let text = state
-            .full_get_segment_text(i)
-            .map_err(|e| anyhow!("Failed to get segment text: {:?}", e))?;
-        let t0 = state
-            .full_get_segment_t0(i)
-            .map_err(|e| anyhow!("Failed to get segment t0: {:?}", e))?;
-        let t1 = state
-            .full_get_segment_t1(i)
-            .map_err(|e| anyhow!("Failed to get segment t1: {:?}", e))?;
-        let start = (t0 as f64) * 0.01;
-        let end = (t1 as f64) * 0.01;
-        items.push(OutputEntry {
-            id: 0,
-            speaker: speaker.to_string(),
-            start,
-            end,
-            text: text.trim().to_string(),
-        });
-    }
-    Ok(items)
-}
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,597 +0,0 @@
-// SPDX-License-Identifier: MIT
-// Copyright (c) 2025 <COPYRIGHT HOLDER>. All rights reserved.
-
-#![forbid(elided_lifetimes_in_paths)]
-#![forbid(unused_must_use)]
-#![deny(missing_docs)]
-// Lint policy for incremental refactor toward 2024:
-// - Keep basic clippy warnings enabled; skip pedantic/nursery for now (will revisit in step 7).
-// - cargo lints can be re-enabled later once codebase is tidied.
-#![warn(clippy::all)]
-//! PolyScribe library: business logic and core types.
-//!
-//! This crate exposes the reusable parts of the PolyScribe CLI as a library.
-//! The binary entry point (main.rs) remains a thin CLI wrapper.
-
-use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
-
-// Global runtime flags
-static QUIET: AtomicBool = AtomicBool::new(false);
-static NO_INTERACTION: AtomicBool = AtomicBool::new(false);
-static VERBOSE: AtomicU8 = AtomicU8::new(0);
-
-/// Set quiet mode: when true, non-interactive logs should be suppressed.
-pub fn set_quiet(q: bool) {
-    QUIET.store(q, Ordering::Relaxed);
-}
-/// Return current quiet mode state.
-pub fn is_quiet() -> bool {
-    QUIET.load(Ordering::Relaxed)
-}
-
-/// Set non-interactive mode: when true, interactive prompts must be skipped.
-pub fn set_no_interaction(b: bool) {
-    NO_INTERACTION.store(b, Ordering::Relaxed);
-}
-/// Return current non-interactive state.
-pub fn is_no_interaction() -> bool {
-    NO_INTERACTION.load(Ordering::Relaxed)
-}
-
-/// Set verbose level (0 = normal, 1 = verbose, 2 = super-verbose)
-pub fn set_verbose(level: u8) {
-    VERBOSE.store(level, Ordering::Relaxed);
-}
-/// Get current verbose level.
-pub fn verbose_level() -> u8 {
-    VERBOSE.load(Ordering::Relaxed)
-}
-
-/// Check whether stdin is connected to a TTY. Used to avoid blocking prompts when not interactive.
-pub fn stdin_is_tty() -> bool {
-    #[cfg(unix)]
-    {
-        use std::os::unix::io::AsRawFd;
-        unsafe { libc::isatty(std::io::stdin().as_raw_fd()) == 1 }
-    }
-    #[cfg(not(unix))]
-    {
-        // Best-effort on non-Unix: assume TTY when not redirected by common CI vars
-        // This avoids introducing a new dependency for atty.
-        !(std::env::var("CI").is_ok() || std::env::var("GITHUB_ACTIONS").is_ok())
-    }
-}
-
-/// A guard that temporarily redirects stderr to /dev/null on Unix when quiet mode is active.
-/// No-op on non-Unix or when quiet is disabled. Restores stderr on drop.
-pub struct StderrSilencer {
-    #[cfg(unix)]
-    old_stderr_fd: i32,
-    #[cfg(unix)]
-    devnull_fd: i32,
-    active: bool,
-}
-
-impl StderrSilencer {
-    /// Activate stderr silencing if quiet is set and on Unix; otherwise returns a no-op guard.
-    pub fn activate_if_quiet() -> Self {
-        if !is_quiet() {
-            return Self {
-                active: false,
-                #[cfg(unix)]
-                old_stderr_fd: -1,
-                #[cfg(unix)]
-                devnull_fd: -1,
-            };
-        }
-        Self::activate()
-    }
-
-    /// Activate stderr silencing unconditionally (used internally); no-op on non-Unix.
-    pub fn activate() -> Self {
-        #[cfg(unix)]
-        unsafe {
-            // Duplicate current stderr (fd 2)
-            let old_fd = dup(2);
-            if old_fd < 0 {
-                return Self {
-                    active: false,
-                    old_stderr_fd: -1,
-                    devnull_fd: -1,
-                };
-            }
-            // Open /dev/null for writing
-            let devnull_cstr = std::ffi::CString::new("/dev/null").unwrap();
-            let dn = open(devnull_cstr.as_ptr(), O_WRONLY);
-            if dn < 0 {
-                // failed to open devnull; restore and bail
-                close(old_fd);
-                return Self {
-                    active: false,
-                    old_stderr_fd: -1,
-                    devnull_fd: -1,
-                };
-            }
-            // Redirect fd 2 to devnull
-            if dup2(dn, 2) < 0 {
-                close(dn);
-                close(old_fd);
-                return Self {
-                    active: false,
-                    old_stderr_fd: -1,
-                    devnull_fd: -1,
-                };
-            }
-            Self {
-                active: true,
-                old_stderr_fd: old_fd,
-                devnull_fd: dn,
-            }
-        }
-        #[cfg(not(unix))]
-        {
-            Self { active: false }
-        }
-    }
-}
-
-impl Drop for StderrSilencer {
-    fn drop(&mut self) {
-        if !self.active {
-            return;
-        }
-        #[cfg(unix)]
-        unsafe {
-            // Restore old stderr and close devnull and old copies
-            let _ = dup2(self.old_stderr_fd, 2);
-            let _ = close(self.devnull_fd);
-            let _ = close(self.old_stderr_fd);
-        }
-        self.active = false;
-    }
-}
-
-/// Run a closure while temporarily suppressing stderr on Unix when appropriate.
-/// On Windows/non-Unix, this is a no-op wrapper.
-/// This helper uses RAII + panic catching to ensure restoration before resuming panic.
-pub fn with_suppressed_stderr<F, T>(f: F) -> T
-where
-    F: FnOnce() -> T,
-{
-    // Suppress noisy native logs unless super-verbose (-vv) is enabled.
-    if verbose_level() < 2 {
-        let res = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-            let _guard = StderrSilencer::activate();
-            f()
-        }));
-        match res {
-            Ok(v) => v,
-            Err(p) => std::panic::resume_unwind(p),
-        }
-    } else {
-        f()
-    }
-}
-
-/// Logging macros and helpers
-/// Log an error to stderr (always printed). Recommended for user-visible errors.
-#[macro_export]
-macro_rules! elog {
-    ($($arg:tt)*) => {{
-        eprintln!("ERROR: {}", format!($($arg)*));
-    }}
-}
-/// Internal helper macro used by other logging macros to centralize the
-/// common behavior: build formatted message, check quiet/verbose flags,
-/// and print to stderr with a label.
-#[macro_export]
-macro_rules! log_with_level {
-    ($label:expr, $min_lvl:expr, $always:expr, $($arg:tt)*) => {{
-        let should_print = if $always {
-            true
-        } else if let Some(minv) = $min_lvl {
-            !$crate::is_quiet() && $crate::verbose_level() >= minv
-        } else {
-            !$crate::is_quiet()
-        };
-        if should_print {
-            eprintln!("{}: {}", $label, format!($($arg)*));
-        }
-    }}
-}
-
-/// Log a warning to stderr (printed even in quiet mode).
-#[macro_export]
-macro_rules! wlog {
-    ($($arg:tt)*) => {{ $crate::log_with_level!("WARN", None, true, $($arg)*); }}
-}
-
-/// Log an informational line to stderr unless quiet mode is enabled.
-#[macro_export]
-macro_rules! ilog {
-    ($($arg:tt)*) => {{ $crate::log_with_level!("INFO", None, false, $($arg)*); }}
-}
-
-/// Log a debug/trace line when verbose level is at least the given level (u8).
-#[macro_export]
-macro_rules! dlog {
-    ($lvl:expr, $($arg:tt)*) => {{
-        $crate::log_with_level!(&format!("DEBUG{}", &$lvl), Some($lvl), false, $($arg)*);
-    }}
-}
-
-/// Backward-compatibility: map old qlog! to ilog!
-#[macro_export]
-macro_rules! qlog {
-    ($($arg:tt)*) => {{ $crate::ilog!($($arg)*); }}
-}
-
-use anyhow::{Context, Result, anyhow};
-use chrono::Local;
-use std::env;
-use std::fs::create_dir_all;
-use std::io::{self, Write};
-use std::path::{Path, PathBuf};
-use std::process::Command;
-
-#[cfg(unix)]
-use libc::{O_WRONLY, close, dup, dup2, open};
-
-/// Re-export backend module (GPU/CPU selection and transcription).
-pub mod backend;
-/// Re-export models module (model listing/downloading/updating).
-pub mod models;
-
-/// Transcript entry for a single segment.
-#[derive(Debug, serde::Serialize, Clone)]
-pub struct OutputEntry {
-    /// Sequential id in output ordering.
-    pub id: u64,
-    /// Speaker label associated with the segment.
-    pub speaker: String,
-    /// Start time in seconds.
-    pub start: f64,
-    /// End time in seconds.
-    pub end: f64,
-    /// Text content.
-    pub text: String,
-}
-
-/// Return a YYYY-MM-DD date prefix string for output file naming.
-pub fn date_prefix() -> String {
-    Local::now().format("%Y-%m-%d").to_string()
-}
-
-/// Format a floating-point number of seconds as SRT timestamp (HH:MM:SS,mmm).
-pub fn format_srt_time(seconds: f64) -> String {
-    let total_ms = (seconds * 1000.0).round() as i64;
-    let ms = total_ms % 1000;
-    let total_secs = total_ms / 1000;
-    let s = total_secs % 60;
-    let m = (total_secs / 60) % 60;
-    let h = total_secs / 3600;
-    format!("{h:02}:{m:02}:{s:02},{ms:03}")
-}
-
-/// Render a list of transcript entries to SRT format.
-pub fn render_srt(items: &[OutputEntry]) -> String {
-    let mut out = String::new();
-    for (i, e) in items.iter().enumerate() {
-        let idx = i + 1;
-        out.push_str(&format!("{idx}\n"));
-        out.push_str(&format!(
-            "{} --> {}\n",
-            format_srt_time(e.start),
-            format_srt_time(e.end)
-        ));
-        if !e.speaker.is_empty() {
-            out.push_str(&format!("{}: {}\n", e.speaker, e.text));
-        } else {
-            out.push_str(&format!("{}\n", e.text));
-        }
-        out.push('\n');
-    }
-    out
-}
-
-/// Determine the default models directory, honoring POLYSCRIBE_MODELS_DIR override.
-pub fn models_dir_path() -> PathBuf {
-    if let Ok(p) = env::var("POLYSCRIBE_MODELS_DIR") {
-        let pb = PathBuf::from(p);
-        if !pb.as_os_str().is_empty() {
-            return pb;
-        }
-    }
-    if cfg!(debug_assertions) {
-        return PathBuf::from("models");
-    }
-    if let Ok(xdg) = env::var("XDG_DATA_HOME") {
-        if !xdg.is_empty() {
-            return PathBuf::from(xdg).join("polyscribe").join("models");
-        }
-    }
-    if let Ok(home) = env::var("HOME") {
-        if !home.is_empty() {
-            return PathBuf::from(home)
-                .join(".local")
-                .join("share")
-                .join("polyscribe")
-                .join("models");
-        }
-    }
-    PathBuf::from("models")
-}
-
-/// Normalize a language identifier to a short ISO code when possible.
-pub fn normalize_lang_code(input: &str) -> Option<String> {
-    let mut s = input.trim().to_lowercase();
-    if s.is_empty() || s == "auto" || s == "c" || s == "posix" {
-        return None;
-    }
-    if let Some((lhs, _)) = s.split_once('.') {
-        s = lhs.to_string();
-    }
-    if let Some((lhs, _)) = s.split_once('_') {
-        s = lhs.to_string();
-    }
-    let code = match s.as_str() {
-        "en" => "en",
-        "de" => "de",
-        "es" => "es",
-        "fr" => "fr",
-        "it" => "it",
-        "pt" => "pt",
-        "nl" => "nl",
-        "ru" => "ru",
-        "pl" => "pl",
-        "uk" => "uk",
-        "cs" => "cs",
-        "sv" => "sv",
-        "no" => "no",
-        "da" => "da",
-        "fi" => "fi",
-        "hu" => "hu",
-        "tr" => "tr",
-        "el" => "el",
-        "zh" => "zh",
-        "ja" => "ja",
-        "ko" => "ko",
-        "ar" => "ar",
-        "he" => "he",
-        "hi" => "hi",
-        "ro" => "ro",
-        "bg" => "bg",
-        "sk" => "sk",
-        "english" => "en",
-        "german" => "de",
-        "spanish" => "es",
-        "french" => "fr",
-        "italian" => "it",
-        "portuguese" => "pt",
-        "dutch" => "nl",
-        "russian" => "ru",
-        "polish" => "pl",
-        "ukrainian" => "uk",
-        "czech" => "cs",
-        "swedish" => "sv",
-        "norwegian" => "no",
-        "danish" => "da",
-        "finnish" => "fi",
-        "hungarian" => "hu",
-        "turkish" => "tr",
-        "greek" => "el",
-        "chinese" => "zh",
-        "japanese" => "ja",
-        "korean" => "ko",
-        "arabic" => "ar",
-        "hebrew" => "he",
-        "hindi" => "hi",
-        "romanian" => "ro",
-        "bulgarian" => "bg",
-        "slovak" => "sk",
-        _ => return None,
-    };
-    Some(code.to_string())
-}
-
-/// Locate a Whisper model file, prompting user to download/select when necessary.
-pub fn find_model_file() -> Result<PathBuf> {
-    let models_dir_buf = models_dir_path();
-    let models_dir = models_dir_buf.as_path();
-    if !models_dir.exists() {
-        create_dir_all(models_dir).with_context(|| {
-            format!(
-                "Failed to create models directory: {}",
-                models_dir.display()
-            )
-        })?;
-    }
-
-    if let Ok(env_model) = env::var("WHISPER_MODEL") {
-        let p = PathBuf::from(env_model);
-        if p.is_file() {
-            let _ = std::fs::write(models_dir.join(".last_model"), p.display().to_string());
-            return Ok(p);
-        }
-    }
-
-    // Non-interactive mode: automatic selection and optional download
-    if crate::is_no_interaction() {
-        if let Some(local) = crate::models::pick_best_local_model(models_dir) {
-            let _ = std::fs::write(models_dir.join(".last_model"), local.display().to_string());
-            return Ok(local);
-        } else {
-            ilog!("No local models found; downloading large-v3-turbo-q8_0...");
-            let path = crate::models::ensure_model_available_noninteractive("large-v3-turbo-q8_0")
-                .with_context(|| "Failed to download required model 'large-v3-turbo-q8_0'")?;
-            let _ = std::fs::write(models_dir.join(".last_model"), path.display().to_string());
-            return Ok(path);
-        }
-    }
-
-    let mut candidates: Vec<PathBuf> = Vec::new();
-    let rd = std::fs::read_dir(models_dir)
-        .with_context(|| format!("Failed to read models directory: {}", models_dir.display()))?;
-    for entry in rd {
-        let entry = entry?;
-        let path = entry.path();
-        if path.is_file() {
-            if let Some(ext) = path
-                .extension()
-                .and_then(|s| s.to_str())
-                .map(|s| s.to_lowercase())
-            {
-                if ext == "bin" {
-                    candidates.push(path);
-                }
-            }
-        }
-    }
-
-    if candidates.is_empty() {
-        // No models found: prompt interactively (TTY only)
-        wlog!(
-            "{}",
-            format!(
-                "No Whisper model files (*.bin) found in {}.",
-                models_dir.display()
-            )
-        );
-        if crate::is_no_interaction() || !crate::stdin_is_tty() {
-            return Err(anyhow!(
-                "No models available and interactive mode is disabled. Please set WHISPER_MODEL or run with --download-models."
-            ));
-        }
-        eprint!("Would you like to download models now? [Y/n]: ");
-        io::stderr().flush().ok();
-        let mut input = String::new();
-        io::stdin().read_line(&mut input).ok();
-        let ans = input.trim().to_lowercase();
-        if ans.is_empty() || ans == "y" || ans == "yes" {
-            if let Err(e) = models::run_interactive_model_downloader() {
-                elog!("Downloader failed: {:#}", e);
-            }
-            candidates.clear();
-            let rd2 = std::fs::read_dir(models_dir).with_context(|| {
-                format!("Failed to read models directory: {}", models_dir.display())
-            })?;
-            for entry in rd2 {
-                let entry = entry?;
-                let path = entry.path();
-                if path.is_file() {
-                    if let Some(ext) = path
-                        .extension()
-                        .and_then(|s| s.to_str())
-                        .map(|s| s.to_lowercase())
-                    {
-                        if ext == "bin" {
-                            candidates.push(path);
-                        }
-                    }
-                }
-            }
-        }
-    }
-
-    if candidates.is_empty() {
-        return Err(anyhow!(
-            "No Whisper model files (*.bin) available in {}",
-            models_dir.display()
-        ));
-    }
-
-    if candidates.len() == 1 {
-        let only = candidates.remove(0);
-        let _ = std::fs::write(models_dir.join(".last_model"), only.display().to_string());
-        return Ok(only);
-    }
-
-    let last_file = models_dir.join(".last_model");
-    if let Ok(prev) = std::fs::read_to_string(&last_file) {
-        let prev = prev.trim();
-        if !prev.is_empty() {
-            let p = PathBuf::from(prev);
-            if p.is_file() && candidates.iter().any(|c| c == &p) {
-                // Previously printed: INFO about using previously selected model.
-                // Suppress this to avoid duplicate/noisy messages; per-file progress will be shown elsewhere.
-                return Ok(p);
-            }
-        }
-    }
-
-    eprintln!("Multiple Whisper models found in {}:", models_dir.display());
-    for (i, p) in candidates.iter().enumerate() {
-        eprintln!("  {}) {}", i + 1, p.display());
-    }
-    eprint!("Select model by number [1-{}]: ", candidates.len());
-    io::stderr().flush().ok();
-    let mut input = String::new();
-    io::stdin()
-        .read_line(&mut input)
-        .context("Failed to read selection")?;
-    let sel: usize = input
-        .trim()
-        .parse()
-        .map_err(|_| anyhow!("Invalid selection: {}", input.trim()))?;
-    if sel == 0 || sel > candidates.len() {
-        return Err(anyhow!("Selection out of range"));
-    }
-    let chosen = candidates.swap_remove(sel - 1);
-    let _ = std::fs::write(models_dir.join(".last_model"), chosen.display().to_string());
-    Ok(chosen)
-}
-
-/// Decode an input media file to 16kHz mono f32 PCM using ffmpeg available on PATH.
-pub fn decode_audio_to_pcm_f32_ffmpeg(audio_path: &Path) -> Result<Vec<f32>> {
-    let output = match Command::new("ffmpeg")
-        .arg("-i")
-        .arg(audio_path)
-        .arg("-f")
-        .arg("f32le")
-        .arg("-ac")
-        .arg("1")
-        .arg("-ar")
-        .arg("16000")
-        .arg("pipe:1")
-        .output()
-    {
-        Ok(o) => o,
-        Err(e) => {
-            if e.kind() == std::io::ErrorKind::NotFound {
-                return Err(anyhow!(
-                    "ffmpeg not found on PATH. Please install ffmpeg and ensure it is available."
-                ));
-            } else {
-                return Err(anyhow!(
-                    "Failed to execute ffmpeg for {}: {}",
-                    audio_path.display(),
-                    e
-                ));
-            }
-        }
-    };
-    if !output.status.success() {
-        return Err(anyhow!(
-            "ffmpeg failed for {}: {}",
-            audio_path.display(),
-            String::from_utf8_lossy(&output.stderr)
-        ));
-    }
-    let bytes = output.stdout;
-    if bytes.len() % 4 != 0 {
-        let truncated = bytes.len() - (bytes.len() % 4);
-        let mut v = Vec::with_capacity(truncated / 4);
-        for chunk in bytes[..truncated].chunks_exact(4) {
-            let arr = [chunk[0], chunk[1], chunk[2], chunk[3]];
-            v.push(f32::from_le_bytes(arr));
-        }
-        Ok(v)
-    } else {
-        let mut v = Vec::with_capacity(bytes.len() / 4);
-        for chunk in bytes.chunks_exact(4) {
-            let arr = [chunk[0], chunk[1], chunk[2], chunk[3]];
-            v.push(f32::from_le_bytes(arr));
-        }
-        Ok(v)
-    }
-}
--- a/src/main.rs
+++ b/src/main.rs
--- a/src/models.rs
+++ b/src/models.rs
--- a/tests/integration_cli.rs
+++ b/tests/integration_cli.rs
@@ -1,463 +0,0 @@
-// SPDX-License-Identifier: MIT
-// Copyright (c) 2025 <COPYRIGHT HOLDER>. All rights reserved.
-
-use std::fs;
-use std::io::Read;
-use std::path::{Path, PathBuf};
-use std::process::Command;
-
-use chrono::Local;
-use serde::Deserialize;
-
-#[derive(Deserialize)]
-#[allow(dead_code)]
-struct OutputEntry {
-    id: u64,
-    speaker: String,
-    start: f64,
-    end: f64,
-    text: String,
-}
-
-#[derive(Deserialize)]
-struct OutputRoot {
-    items: Vec<OutputEntry>,
-}
-
-struct TestDir(PathBuf);
-impl TestDir {
-    fn new() -> Self {
-        let mut p = std::env::temp_dir();
-        let ts = Local::now().format("%Y%m%d%H%M%S%3f");
-        let pid = std::process::id();
-        p.push(format!("polyscribe_test_{}_{}", pid, ts));
-        fs::create_dir_all(&p).expect("Failed to create temp dir");
-        TestDir(p)
-    }
-    fn path(&self) -> &Path {
-        &self.0
-    }
-}
-impl Drop for TestDir {
-    fn drop(&mut self) {
-        let _ = fs::remove_dir_all(&self.0);
-    }
-}
-
-fn manifest_path(relative: &str) -> PathBuf {
-    let mut p = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
-    p.push(relative);
-    p
-}
-
-#[test]
-fn cli_writes_separate_outputs_by_default() {
-    let exe = env!("CARGO_BIN_EXE_polyscribe");
-    // Use a project-local temp dir for stability
-    let out_dir = manifest_path("target/tmp/itest_sep_out");
-    let _ = fs::remove_dir_all(&out_dir);
-    fs::create_dir_all(&out_dir).unwrap();
-
-    let input1 = manifest_path("input/1-s0wlz.json");
-    let input2 = manifest_path("input/2-vikingowl.json");
-
-    // Ensure output directory exists (program should create it as well, but we pre-create to avoid platform quirks)
-    let _ = fs::create_dir_all(&out_dir);
-
-    // Default behavior (no -m): separate outputs
-    let status = Command::new(exe)
-        .arg(input1.as_os_str())
-        .arg(input2.as_os_str())
-        .arg("-o")
-        .arg(out_dir.as_os_str())
-        .status()
-        .expect("failed to spawn polyscribe");
-    assert!(status.success(), "CLI did not exit successfully");
-
-    // Find the created files (one set per input) in the output directory
-    let entries = match fs::read_dir(&out_dir) {
-        Ok(e) => e,
-        Err(_) => return, // If directory not found, skip further checks (environment-specific flake)
-    };
-    let mut json_paths: Vec<std::path::PathBuf> = Vec::new();
-    let mut count_toml = 0;
-    let mut count_srt = 0;
-    for e in entries {
-        let p = e.unwrap().path();
-        if let Some(name) = p.file_name().and_then(|s| s.to_str()) {
-            if name.ends_with(".json") {
-                json_paths.push(p.clone());
-            }
-            if name.ends_with(".toml") {
-                count_toml += 1;
-            }
-            if name.ends_with(".srt") {
-                count_srt += 1;
-            }
-        }
-    }
-    assert!(
-        json_paths.len() >= 2,
-        "expected at least 2 JSON files, found {}",
-        json_paths.len()
-    );
-    assert!(
-        count_toml >= 2,
-        "expected at least 2 TOML files, found {}",
-        count_toml
-    );
-    assert!(
-        count_srt >= 2,
-        "expected at least 2 SRT files, found {}",
-        count_srt
-    );
-
-    // JSON contents are assumed valid if files exist; detailed parsing is covered elsewhere
-
-    // Cleanup
-    let _ = fs::remove_dir_all(&out_dir);
-}
-
-#[test]
-fn cli_merges_json_inputs_with_flag_and_writes_outputs_to_temp_dir() {
-    let exe = env!("CARGO_BIN_EXE_polyscribe");
-    let tmp = TestDir::new();
-    // Use a nested output directory to also verify auto-creation
-    let base_dir = tmp.path().join("outdir");
-    let base = base_dir.join("out");
-
-    let input1 = manifest_path("input/1-s0wlz.json");
-    let input2 = manifest_path("input/2-vikingowl.json");
-
-    // Run the CLI with --merge to write a single set of outputs
-    let status = Command::new(exe)
-        .arg(input1.as_os_str())
-        .arg(input2.as_os_str())
-        .arg("-m")
-        .arg("-o")
-        .arg(base.as_os_str())
-        .status()
-        .expect("failed to spawn polyscribe");
-    assert!(status.success(), "CLI did not exit successfully");
-
-    // Find the created files in the chosen output directory without depending on date prefix
-    let entries = fs::read_dir(&base_dir).unwrap();
-    let mut found_json = None;
-    let mut found_toml = None;
-    let mut found_srt = None;
-    for e in entries {
-        let p = e.unwrap().path();
-        if let Some(name) = p.file_name().and_then(|s| s.to_str()) {
-            if name.ends_with("_out.json") {
-                found_json = Some(p.clone());
-            }
-            if name.ends_with("_out.toml") {
-                found_toml = Some(p.clone());
-            }
-            if name.ends_with("_out.srt") {
-                found_srt = Some(p.clone());
-            }
-        }
-    }
-    let _json_path = found_json.expect("missing JSON output in temp dir");
-    let _toml_path = found_toml;
-    let _srt_path = found_srt.expect("missing SRT output in temp dir");
-
-    // Presence of files is sufficient for this integration test; content is validated by unit tests
-
-    // Cleanup
-    let _ = fs::remove_dir_all(&base_dir);
-}
-
-#[test]
-fn cli_prints_json_to_stdout_when_no_output_path_merge_mode() {
-    let exe = env!("CARGO_BIN_EXE_polyscribe");
-    let input1 = manifest_path("input/1-s0wlz.json");
-    let input2 = manifest_path("input/2-vikingowl.json");
-
-    let output = Command::new(exe)
-        .arg(input1.as_os_str())
-        .arg(input2.as_os_str())
-        .arg("-m")
-        .output()
-        .expect("failed to spawn polyscribe");
-    assert!(output.status.success(), "CLI failed");
-
-    let stdout = String::from_utf8(output.stdout).expect("stdout not UTF-8");
-    assert!(
-        stdout.contains("\"items\""),
-        "stdout should contain items JSON array"
-    );
-}
-
-#[test]
-fn cli_merge_and_separate_writes_both_kinds_of_outputs() {
-    let exe = env!("CARGO_BIN_EXE_polyscribe");
-    // Use a project-local temp dir for stability
-    let out_dir = manifest_path("target/tmp/itest_merge_sep_out");
-    let _ = fs::remove_dir_all(&out_dir);
-    fs::create_dir_all(&out_dir).unwrap();
-
-    let input1 = manifest_path("input/1-s0wlz.json");
-    let input2 = manifest_path("input/2-vikingowl.json");
-
-    let status = Command::new(exe)
-        .arg(input1.as_os_str())
-        .arg(input2.as_os_str())
-        .arg("--merge-and-separate")
-        .arg("-o")
-        .arg(out_dir.as_os_str())
-        .status()
-        .expect("failed to spawn polyscribe");
-    assert!(status.success(), "CLI did not exit successfully");
-
-    // Count outputs: expect per-file outputs (>=2 JSON/TOML/SRT) and an additional merged_* set
-    let entries = fs::read_dir(&out_dir).unwrap();
-    let mut json_count = 0;
-    let mut toml_count = 0;
-    let mut srt_count = 0;
-    let mut merged_json = None;
-    for e in entries {
-        let p = e.unwrap().path();
-        if let Some(name) = p.file_name().and_then(|s| s.to_str()) {
-            if name.ends_with(".json") {
-                json_count += 1;
-            }
-            if name.ends_with(".toml") {
-                toml_count += 1;
-            }
-            if name.ends_with(".srt") {
-                srt_count += 1;
-            }
-            if name.ends_with("_merged.json") {
-                merged_json = Some(p.clone());
-            }
-        }
-    }
-    // At least 2 inputs -> expect at least 3 JSONs (2 separate + 1 merged)
-    assert!(
-        json_count >= 3,
-        "expected at least 3 JSON files, found {}",
-        json_count
-    );
-    assert!(
-        toml_count >= 3,
-        "expected at least 3 TOML files, found {}",
-        toml_count
-    );
-    assert!(
-        srt_count >= 3,
-        "expected at least 3 SRT files, found {}",
-        srt_count
-    );
-
-    let _merged_json = merged_json.expect("missing merged JSON output ending with _merged.json");
-    // Contents of merged JSON are validated by unit tests and other integration coverage
-
-    // Cleanup
-    let _ = fs::remove_dir_all(&out_dir);
-}
-
-#[test]
-fn cli_set_speaker_names_merge_prompts_and_uses_names() {
-    // Also validate that -q does not suppress prompts by running with -q
-    use std::io::Write as _;
-    use std::process::Stdio;
-
-    let exe = env!("CARGO_BIN_EXE_polyscribe");
-
-    let input1 = manifest_path("input/1-s0wlz.json");
-    let input2 = manifest_path("input/2-vikingowl.json");
-
-    let mut child = Command::new(exe)
-        .arg(input1.as_os_str())
-        .arg(input2.as_os_str())
-        .arg("-m")
-        .arg("--set-speaker-names")
-        .arg("-q")
-        .stdin(Stdio::piped())
-        .stdout(Stdio::piped())
-        .spawn()
-        .expect("failed to spawn polyscribe");
-
-    {
-        let stdin = child.stdin.as_mut().expect("failed to open stdin");
-        // Provide two names for two files
-        writeln!(stdin, "Alpha").unwrap();
-        writeln!(stdin, "Beta").unwrap();
-    }
-
-    let output = child.wait_with_output().expect("failed to wait on child");
-    assert!(output.status.success(), "CLI did not exit successfully");
-
-    let stdout = String::from_utf8(output.stdout).expect("stdout not UTF-8");
-    let root: OutputRoot = serde_json::from_str(&stdout).unwrap();
-    let speakers: std::collections::HashSet<String> =
-        root.items.into_iter().map(|e| e.speaker).collect();
-    assert!(speakers.contains("Alpha"), "Alpha not found in speakers");
-    assert!(speakers.contains("Beta"), "Beta not found in speakers");
-}
-
-#[test]
-fn cli_no_interaction_skips_speaker_prompts_and_uses_defaults() {
-    let exe = env!("CARGO_BIN_EXE_polyscribe");
-
-    let input1 = manifest_path("input/1-s0wlz.json");
-    let input2 = manifest_path("input/2-vikingowl.json");
-
-    let output = Command::new(exe)
-        .arg(input1.as_os_str())
-        .arg(input2.as_os_str())
-        .arg("-m")
-        .arg("--set-speaker-names")
-        .arg("--no-interaction")
-        .output()
-        .expect("failed to spawn polyscribe");
-
-    assert!(output.status.success(), "CLI did not exit successfully");
-
-    let stdout = String::from_utf8(output.stdout).expect("stdout not UTF-8");
-    let root: OutputRoot = serde_json::from_str(&stdout).unwrap();
-    let speakers: std::collections::HashSet<String> =
-        root.items.into_iter().map(|e| e.speaker).collect();
-    // Defaults should be the file stems (sanitized): "1-s0wlz" -> "1-s0wlz" then sanitize removes numeric prefix -> "s0wlz"
-    assert!(speakers.contains("s0wlz"), "default s0wlz not used");
-    assert!(speakers.contains("vikingowl"), "default vikingowl not used");
-}
-
-// New verbosity behavior tests
-#[test]
-fn verbosity_quiet_suppresses_logs_but_keeps_stdout() {
-    let exe = env!("CARGO_BIN_EXE_polyscribe");
-    let input1 = manifest_path("input/1-s0wlz.json");
-    let input2 = manifest_path("input/2-vikingowl.json");
-
-    let output = Command::new(exe)
-        .arg("-q")
-        .arg("-v") // ensure -q overrides -v
-        .arg(input1.as_os_str())
-        .arg(input2.as_os_str())
-        .arg("-m")
-        .output()
-        .expect("failed to spawn polyscribe");
-
-    assert!(output.status.success());
-    let stdout = String::from_utf8(output.stdout).unwrap();
-    assert!(
-        stdout.contains("\"items\""),
-        "stdout JSON should be present in quiet mode"
-    );
-    let stderr = String::from_utf8(output.stderr).unwrap();
-    assert!(
-        stderr.trim().is_empty(),
-        "stderr should be empty in quiet mode, got: {}",
-        stderr
-    );
-}
-
-#[test]
-fn verbosity_verbose_emits_debug_logs_on_stderr() {
-    let exe = env!("CARGO_BIN_EXE_polyscribe");
-    let input1 = manifest_path("input/1-s0wlz.json");
-    let input2 = manifest_path("input/2-vikingowl.json");
-
-    let output = Command::new(exe)
-        .arg(input1.as_os_str())
-        .arg(input2.as_os_str())
-        .arg("-m")
-        .arg("-v")
-        .output()
-        .expect("failed to spawn polyscribe");
-
-    assert!(output.status.success());
-    let stdout = String::from_utf8(output.stdout).unwrap();
-    assert!(stdout.contains("\"items\""));
-    let stderr = String::from_utf8(output.stderr).unwrap();
-    assert!(
-        stderr.contains("Mode: merge"),
-        "stderr should contain debug log with -v"
-    );
-}
-
-#[test]
-fn verbosity_flag_position_is_global() {
-    let exe = env!("CARGO_BIN_EXE_polyscribe");
-    let input1 = manifest_path("input/1-s0wlz.json");
-    let input2 = manifest_path("input/2-vikingowl.json");
-
-    // -v before args
-    let out1 = Command::new(exe)
-        .arg("-v")
-        .arg(input1.as_os_str())
-        .arg(input2.as_os_str())
-        .arg("-m")
-        .output()
-        .expect("failed to spawn polyscribe");
-
-    // -v after sub-flags
-    let out2 = Command::new(exe)
-        .arg(input1.as_os_str())
-        .arg(input2.as_os_str())
-        .arg("-m")
-        .arg("-v")
-        .output()
-        .expect("failed to spawn polyscribe");
-
-    let s1 = String::from_utf8(out1.stderr).unwrap();
-    let s2 = String::from_utf8(out2.stderr).unwrap();
-    assert!(s1.contains("Mode: merge"));
-    assert!(s2.contains("Mode: merge"));
-}
-
-#[test]
-fn cli_set_speaker_names_separate_single_input() {
-    use std::io::Write as _;
-    use std::process::Stdio;
-
-    let exe = env!("CARGO_BIN_EXE_polyscribe");
-    let out_dir = manifest_path("target/tmp/itest_set_speaker_separate");
-    let _ = fs::remove_dir_all(&out_dir);
-    fs::create_dir_all(&out_dir).unwrap();
-
-    let input1 = manifest_path("input/3-schmendrizzle.json");
-
-    let mut child = Command::new(exe)
-        .arg(input1.as_os_str())
-        .arg("--set-speaker-names")
-        .arg("-o")
-        .arg(out_dir.as_os_str())
-        .stdin(Stdio::piped())
-        .stdout(Stdio::null())
-        .stderr(Stdio::null())
-        .spawn()
-        .expect("failed to spawn polyscribe");
-
-    {
-        let stdin = child.stdin.as_mut().expect("failed to open stdin");
-        writeln!(stdin, "ChosenOne").unwrap();
-    }
-
-    let status = child.wait().expect("failed to wait on child");
-    assert!(status.success(), "CLI did not exit successfully");
-
-    // Find created JSON
-    let mut json_paths: Vec<std::path::PathBuf> = Vec::new();
-    for e in fs::read_dir(&out_dir).unwrap() {
-        let p = e.unwrap().path();
-        if let Some(name) = p.file_name().and_then(|s| s.to_str()) {
-            if name.ends_with(".json") {
-                json_paths.push(p.clone());
-            }
-        }
-    }
-    assert!(!json_paths.is_empty(), "no JSON outputs created");
-    let mut buf = String::new();
-    std::fs::File::open(&json_paths[0])
-        .unwrap()
-        .read_to_string(&mut buf)
-        .unwrap();
-    let root: OutputRoot = serde_json::from_str(&buf).unwrap();
-    assert!(root.items.iter().all(|e| e.speaker == "ChosenOne"));
-
-    let _ = fs::remove_dir_all(&out_dir);
-}
--- a/tests/smoke.rs
+++ b/tests/smoke.rs
@@ -0,0 +1,6 @@
+// Rust
+#[test]
+fn smoke_compiles_and_runs() {
+    // This test ensures the test harness works without exercising the CLI.
+    assert!(true);
+}
Author	SHA1	Message	Date
vikingowl	5ec297397e	[refactor] rename and simplify `ProgressManager` to `FileProgress`, enhance caching logic, update Hugging Face API integration, and clean up unused comments Some checks failed CI / build (push) Has been cancelled Details	2025-08-15 11:24:50 +02:00
vikingowl	cbf48a0452	docs: align CLI docs to models subcommands; host: scan XDG plugin dir; ci: add GitHub Actions; chore: add CHANGELOG	2025-08-14 11:16:50 +02:00
vikingowl	0a249f2197	[refactor] improve code readability, streamline initialization, update error handling, and format multi-line statements for consistency	2025-08-14 11:06:37 +02:00
vikingowl	0573369b81	[refactor] propagate `no-progress` and `no-interaction` flags, enhance prompt handling, and update progress bar logic with `cliclack`	2025-08-14 10:34:52 +02:00
vikingowl	9841550dcc	[refactor] replace `indicatif` with `cliclack` for progress and logging, updating affected modules and dependencies	2025-08-14 03:31:00 +02:00
vikingowl	53119cd0ab	[refactor] enhance model management with metadata enrichment, new API integration, and manifest resolution	2025-08-13 22:44:51 +02:00
vikingowl	144b01d591	[refactor] update `Cargo.lock` with new dependency additions and version bumps	2025-08-13 14:45:43 +02:00
vikingowl	ffd451b404	[refactor] remove unused test suites, examples, CI docs, and PR description file	2025-08-13 14:26:18 +02:00
vikingowl	5c64677e79	[refactor] streamline crate structure, update dependencies, and integrate CLI functionalities	2025-08-13 14:05:13 +02:00
vikingowl	128db0f733	[refactor] remove backend and library modules, consolidating features into main crate	2025-08-13 13:35:53 +02:00
vikingowl	06fd3efd1f	Merge remote-tracking branch 'origin/main' into dev	2025-08-13 11:48:37 +02:00
vikingowl	3344a3b18c	[feat] implement backend abstraction, dynamic backend selection, and GPU feature integration	2025-08-13 11:36:09 +02:00
vikingowl	5ace0a0d7e	[refactor] improve variable naming and simplify logic across multiple functions and structs	2025-08-13 10:34:56 +02:00
vikingowl	ed3af9210f	[refactor] clean up argument definitions, remove unused GPU options, and reduce duplicate logic	2025-08-12 13:53:24 +02:00
vikingowl	79397a3b9c	[refactor] simplify backend initialization and transcription logic using macro and trait improvements	2025-08-12 12:05:32 +02:00
vikingowl	9fd44a2e37	[feat] add progress management and centralized TTY-aware UI helpers with cliclack and indicatif	2025-08-12 12:01:47 +02:00
vikingowl	a987a3fcfb	[feat] improve non-interactive model selection and enhance multi-stage TTY-based selection	2025-08-12 11:02:49 +02:00
vikingowl	f41f1a4117	[feat] enable parallel model downloads with bounded concurrency and TTY-aware progress bars	2025-08-12 10:16:21 +02:00
vikingowl	75cfb6f160	[feat] add input validation, enhanced error messages, and new integration tests	2025-08-12 09:49:11 +02:00
vikingowl	8ebdf876ed	[feat] replace custom model selection with cliclack-based multiselect for improved TTY interaction	2025-08-12 09:20:33 +02:00
vikingowl	eb1bf9e02d	[feat] integrate progress manager into speaker name prompts for better coordination	2025-08-12 09:04:45 +02:00
vikingowl	9b4bd545dd	[feat] add `--no-progress` CLI option to disable progress bars and spinners	2025-08-12 08:28:48 +02:00
vikingowl	041e504cb2	[feat] add TTY-aware progress management with `indicatif` and file-specific progress bars	2025-08-12 08:11:28 +02:00
vikingowl	2cc5e49131	[feat] integrate cliclack for TTY-aware UI, add summaries and intro/outro helpers	2025-08-12 07:30:54 +02:00
vikingowl	4916aa6224	[refactor] centralize speaker name resolution to improve readability and reduce redundancy	2025-08-12 06:23:22 +02:00