docs: update readme and config docs for general language setting

README.md

@@ -238,6 +238,7 @@ hyprvoice configure
 The wizard guides you through all settings with a user-friendly interface:
 
 - **Providers** - API keys for OpenAI, Groq, Mistral, ElevenLabs, Deepgram
+- **Language** - Global language setting for all transcription (57 languages + auto-detect)
 - **Transcription** - Speech-to-text provider and model selection (cloud or local)
 - **LLM** - Post-processing to clean up transcriptions (enabled by default)
 - **Keywords** - Domain-specific terms for better accuracy
@@ -299,10 +300,12 @@ For complete offline privacy, use whisper.cpp for local transcription - no API k
 ### Configuration
 
 ```toml
+[general]
+language = ""              # empty for auto-detect, or "en", "es", etc.
+
 [transcription]
 provider = "whisper-cpp"
 model = "base.en"          # or "base" for multilingual
-language = ""              # empty for auto-detect
 threads = 0                # 0 = auto (NumCPU - 1)
 ```
 
@@ -321,6 +324,9 @@ For real-time transcription results as you speak, use streaming providers. Text
 ### Configuration
 
 ```toml
+[general]
+language = ""              # empty for auto-detect
+
 # ElevenLabs streaming
 [providers.elevenlabs]
 api_key = "..."

docs/config.md

@@ -10,6 +10,7 @@ Configuration is stored in `~/.config/hyprvoice/config.toml` and changes are app
 
 ## Table of Contents
 
+- [General Settings](#general-settings)
 - [Unified Provider System](#unified-provider-system)
 - [Transcription Providers](#transcription-providers)
   - [Cloud Providers](#cloud-providers)
@@ -25,6 +26,41 @@ Configuration is stored in `~/.config/hyprvoice/config.toml` and changes are app
 - [Example Configurations](#example-configurations)
 - [Migration from Old Config Format](#migration-from-old-config-format)
 
+## General Settings
+
+The `[general]` section contains application-wide settings:
+
+```toml
+[general]
+language = ""              # ISO 639-1 code (e.g., "en", "es", "de"). Empty for auto-detect.
+```
+
+### Language
+
+The global language setting applies to all transcription providers:
+
+```toml
+[general]
+language = ""              # Auto-detect (recommended)
+# language = "en"          # English
+# language = "es"          # Spanish
+# language = "de"          # German
+```
+
+**Override behavior:** You can override the global language for a specific transcription provider:
+
+```toml
+[general]
+language = "en"            # Default to English
+
+[transcription]
+# language = "es"          # Uncomment to override for this provider only
+```
+
+When `transcription.language` is set, it takes precedence over `general.language`. This allows you to set a default language but override it for specific use cases.
+
+See [Language Configuration](#language-configuration) for the full list of supported languages and model compatibility.
+
 ## Unified Provider System
 
 Hyprvoice uses a unified provider system where API keys are configured once and shared between transcription and LLM features:
@@ -63,9 +99,11 @@ Hyprvoice supports multiple transcription backends. See [docs/providers.md](./pr
 Cloud-based transcription using OpenAI's Whisper API:
 
 ```toml
+[general]
+language = ""                   # Empty for auto-detect, or "en", "es", "fr", etc.
+
 [transcription]
 provider = "openai"
-language = ""                   # Empty for auto-detect, or "en", "es", "fr", etc.
 model = "whisper-1"
 ```
 
@@ -80,9 +118,11 @@ model = "whisper-1"
 Fast cloud-based transcription using Groq's Whisper API:
 
 ```toml
+[general]
+language = ""                   # Empty for auto-detect, or "en", "es", "fr", etc.
+
 [transcription]
 provider = "groq-transcription"
-language = ""                   # Empty for auto-detect, or "en", "es", "fr", etc.
 model = "whisper-large-v3"      # Or "whisper-large-v3-turbo" for faster processing
 ```
 
@@ -116,9 +156,11 @@ model = "whisper-large-v3"
 Transcription using Mistral's Voxtral API, excellent for European languages:
 
 ```toml
