Make GoDoc the public API contract

doc.go

@@ -1,8 +1,39 @@
 // Package promptkit provides an embeddable engine for preparing and executing
 // prompt-defined LLM workflows.
 //
-// Applications construct an Engine with NewEngine, select filesystem or
-// in-memory definition sources with options, and use Prepare or Run to execute
-// requests. Concrete repositories, validators, and outbound clients remain
-// internal implementation details.
+// Applications construct an [Engine] with [NewEngine], select filesystem or
+// in-memory sources with options, and call [Engine.Prepare] or [Engine.Run].
+// Concrete repositories, validators, and the built-in OpenAI-compatible client
+// remain internal implementation details.
+//
+// # Concurrency and ownership
+//
+// An Engine supports concurrent Prepare and Run calls. An injected [LLMClient]
+// or [ArtifactReader] can therefore receive concurrent calls and must be safe
+// for that use.
+//
+// NewEngine copies in-memory profiles. Prepare and Run copy request maps,
+// slices, pointer values, and JSON-compatible extra parameters before using
+// them. Returned values and values passed to extension interfaces are likewise
+// isolated from engine state. Callers own those copies and may mutate them
+// after the call that supplied or returned them.
+//
+// # JSON
+//
+// Stable JSON representations are provided for [PreparedRun], [RunResult],
+// [Artifact], [ExecutionTarget], [OutputContract], [ValidationResult],
+// [TokenUsage], [RenderedPrompt], [RenderedMessage], [CacheControl],
+// [StructuredOutputSpec], [StructuredOutputJSONSpec], [GenerateRequest],
+// [GenerateResponse], [ExecutionTargetPresence], and the string value types
+// used by those values.
+//
+// Construction values, including [Config], [RunRequest], [ArtifactRef],
+// [ExecutionTargetOverride], [Profile], and
+// [OpenAICompatibleProfileConfig], do not have stable JSON representations.
+// Direct API keys are nevertheless excluded from JSON for every public value.
+//
+// JSON timestamps use time.Time's RFC 3339 encoding and are omitted when zero.
+// PreparedRun and RunResult durations are encoded as integer milliseconds in
+// duration_ms and omitted when zero. Run IDs and all exposed hashes are opaque:
+// their spelling, length, character set, and algorithm are not API contracts.
 package promptkit