Add framework documentation and offline example

docs/consumers/pkg-promptkit.md

@@ -9,7 +9,8 @@ import "gitea.maximumdirect.net/eric/promptkit"
 Package `promptkit` is the supported Go contract for in-process prompt
 preparation and execution. The declarations and their GoDoc in the
 [root package](../../doc.go) own the exact API; this guide explains how the
-pieces are used together.
+pieces are used together. The [framework format reference](../formats.md) owns
+prompt, profile, and schema file contracts.
 
 ## Engine Construction And Sources
 
@@ -32,10 +33,9 @@ The [source options](../../engine.go) replace their matching directory source:
 - `WithLLMClient` replaces the built-in model client; and
 - `WithArtifactReader` replaces the default reader for every input.
 
-Prompt-content and schema paths from an `fs.FS` stay within the configured
-root. Single-file prompt and profile sources select definitions by YAML ID.
-Relative prompt content resolves from its prompt file, while a single schema
-is addressed by its base name.
+Source selection, path resolution, strict decoding, profile overlays, and
+file-to-request precedence are defined in the
+[framework format reference](../formats.md).
 
 Per-generation timeout values from profiles or requests are independent of
 the transport cap and caller context. An explicit request value of zero
@@ -49,28 +49,10 @@ defines the complete timeout layering.
 [`RunRequest`](../../types.go). `Prepare` resolves the prompt, profile, input
 artifacts, validation contract, and rendered messages without calling an LLM.
 `Run` performs the same preparation, calls the configured client, and validates
-the generated content.
-
-```go
-engine, err := promptkit.NewEngine(promptkit.Config{
-	PromptDir:  "./prompts",
-	ProfileDir: "./profiles",
-})
-if err != nil {
-	return err
-}
-
-prepared, err := engine.Prepare(ctx, promptkit.RunRequest{
-	PromptID: "meeting.summary",
-	Inputs: map[string]promptkit.ArtifactRef{
-		"transcript": promptkit.File("./transcript.md"),
-	},
-})
-if err != nil {
-	return err
-}
-_ = prepared.Messages
-```
+the generated content. The maintained
+[offline preparation example](../../examples/go-library/prepare/main.go)
+provides a complete runnable workflow using a prompt file, in-memory profile,
+and inline input.
 
 [`PreparedRun` and `RunResult`](../../types.go) expose copied public values.
 Preparation returns effective settings, hashes, rendered messages, selected
@@ -86,8 +68,10 @@ returns an error matching `ErrValidation`.
 
 The [request and value declarations](../../types.go) own the available fields,
 serialized constants, and result shapes. Use `File`, `Inline`, or
-`InlineWithURI` to construct artifact references. Required declared inputs and
-every input referenced by a template must be supplied.
+`InlineWithURI` to construct artifact references. The
+[framework format reference](../formats.md) defines declared inputs, template
+references, output contracts, and the relationship between file values and
+request overrides.
 
 `ExecutionTargetOverride` uses pointers for numeric settings so an explicit
 zero remains distinct from no override. `ExtraParams` accepts JSON-compatible
@@ -110,7 +94,9 @@ precedence over explicit file sources and built-ins.
 Raw API keys do not belong in profiles. File-backed profiles may name an
 environment variable, while an in-memory profile can require a request key.
 A direct `RunRequest.APIKey` is request-scoped and takes precedence over an
-environment lookup for the built-in client.
+environment lookup for the built-in client. Profile fields, ranges, built-ins,
+precedence, and credential rules are owned by the
+[framework format reference](../formats.md).
 
 API keys are excluded from JSON, prepared values, and results. The public
 `String` and `GoString` methods report only whether a direct key is present.