Clarify public profile and source docs

types.go

@@ -155,6 +155,11 @@ type ExecutionTargetOverride struct {
 }
 
 // Profile is an in-memory execution profile for library consumers.
+//
+// It is equivalent to a loaded profile file after validation. Raw API keys do
+// not belong in profiles; use APIKeyRequired to require callers to provide
+// RunRequest.APIKey for each request, or use profile YAML api_key_env with file
+// and FS profile sources.
 type Profile struct {
 	ID              string
 	Endpoint        string
@@ -169,7 +174,12 @@ type Profile struct {
 	ExtraParams     map[string]any
 }
 
-// OpenAICompatibleProfileConfig configures an OpenAI-compatible in-memory profile.
+// OpenAICompatibleProfileConfig configures an OpenAI-compatible in-memory
+// profile.
+//
+// It contains ordinary profile fields for OpenAI-compatible chat-completions
+// endpoints. APIKeyRequired is satisfied by RunRequest.APIKey. Raw API keys do
+// not belong in this config.
 type OpenAICompatibleProfileConfig struct {
 	ID              string
 	Endpoint        string