+[general]
+language = ""                   # Empty for auto-detect
+
 [transcription]
 provider = "mistral-transcription"
-language = ""
 model = "voxtral-mini-latest"   # Or "voxtral-mini-2507"
 ```
 
@@ -127,9 +169,11 @@ model = "voxtral-mini-latest"   # Or "voxtral-mini-2507"
 Transcription using ElevenLabs' Scribe API with 57+ language support:
 
 ```toml
+[general]
+language = ""                   # Empty for auto-detect
+
 [transcription]
 provider = "elevenlabs"
-language = ""
 model = "scribe_v1"             # Or "scribe_v2" for lower latency
 ```
 
@@ -144,12 +188,14 @@ model = "scribe_v1"             # Or "scribe_v2" for lower latency
 Fast streaming transcription using Deepgram's Nova models:
 
 ```toml
+[general]
+language = ""                   # Empty for auto-detect
+
 [providers.deepgram]
   api_key = "..."               # Or set DEEPGRAM_API_KEY env var
 
 [transcription]
 provider = "deepgram"
-language = ""
 model = "nova-3"                # Or "nova-2" for different language support
 ```
 
@@ -170,9 +216,11 @@ Run Whisper models locally on your machine. No API keys, no network latency, com
 2. Download a model: `hyprvoice model download base.en`
 
 ```toml
+[general]
+language = ""                   # Empty for auto-detect
+
 [transcription]
 provider = "whisper-cpp"
-language = ""                   # Empty for auto-detect
 model = "base.en"               # English-only model (fastest)
 threads = 0                     # 0 = auto (uses NumCPU - 1)
 ```
@@ -230,10 +278,10 @@ model = "gpt-4o-realtime-preview"
 
 ## Language Configuration
 
-Configure the expected spoken language for better accuracy:
+Configure the expected spoken language for better accuracy. Language is set globally in `[general]`:
 
 ```toml
-[transcription]
+[general]
 language = ""                   # Empty for auto-detect (recommended)
 # Or specify a language code:
 # language = "en"               # English
@@ -243,6 +291,16 @@ language = ""                   # Empty for auto-detect (recommended)
 # language = "ja"               # Japanese
 ```
 
+**Override per-provider:** If you need different languages for different setups:
+
+```toml
+[general]
+language = "en"                 # Global default
+
+[transcription]
+# language = "es"               # Uncomment to override for transcription only
+```
+
 **Recommendations:**
 
 - Use auto-detect (`language = ""`) for most cases - it works well
@@ -273,12 +331,14 @@ Some models only support English. Hyprvoice validates compatibility:
 1. **At config time (TUI/validation):** Selecting an English-only model with a non-English language shows an error and prevents saving
 2. **At runtime (safety net):** If config was manually edited to an invalid combination, hyprvoice logs a warning, sends a desktop notification, and falls back to auto-detect
 
-```
+```toml
 # This combination will be rejected:
+[general]
+language = "es"                         # Error: model does not support Spanish
+
 [transcription]
 provider = "groq-transcription"
 model = "distil-whisper-large-v3-en"   # English only!
-language = "es"                         # Error: model does not support Spanish
 ```
 
 ## Model Management
@@ -525,6 +585,9 @@ You can customize notification text via the `[notifications.messages]` section:
 ### Fast Transcription Only (No LLM)
 
 ```toml
+[general]
+language = ""                   # Auto-detect
+
 [providers.groq]
   api_key = "gsk_..."
 
@@ -539,6 +602,9 @@ You can customize notification text via the `[notifications.messages]` section:
 ### High Quality with OpenAI (Default)
 
 ```toml
+[general]
+language = ""                   # Auto-detect
+
 [providers.openai]
   api_key = "sk-..."
 
