Document consumer safety and offline execution

docs/consumers/pkg-promptkit.md

@@ -16,8 +16,8 @@ import "gitea.maximumdirect.net/eric/promptkit"
 ```
 
 The following Go fragments are illustrative and omit surrounding package,
-import, and error-handling code. Use the maintained example for a complete
-program.
+import, and error-handling code. Use the maintained examples for complete
+programs.
 
 ## Construct An Engine
 
@@ -68,6 +68,13 @@ configured model client, classifies the generated artifact, and validates the
 content. A completed content check may return `ValidationFailed` in the result;
 an operational inability to validate returns an error.
 
+The maintained
+[offline execution example](../../examples/go-library/run/main.go) injects a
+deterministic model client and exercises `Run` without credentials, network
+access, or paid calls. It is intentionally separate from the preparation
+example so each workflow and its small prompt fixture can be copied and run on
+its own.
+
 Use the [`RunResult` and `ValidationResult` GoDoc](../../types.go) for the
 returned data and the `Engine.Run` GoDoc for failure and cancellation
 semantics. The
@@ -98,12 +105,29 @@ from supported JSON values and the package's `String` and `GoString`
 summaries. The exact precedence and redaction guarantees belong to
 [`RunRequest`, `GenerateRequest`, and the profile GoDoc](../../types.go).
 
+## Protect Files And Generated Data
+
+The default artifact reader opens a `File` reference as a caller-selected
+operating-system path. It does not constrain paths to an application root,
+impose an inbound request-size policy, or establish an untrusted-input security
+boundary. Applications must validate and restrict untrusted paths and payloads
+before constructing a request, or inject an artifact reader that enforces
+their filesystem, authorization, and size policies.
+
+Rendered messages, input and output artifact bodies, raw model output, and
+validation diagnostics can contain sensitive data. API-key redaction does not
+sanitize those values. Treat prepared values, results, collaborator requests,
+errors, and logs according to the application's data-access, retention, and
+secret-handling policies.
+
 ## Extension Interfaces
 
 Inject an [`LLMClient` or `ArtifactReader`](../../types.go) when the built-in
 behavior does not fit the application. Their GoDoc defines concurrent use,
 context handling, ownership of copied values, nil responses, and preservation
-of collaborator errors.
+of collaborator errors. Implementations must honor cancellation, safely manage
+copies they retain, avoid unsafe logging of content or credentials, and enforce
+the application policy that motivated the injection.
 
 ## Handle Errors
 
@@ -119,4 +143,5 @@ documented.
 
 Promptkit is an importable library. It does not own a command, inbound HTTP
 API, process configuration, or deployment policy. Applications map the root
-package's results and errors into those concerns.
+package's results and errors into those concerns, including inbound size and
+trust policy.

docs/internal/overview.md

@@ -13,6 +13,7 @@ contributor workflow and validation.
 | --- | --- | --- |
 | Root `promptkit` package | Provides the supported engine facade, source and injection options, public request and result values, built-in profile construction, extension interfaces, value conversion, redacted formatting, and public error mapping. | [Package GoDoc](../../doc.go), [engine assembly](../../engine.go) |
 | `examples/go-library/prepare` | Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, and `Prepare`. It is not a public library package. | [Example program](../../examples/go-library/prepare/main.go) |
+| `examples/go-library/run` | Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, an injected deterministic model client, and `Run`. It is not a public library package. | [Example program](../../examples/go-library/run/main.go) |
 | `internal/domain` | Defines internal framework values for requests, artifacts, prompt definitions, profiles, execution targets, rendering, generation, and validation. | [Domain declarations](../../internal/domain/domain.go) |
 | `internal/defaults` | Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits. | [Framework defaults](../../internal/defaults/defaults.go) |
 | `internal/filecatalog` | Provides deterministic YAML discovery and path helpers for operating-system filesystems and `fs.FS` sources. | [File catalog](../../internal/filecatalog/catalog.go) |

docs/policy/architecture.md

@@ -41,9 +41,9 @@ The implemented internal components consist of:
 - `internal/usecase`, which coordinates preparation and execution across the
   internal framework components.
 
-The `examples/go-library/prepare` package is a maintained downstream consumer
-of the root facade. It does not expose a library package or participate in
-internal assembly.
+The `examples/go-library/prepare` and `examples/go-library/run` packages are
+maintained downstream consumers of the root facade. They do not expose library
+packages or participate in internal assembly.
 
 The root facade assembles the internal repositories, renderer, validator,
 outbound client, and use-case runner while translating public values and

docs/roadmap/documentation.md

@@ -106,21 +106,25 @@ documented behavior whose compatibility risk warrants durable coverage.
 Move consumer-relevant security boundaries to the places where consumers will
 encounter them and add one representative execution workflow.
 
-- [ ] Explain in public GoDoc and the consumer guide that the default file
+- [x] Explain in public GoDoc and the consumer guide that the default file
   artifact reader accepts unrestricted caller-selected paths.
-- [ ] Make clear that Promptkit does not impose an application root, inbound
+- [x] Make clear that Promptkit does not impose an application root, inbound
   request-size policy, or untrusted-input security boundary.
-- [ ] Explain that rendered messages, artifact bodies, raw model output, and
+- [x] Explain that rendered messages, artifact bodies, raw model output, and
   validation details may be sensitive even when credentials are redacted.
-- [ ] Clarify the responsibilities of injected artifact readers and model
+- [x] Clarify the responsibilities of injected artifact readers and model
   clients for cancellation, copying, logging, and secret handling.
-- [ ] Add a maintained offline `Run` example using an injected deterministic
+- [x] Add a maintained offline `Run` example using an injected deterministic
   model client, without credentials, live network access, or paid calls.
-- [ ] Link the consumer guide to the execution example and keep embedded
+- [x] Link the consumer guide to the execution example and keep embedded
   snippets smaller than the maintained artifact.
-- [ ] Decide whether the existing preparation example should remain separate
+- [x] Decide whether the existing preparation example should remain separate
   or share reusable fixtures without obscuring either workflow.
 
+The preparation and execution examples remain separate, self-contained
+workflows. Each keeps its own small prompt fixture so consumers can copy or run
+one example without depending on the other.
+
 **Gate:** Both preparation and execution have complete, secret-free,
 deterministic consumer examples, and the consumer guide exposes the important
 filesystem and data-sensitivity boundaries without leaking internal mechanics.