config: use ParseError.ErrorWithUsage() for richer TOML startup diagnostics

internal/cmd/root.go

@@ -215,7 +215,7 @@ func run(cmd *cobra.Command, args []string) error {
 
 	if err != nil {
 		// Log configuration validation errors to markdown logger
-		logger.LogErrorToMarkdown("startup", "Configuration validation failed:\n%s", err.Error())
+		logger.LogErrorToMarkdown("startup", "Configuration validation failed:\n%s", config.FormatConfigError(err))
 		return fmt.Errorf("failed to load config: %w", err)
 	}
 

internal/config/config_core.go

@@ -547,6 +547,29 @@ func LoadFromFile(path string) (*Config, error) {
 	return &cfg, nil
 }
 
+// FormatConfigError returns a rich diagnostic message for TOML parse errors.
+// When err wraps a toml.ParseError, it returns ParseError.ErrorWithUsage() which
+// includes a source-code snippet and column pointer, e.g.:
+//
+//	toml: line 5 (field command): expected "=", got "[" instead
+//
+//	  3 | [servers.github]
+//	  4 | command = "docker"
+//	  5 | [servers.github
+//	      | ^
+//
+// For all other error types, it falls back to err.Error().
+func FormatConfigError(err error) string {
+	if err == nil {
+		return ""
+	}
+	var perr toml.ParseError
+	if errors.As(err, &perr) {
+		return perr.ErrorWithUsage()
+	}
+	return err.Error()
+}
+
 // logConfig is the debug logger for the config package.
 // Enable with DEBUG=config:* or DEBUG=*.
 var logConfig = logger.New("config:config")

internal/config/config_core_test.go

@@ -62,6 +62,35 @@ command = "docker"
 	assert.Greater(t, perr.Position.Col, 0, "parse error should include column number")
 }
 
+// TestFormatConfigError verifies that FormatConfigError returns source-context-rich
+// output for toml.ParseError and falls back to err.Error() for other errors.
+func TestFormatConfigError(t *testing.T) {
+	t.Run("wraps toml.ParseError with ErrorWithUsage", func(t *testing.T) {
+		// Write invalid TOML to trigger a ParseError
+		path := writeTempTOML(t, "[gateway]\nport 3000\n")
+		_, err := LoadFromFile(path)
+		require.Error(t, err, "expected error from invalid TOML")
+
+		msg := FormatConfigError(err)
+
+		// ErrorWithUsage output contains the file source snippet (|) and a
+		// column pointer (^), which Error() alone does not include.
+		assert.Contains(t, msg, "|", "ErrorWithUsage should include source-snippet lines")
+		assert.Contains(t, msg, "^", "ErrorWithUsage should include column pointer")
+	})
+
+	t.Run("falls back to err.Error() for non-TOML errors", func(t *testing.T) {
+		err := fmt.Errorf("some other error")
+		assert.Equal(t, "some other error", FormatConfigError(err))
+	})
+
+	t.Run("falls back to err.Error() for wrapped non-TOML errors", func(t *testing.T) {
+		inner := fmt.Errorf("inner error")
+		err := fmt.Errorf("config error: %w", inner)
+		assert.Equal(t, "config error: inner error", FormatConfigError(err))
+	})
+}
+
 func TestLoadFromFile_BothTracingAndOpenTelemetry_OpenTelemetryTakesPrecedence(t *testing.T) {
 	path := writeTempTOML(t, `
 [gateway.tracing]