Document consumer safety and offline execution

types.go

@@ -244,6 +244,11 @@ type Artifact struct {
 // value. Readers supply artifact metadata, and the engine assigns an input-map
 // name only when the returned artifact name is empty.
 //
+// An injected reader owns any application-specific path containment,
+// authorization, content-size, and content-type policy. It must protect
+// sensitive references and bodies in its logging and in any copies it retains.
+// It may reuse or mutate the returned artifact and body after Read returns.
+//
 // Returning a non-nil error makes the engine return an error matching
 // ErrArtifactLoad while preserving the reader error through errors.Is.
 // Returning a nil artifact with a nil error also produces ErrArtifactLoad.
@@ -519,6 +524,11 @@ type StructuredOutputJSONSpec struct {
 // slices, and pointers are client-owned copies and may be mutated or retained
 // without affecting engine state.
 //
+// Generate receives rendered messages and may receive a direct API key. A
+// client must protect those values and any raw output in its logging, storage,
+// and retained copies. It is responsible for the cancellation behavior of any
+// work it starts and for synchronizing access to retained or shared data.
+//
 // A returned error makes Run return ErrLLMGenerate while preserving the client
 // error through errors.Is. A nil response with a nil error also produces
 // ErrLLMGenerate. Promptkit copies the non-nil response before returning from
@@ -557,6 +567,11 @@ type GenerateResponse struct {
 }
 
 // File returns a file-backed artifact reference whose URI is path.
+//
+// The default artifact reader opens path as a caller-selected operating-system
+// path without restricting it to an application root or imposing a size limit.
+// Applications accepting untrusted paths must validate them before calling
+// Promptkit or use [WithArtifactReader] to enforce application policy.
 func File(path string) ArtifactRef {
 	return ArtifactRef{Type: ArtifactRefFile, URI: path}
 }