Clarify public profile and source docs

engine.go

@@ -85,6 +85,10 @@ func WithLLMClient(client LLMClient) Option {
 	})
 }
 
+// WithPromptFS loads prompt definitions from fsys under root.
+//
+// The source uses the same strict prompt YAML rules as configured prompt
+// directories, and prompt content_file paths resolve within this source.
 func WithPromptFS(fsys fs.FS, root string) Option {
 	return optionFunc(func(options *engineOptions) error {
 		if fsys == nil {
@@ -99,6 +103,9 @@ func WithPromptFS(fsys fs.FS, root string) Option {
 	})
 }
 
+// WithPromptFile loads prompt definitions from the single prompt file at path.
+//
+// Relative prompt content_file paths resolve from the file's directory.
 func WithPromptFile(path string) Option {
 	return optionFunc(func(options *engineOptions) error {
 		fsys, root, err := fileSource(path)
@@ -111,6 +118,10 @@ func WithPromptFile(path string) Option {
 	})
 }
 
+// WithProfileFS loads execution profiles from fsys under root.
+//
+// Profiles from this source overlay built-in profiles. Profile YAML must use
+// api_key_env for environment-based credentials; raw API keys are rejected.
 func WithProfileFS(fsys fs.FS, root string) Option {
 	return optionFunc(func(options *engineOptions) error {
 		if fsys == nil {
@@ -125,6 +136,10 @@ func WithProfileFS(fsys fs.FS, root string) Option {
 	})
 }
 
+// WithProfileFile loads execution profiles from the single profile file at path.
+//
+// The profile overlays built-in profiles. Profile YAML must use api_key_env for
+// environment-based credentials; raw API keys are rejected.
 func WithProfileFile(path string) Option {
 	return optionFunc(func(options *engineOptions) error {
 		fsys, root, err := fileSource(path)
@@ -151,6 +166,10 @@ func WithProfiles(profiles ...Profile) Option {
 	})
 }
 
+// WithSchemaFS loads JSON Schema documents from fsys under root.
+//
+// Prompt schema_path values resolve within this source when schema validation
+// or structured output is requested.
 func WithSchemaFS(fsys fs.FS, root string) Option {
 	return optionFunc(func(options *engineOptions) error {
 		if fsys == nil {
@@ -165,6 +184,9 @@ func WithSchemaFS(fsys fs.FS, root string) Option {
 	})
 }
 
+// WithSchemaFile loads JSON Schema documents from the single schema file at path.
+//
+// Prompt schema_path values refer to the file's base name.
 func WithSchemaFile(path string) Option {
 	return optionFunc(func(options *engineOptions) error {
 		fsys, root, err := fileSource(path)

profiles.go

@@ -10,8 +10,12 @@ import (
 	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
 )
 
-// OpenAICompatibleProfile returns an in-memory profile for an OpenAI-compatible
-// chat-completions endpoint.
+// OpenAICompatibleProfile returns an ordinary in-memory Profile for an
+// OpenAI-compatible chat-completions endpoint.
+//
+// It does not register global state, maintain a model catalog, or resolve
+// credentials. If APIKeyRequired is true, callers satisfy it with
+// RunRequest.APIKey. Raw API keys do not belong in profiles.
 func OpenAICompatibleProfile(cfg OpenAICompatibleProfileConfig) Profile {
 	return Profile{
 		ID:              cfg.ID,

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