improve language-model compatibility error messages with docs URL

internal/config/config_test.go

@@ -707,7 +707,7 @@ func TestValidateModelLanguageCompatibility(t *testing.T) {
 			model:       "distil-whisper-large-v3-en",
 			langCode:    "es",
 			wantErr:     true,
-			errContains: "does not support language 'es'",
+			errContains: "does not support Spanish (es)",
 		},
 		{
 			name:     "multilingual model supports spanish",
@@ -722,7 +722,7 @@ func TestValidateModelLanguageCompatibility(t *testing.T) {
 			model:       "base.en",
 			langCode:    "fr",
 			wantErr:     true,
-			errContains: "does not support language 'fr'",
+			errContains: "does not support French (fr)",
 		},
 		{
 			name:     "whisper-cpp multilingual supports french",

internal/config/validate.go

@@ -212,16 +212,23 @@ func ValidateModelLanguageCompatibility(registryProvider, modelID, langCode stri
 	// truncate supported languages for error message
 	supported := model.SupportedLanguages
 	suffix := ""
-	if len(supported) > 10 {
-		supported = supported[:10]
+	if len(supported) > 5 {
+		supported = supported[:5]
 		suffix = "..."
 	}
 
+	// build error with docs URL if available
+	docsHint := ""
+	if model.DocsURL != "" {
+		docsHint = fmt.Sprintf(" See %s for full list.", model.DocsURL)
+	}
+
 	return fmt.Errorf(
-		"model %s does not support language '%s' (%s). Either change model, select auto-detect, or choose a supported language: %s%s",
-		modelID,
-		langCode,
+		"model %s does not support %s (%s).%s Supported: %s%s",
+		model.Name,
 		langName,
+		langCode,
+		docsHint,
 		strings.Join(supported, ", "),
 		suffix,
 	)

internal/provider/provider.go

@@ -151,15 +151,25 @@ func ValidateModelLanguage(providerName, modelID, langCode string) error {
 
 	// truncate supported languages list for error message
 	supported := model.SupportedLanguages
-	if len(supported) > 10 {
-		supported = append(supported[:10], "...")
+	suffix := ""
+	if len(supported) > 5 {
+		supported = supported[:5]
+		suffix = "..."
+	}
+
+	// build error with docs URL if available
+	docsHint := ""
+	if model.DocsURL != "" {
+		docsHint = fmt.Sprintf(" See %s for full list.", model.DocsURL)
 	}
 
 	return fmt.Errorf(
-		"model %s does not support language '%s'. Supported: %s",
-		modelID,
+		"model %s does not support language '%s'.%s Supported: %s%s",
+		model.Name,
 		langCode,
+		docsHint,
 		strings.Join(supported, ", "),
+		suffix,
 	)
 }
 

internal/provider/provider_test.go

@@ -2,6 +2,7 @@ package provider
 
 import (
 	"slices"
+	"strings"
 	"testing"
 )
 
@@ -263,6 +264,35 @@ func TestValidateModelLanguage(t *testing.T) {
 	}
 }
 
+func TestValidateModelLanguage_ErrorFormat(t *testing.T) {
+	// verify error includes model name, not ID
+	err := ValidateModelLanguage("groq", "distil-whisper-large-v3-en", "es")
+	if err == nil {
+		t.Fatal("expected error for unsupported language")
+	}
+	errMsg := err.Error()
+
+	// should contain model name (from Model.Name)
+	if !strings.Contains(errMsg, "Distil Whisper Large v3 EN") {
+		t.Errorf("error should contain model name, got: %s", errMsg)
+	}
+
+	// should contain docs URL
+	if !strings.Contains(errMsg, "https://console.groq.com/docs/speech-to-text#supported-languages") {
+		t.Errorf("error should contain docs URL, got: %s", errMsg)
+	}
+
+	// should contain language code
+	if !strings.Contains(errMsg, "'es'") {
+		t.Errorf("error should contain language code, got: %s", errMsg)
+	}
+
+	// should have truncated language list (only 5 supported langs, English-only has 1)
+	if !strings.Contains(errMsg, "en") {
+		t.Errorf("error should contain supported languages, got: %s", errMsg)
+	}
+}
+
 func TestOpenAIRealtimeModel(t *testing.T) {
 	m, err := GetModel("openai", "gpt-4o-realtime-preview")
 	if err != nil {