Add framework documentation and offline example

docs/policy/architecture.md

@@ -9,8 +9,9 @@ implemented packages without redefining these rules.
 
 ## System Shape
 
-Promptkit is an importable Go library. It does not provide a runnable command,
-an HTTP service, or another application process.
+Promptkit is an importable Go library. It does not ship a command, an HTTP
+service, or another application process. Repository examples demonstrate
+library use but are not Promptkit applications or release artifacts.
 
 The module root contains package `promptkit`, which is the public facade. It
 provides the supported engine, configuration and source options, requests,
@@ -40,6 +41,10 @@ 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 root facade assembles the internal repositories, renderer, validator,
 outbound client, and use-case runner while translating public values and
 errors at the library boundary. The defaults and renderer depend on the domain

docs/policy/documentation.md

@@ -75,13 +75,14 @@ mechanisms, not secret values.
 | Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression policy, and test maintenance. | Subsystem behavior, exact public contracts, subsystem-specific test inventories, and implementation plans. |
 | Release procedure | `docs/release.md`, when present | Required release validation, version and tag procedure, release ordering, and post-publication checks. | General contributor workflow, public API semantics, and decision history. |
 | Exact exported Go API | Go declarations and GoDoc, as APIs are implemented | Exported names, signatures, types, values, errors, and exact behavioral contracts. | Task-oriented consumer walkthroughs, implementation details, and future API proposals. |
+| Framework file formats | `docs/formats.md` | Prompt-definition and profile YAML fields, schema references, defaults, validation modes, built-in profiles, credentials, and file-to-request precedence. | Exported Go declarations, outbound wire behavior, internal parsing mechanics, and application configuration. |
 | Consumer guidance | `docs/consumers/`, when consumer workflows require dedicated guidance | Task-oriented use of implemented public APIs, minimal examples, and consumer responsibilities. | Exact exported declarations and internal mechanics. |
 | Durable integration contracts | `docs/integrations/`, when integrations exist | External formats and protocols, compatibility behavior, and upstream or downstream responsibilities. | Internal transformations and public Go declarations. |
 | Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal documents. | Normative architecture, contributor workflow, external contracts, and proposed components. |
 | Internal subsystem behavior | Other files under `docs/internal/`, when a subsystem needs durable detail | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, public API definitions, and future package plans. |
 | Architectural decision history | `docs/adr/`, when repository-local decisions require records | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, and task sequencing. |
 | Temporary feature roadmaps | `docs/roadmap/`, while planned work needs coordination | Proposed or accepted scope, sequencing, gates, and implementation status. | Implemented behavior reference and durable decision rationale. |
-| Complete copyable artifacts | `examples/`, when maintained examples exist | Valid inputs, Go programs, and other files intended to be copied or run. | Field-by-field reference, exact API declarations, and prose explanation. |
+| Complete copyable artifacts | `examples/` | Valid inputs, Go programs, and other files intended to be copied or run. | Field-by-field reference, exact API declarations, and prose explanation. |
 
 Conditional owners do not require placeholder files or directories. Create a
 consumer, integration, subsystem, ADR, roadmap, or example document only when
@@ -105,6 +106,9 @@ for a task. Internal documents explain how Promptkit implements them. Internal
 documentation may identify a public type or external format as a dependency,
 but must link to its canonical definition rather than restate it.
 
+The [framework format reference](../formats.md) owns exact prompt, profile, and
+schema-file contracts. Integration documents own external wire formats.
+
 ### Security Topics
 
 This policy owns what documentation and examples may contain. Architecture owns

docs/policy/testing.md

@@ -55,6 +55,15 @@ documentation-link, and repository-hygiene checks before accepting changes.
 Introducing hosted CI later would supplement, not silently redefine, this
 documented validation model.
 
+The complete test sequence includes ordinary and race-enabled package tests.
+The maintained offline consumer workflow is also run from the repository root:
+
+```sh
+go test ./...
+go test -race ./...
+go run ./examples/go-library/prepare
+```
+
 Tests in the default suite must be deterministic, offline, and independent of
 real credentials. They must not invoke paid APIs, use live network
 dependencies, or depend on mutable external services. Tests that require live
@@ -77,6 +86,10 @@ Use each test type where it protects a distinct risk:
   relied upon by consumers.
 - Integration tests use real collaborators when correctness depends on their
   interaction, while replacing live or nondeterministic external boundaries.
+- External-package root tests exercise the public facade as a Go consumer,
+  while internal package tests own focused implementation behavior.
+- The maintained offline preparation example protects one representative
+  assembled consumer workflow without contacting a model provider.
 - Fixtures should be minimal, synthetic, versioned with the behavior they
   exercise, and free of credentials or private data.
 - Golden files are appropriate only when the complete output is intentionally
@@ -154,7 +167,8 @@ A test failing is not the same as a test needing to be edited. Many tests may co
 
 Configurable thresholds and defaults must not be duplicated throughout the test suite.
 
-For example, do not encode an internal concurrency limit indirectly:
+The following fragments are illustrative rather than standalone Go programs.
+Do not encode an internal concurrency limit indirectly:
 
 ```go
 // Production policy: