feat: Add test fixtures and enhance test suite for subtitle processing

- Added `already_clean.srt` fixture to test idempotency of the clean operation.
- Introduced `cue_settings.vtt` fixture to validate conversion from VTT with cue settings to SRT.
- Created `large.srt` fixture for testing chunking functionality with large subtitle files.
- Added `latin1.srt` fixture to test handling of Latin-1 encoded subtitles.
- Enhanced `run_tests.sh` to include new tests for:
  - Checking the output of the `check` command.
  - Config set/get functionality.
  - Idempotent clean operation on already clean files.
  - Conversion of VTT with cue settings to SRT.
  - Fixing Latin-1 encoded files to UTF-8.
  - Chunking functionality for large and small subtitle files.
  - Validation of SRT files for correct formatting.
  - Auto-detection of source language in translation.
  - Quiet and verbose flag functionality in commands.

Author: maxgfr

.github/workflows/ci.yml

@@ -55,4 +55,4 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Run shellcheck
-        run: shellcheck -x -S warning subtool.sh || true
+        run: shellcheck -x -S warning subtool.sh

CLAUDE.md

@@ -0,0 +1,63 @@
+# subtool - All-in-one Subtitle CLI
+
+## Project Overview
+Single bash script (`subtool.sh`, ~2100 lines) for subtitle management: download, translate, convert, sync, clean, merge, fix, extract, embed.
+
+## Architecture
+- **One file**: `subtool.sh` — everything is in this script
+- **Config**: `~/.config/subtool/config` (API keys, defaults)
+- **Cache**: `~/.cache/subtool/` (temp files, chunks)
+- **Tests**: `tests/run_tests.sh` + `tests/fixtures/`
+
+## Key Subsystems
+
+### Subtitle Sources (search + download)
+- **OpenSubtitles** API v1 (`/subtitles`, `/features`, `/download`) — requires `OPENSUBTITLES_API_KEY`
+- **Podnapisi** — scrapes podnapisi.net
+- **SubDL** — uses subdl.com API — requires `SUBDL_API_KEY`
+
+Search flow: `search_all_sources()` → iterates `SOURCES` (comma-separated) → calls `search_<source>()` for each.
+OpenSubtitles search resolves title to IMDB ID via `/features` endpoint first, then searches by `imdb_id`.
+
+### AI Translation Providers
+- `claude-code` (default) — calls `claude -p` CLI, no API key needed
+- `zai-codeplan` — Z.ai Coding Plan API
+- `openai`, `claude`, `mistral`, `gemini` — standard chat APIs
+
+Translation uses chunking for large files (`chunk_srt()`, 250 lines per chunk).
+
+### Smart Query Parsing
+`parse_smart_query()` extracts title, season, episode, range, year, IMDB ID from free-text input like "Die Discounter S01E03-E08".
+
+## Commands
+`get`, `search`, `batch`, `translate`, `info`, `clean`, `sync`, `autosync`, `convert`, `merge`, `fix`, `extract`, `embed`, `config`, `check`, `providers`, `sources`
+
+## CLI Flags
+- `--auto` — auto-select first result (skip interactive prompt)
+- `--dry-run` — show results without downloading
+- `--json` — JSON output (implies `--quiet`)
+- `--verbose` — debug output via `debug()` to stderr
+- `--quiet` — suppress informational messages
+
+## Utility Functions
+- `api_retry()` — retry with backoff for 429/rate-limit responses
+- `detect_lang()` — auto-detect language from subtitle text sample
+- `validate_srt()` — check SRT format validity (indices, timestamps, text)
+- `_translate_prompt()` / `_translate_dispatch()` — shared translation logic (deduplicated)
+
+## CI/CD
+- `.github/workflows/release.yml` — semantic-release (bumps VERSION in subtool.sh)
+- `.github/workflows/ci.yml` — tests
+- `.releaserc` + `.version-hook.sh` — version management
+- Homebrew tap at `~/Downloads/homebrew-tap/Formula/subtool.rb`
+
+## Conventions
+- All output/logs via stderr (`>&2`), only data on stdout
+- Colors: RED/GREEN/YELLOW/BLUE/CYAN/BOLD/NC
+- Helper functions: `log()`, `warn()`, `err()`, `info()`, `debug()`, `header()`, `die()`
+- URL encoding: `urlencode()` via jq
+- Dependencies: `jq` (required), `ffmpeg`/`ffprobe`/`ffsubsync` (optional)
+
+## GitHub
+- Repo: `maxgfr/subtool`
+- Homebrew: `maxgfr/tap/subtool`

README.md

@@ -115,23 +115,52 @@ subtool convert -f subs.ass --to srt
 # Merge bilingual subtitles
 subtool merge -f primary.srt --merge-with secondary.srt
 
-# Fix broken subtitles (renumber, fix overlaps, UTF-8)
+# Fix broken subtitles (renumber, fix overlaps, sort by timestamp, UTF-8)
 subtool fix -f broken.srt
 
 # Extract subtitles from video
 subtool extract -f video.mkv --track 0
 
 # Embed subtitles into video
 subtool embed -f video.mkv --sub subs.srt -l fr
+
+# Check environment (deps, API keys, config)
+subtool check
+```
+
+## Flags
+
+| Flag | Description |
+|---|---|
+| `--auto` | Auto-select first result (no interactive prompt) |
+| `--dry-run` | Show results without downloading |
+| `--json` | Output results as JSON (implies `--quiet`) |
+| `--verbose` | Show debug output |
+| `--quiet` | Suppress informational messages |
+
+```bash
+# Auto-select first subtitle match
+subtool get -q "Inception" -l fr --auto
+
+# Dry-run: see what would be downloaded
+subtool get -q "Inception" -l fr --dry-run
+
+# JSON output for scripting
+subtool search -q "Inception" -l fr --json
+
+# Verbose debug output
+subtool get -q "Inception" -l fr --verbose
 ```
 
 ## Configuration
 
 ```bash
 subtool config                    # Show current config
 subtool config set key value      # Set a config value
+subtool config get key            # Get a config value
 subtool providers                 # List AI providers and models
 subtool sources                   # List subtitle sources
+subtool check                     # Diagnostic: deps, API keys, paths
 ```
 
 API keys are stored in `~/.config/subtool/config`: