Implement a library profile API and built-in profile docs

internal/usecase/runner.go

@@ -27,6 +27,7 @@ var (
 	ErrInvalidRequest   = errors.New("invalid run request")
 	ErrProfileRequired  = errors.New("profile selection is required")
 	ErrAPIKeyEnvMissing = errors.New("api_key_env points to an unset environment variable")
+	ErrAPIKeyRequired   = errors.New("api key is required")
 	ErrProfileLoad      = errors.New("failed to load prompt definition")
 	ErrArtifactLoad     = errors.New("failed to load artifact")
 	ErrPromptRender     = errors.New("failed to render prompt")
@@ -202,7 +203,7 @@ func (r *Runner) Prepare(ctx context.Context, req domain.RunRequest) (*domain.Pr
 	if strings.TrimSpace(effectiveModel.Model) == "" {
 		return nil, fmt.Errorf("%w: execution model is required", ErrInvalidRequest)
 	}
-	if err := validateAPIKey(effectiveModel.APIKeyEnv, effectiveModel.APIKey); err != nil {
+	if err := validateAPIKey(effectiveModel.APIKeyEnv, effectiveModel.APIKey, effectiveModel.APIKeyRequired); err != nil {
 		return nil, fmt.Errorf("%w: %w", ErrInvalidRequest, err)
 	}
 
@@ -363,6 +364,9 @@ func mergeExecutionTarget(base domain.ExecutionTarget, override domain.Execution
 	if strings.TrimSpace(override.APIKeyEnv) != "" {
 		out.APIKeyEnv = override.APIKeyEnv
 	}
+	if override.APIKeyRequired {
+		out.APIKeyRequired = true
+	}
 	if len(override.ExtraParams) > 0 {
 		out.ExtraParams = copyExtraParams(override.ExtraParams)
 	}
@@ -435,12 +439,15 @@ func resolveExecutionTarget(profileValue *domain.ExecutionProfile, override *dom
 	return out, presence, nil
 }
 
-func validateAPIKey(apiKeyEnv string, apiKey string) error {
+func validateAPIKey(apiKeyEnv string, apiKey string, apiKeyRequired bool) error {
 	if strings.TrimSpace(apiKey) != "" {
 		return nil
 	}
 	envName := strings.TrimSpace(apiKeyEnv)
 	if envName == "" {
+		if apiKeyRequired {
+			return ErrAPIKeyRequired
+		}
 		return nil
 	}
 	if strings.TrimSpace(os.Getenv(envName)) == "" {
@@ -463,6 +470,7 @@ func executionProfileToTarget(p *domain.ExecutionProfile) domain.ExecutionTarget
 		ServiceTier:     p.ServiceTier,
 		ReasoningEffort: p.ReasoningEffort,
 		APIKeyEnv:       p.APIKeyEnv,
+		APIKeyRequired:  p.APIKeyRequired,
 		ExtraParams:     copyExtraParams(p.ExtraParams),
 	}
 }