@@ -555,6 +621,9 @@ You can customize notification text via the `[notifications.messages]` section:
 ### Budget-Friendly with Groq
 
 ```toml
+[general]
+language = ""                   # Auto-detect
+
 [providers.groq]
   api_key = "gsk_..."
 
@@ -571,6 +640,9 @@ You can customize notification text via the `[notifications.messages]` section:
 ### Mixed Providers (Groq Transcription + OpenAI LLM)
 
 ```toml
+[general]
+language = ""                   # Auto-detect
+
 [providers.openai]
   api_key = "sk-..."
 
@@ -592,6 +664,9 @@ You can customize notification text via the `[notifications.messages]` section:
 ```toml
 # No API keys needed!
 
+[general]
+language = ""                   # Auto-detect
+
 [transcription]
   provider = "whisper-cpp"
   model = "base.en"
@@ -604,6 +679,9 @@ You can customize notification text via the `[notifications.messages]` section:
 ### Real-Time Streaming with Deepgram
 
 ```toml
+[general]
+language = ""                   # Auto-detect
+
 [providers.deepgram]
   api_key = "..."
 
@@ -618,6 +696,9 @@ You can customize notification text via the `[notifications.messages]` section:
 ### Ultra-Low Latency Streaming
 
 ```toml
+[general]
+language = ""                   # Auto-detect
+
 [providers.elevenlabs]
   api_key = "..."
 
@@ -629,8 +710,56 @@ You can customize notification text via the `[notifications.messages]` section:
   enabled = false
 ```
 
+### Multilingual Setup with Specific Language
+
+```toml
+[general]
+language = "es"                 # Always transcribe as Spanish
+
+[providers.openai]
+  api_key = "sk-..."
+
+[transcription]
+  provider = "openai"
+  model = "whisper-1"
+
+[llm]
+  enabled = true
+  provider = "openai"
+  model = "gpt-4o-mini"
+```
+
 ## Migration from Old Config Format
 
+### Language Migration
+
+If you have `transcription.language` set in your config, it will continue to work but is now an override. The recommended approach is to move it to `[general]`:
+
+**Old format (still works as override):**
+
+```toml
+[transcription]
+  provider = "openai"
+  language = "en"     # Works but is now an override
+  model = "whisper-1"
+```
+
+**New format (recommended):**
+
+```toml
+[general]
+  language = "en"     # Global setting
+
+[transcription]
+  provider = "openai"
+  model = "whisper-1"
+  # language = "es"   # Only set here to override [general]
+```
+
+When loading, if `transcription.language` is set but `general.language` is not, the language is automatically migrated to the general section. Run `hyprvoice configure` and save to persist this change.
+
+### API Key Migration
+
 If you're upgrading from an older version with `transcription.api_key`:
 
 **Old format (still works):**

progress.txt

@@ -609,3 +609,19 @@ Started: Sun Feb  1 12:22:47 AM CET 2026
   - `TestConfig_Validate_GeneralLanguage/valid_override_with_compatible_language`
   - `TestConfig_Validate_GeneralLanguage/auto_language_always_passes`
 - All tests passing, typecheck passes
+
+### Task 12: Update README and docs for general language setting
+- Updated README.md:
+  - Local Transcription config example: language moved to `[general]` section
+  - Streaming Transcription config example: added `[general]` section with language
+  - Configuration wizard list: added Language menu item
+- Updated docs/config.md:
+  - Added General Settings section at top with language field documentation
+  - Added override behavior explanation (transcription.language overrides general.language)
+  - Updated all provider examples to show language in `[general]` section
+  - Updated Language Configuration section to show `[general]` format
+  - Updated Language-Model Compatibility example to use `[general]` format
+  - Updated all Example Configurations with `[general]` section
+  - Added "Multilingual Setup with Specific Language" example
+  - Added Language Migration section explaining the change from transcription.language
+- Typecheck passes

tasks/prd.jsonc

@@ -200,7 +200,7 @@
 				"Override behavior documented",
 				"Typecheck passes"
 			],
-			"passes": false
+			"passes": true
 		},
 		{
 			"title": "Add migration for existing configs",