Record public facade boundary validation

.gitignore

@@ -1,6 +1,5 @@
 # ---> Codex
 .codex
-AGENTS.md
 
 # ---> Go
 # If you prefer the allow list template instead of the deny list, see community template:

AGENTS.md

@@ -0,0 +1 @@
+Please review `docs/development.md` for initial orientation in this repository and follow its task-specific reading guide.

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2026 eric. 
+Copyright (c) 2026 Eric Rakestraw. 
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 

README.md

@@ -1,8 +1,12 @@
 # scriptorium
 
-Scriptorium is a config-driven prompt execution engine.
+Scriptorium is a narrow prompt-execution application for rendering prompt
+requests, running them against OpenAI-compatible chat-completions endpoints, and
+serving the same run workflow over HTTP.
 
-It separates prompt definitions (what to generate) from execution profiles (how to call an OpenAI-compatible model endpoint), then runs or renders a prepared request from named input artifacts.
+It keeps prompt definitions, execution profiles, schemas, and input artifacts as
+separate files so prompts can be reviewed and reused without baking model
+runtime settings into application code.
 
 ## Quickstart
 
@@ -18,19 +22,24 @@ go run ./cmd/scriptorium render \
 ```
 
 This command renders the prepared prompt and effective runtime settings without calling an LLM.
+For complete invocation and output behavior, see the [CLI reference](docs/cli.md).
 
 ## Documentation
 
 - [CLI reference](docs/cli.md)
 - [Configuration reference](docs/config.md)
+- [HTTP API reference](docs/api.md)
 - [Operations guide](docs/operations.md)
-- [Troubleshooting](docs/troubleshooting.md)
-- [HTTP API integration](docs/integrations/http-api.md)
+- [Consumer integration overview](docs/consumers/api.md)
+- [Go library package](docs/consumers/pkg-scriptorium.md)
+- [Subprocess integration](docs/integrations/subprocess.md)
 - [OpenAI-compatible chat integration](docs/integrations/openai-compatible-chat.md)
-- [Narratio subprocess integration](docs/integrations/narratio.md)
 - [Architecture policy](docs/policy/architecture.md)
 
 ## Examples
 
-- `examples/render-markdown-summary.sh`
-- `examples/http-run.json`
+- [Minimal configuration](examples/config.yml) and [complete configuration](examples/config.full.yml)
+- [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/), [schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/)
+- [Render script](examples/render-markdown-summary.sh)
+- [HTTP request](examples/http-run.json)
+- [Go library example](examples/go-library/prepare/main.go)

artifact_reader.go

@@ -0,0 +1,39 @@
+package scriptorium
+
+import (
+	"context"
+	"errors"
+
+	artifactadapter "gitea.maximumdirect.net/eric/scriptorium/internal/artifact"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+)
+
+var errNilArtifactReaderResponse = errors.New("artifact reader returned nil artifact without error")
+
+type publicArtifactReaderAdapter struct {
+	reader ArtifactReader
+}
+
+var _ artifactadapter.Reader = publicArtifactReaderAdapter{}
+
+func (a publicArtifactReaderAdapter) Read(ctx context.Context, ref domain.ArtifactRef) (*domain.Artifact, error) {
+	artifact, err := a.reader.Read(ctx, ArtifactRef{
+		Type: ArtifactRefType(ref.Type),
+		URI:  ref.URI,
+		Body: ref.Body,
+	})
+	if err != nil {
+		return nil, err
+	}
+	if artifact == nil {
+		return nil, errNilArtifactReaderResponse
+	}
+	return &domain.Artifact{
+		Name:        artifact.Name,
+		ContentType: artifact.ContentType,
+		Body:        copyBytes(artifact.Body),
+		URI:         artifact.URI,
+		Size:        artifact.Size,
+		Hash:        artifact.Hash,
+	}, nil
+}

artifact_reader_internal_test.go

@@ -0,0 +1,36 @@
+package scriptorium
+
+import (
+	"context"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+)
+
+func TestPublicArtifactReaderAdapterCopiesBody(t *testing.T) {
+	reader := internalArtifactReaderFake{
+		artifact: &Artifact{Body: []byte("original")},
+	}
+	adapter := publicArtifactReaderAdapter{reader: &reader}
+
+	artifact, err := adapter.Read(context.Background(), domain.ArtifactRef{
+		Type: domain.ArtifactRefInline,
+		URI:  "memory://input",
+		Body: "input",
+	})
+	if err != nil {
+		t.Fatalf("read artifact: %v", err)
+	}
+	artifact.Body[0] = 'X'
+	if got := string(reader.artifact.Body); got != "original" {
+		t.Fatalf("reader artifact body was mutated: %q", got)
+	}
+}
+
+type internalArtifactReaderFake struct {
+	artifact *Artifact
+}
+
+func (r *internalArtifactReaderFake) Read(context.Context, ArtifactRef) (*Artifact, error) {
+	return r.artifact, nil
+}

convert.go

@@ -0,0 +1,406 @@
+package scriptorium
+
+import (
+	"reflect"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+)
+
+func toDomainRunRequest(req RunRequest) (domain.RunRequest, error) {
+	execution, err := toDomainExecutionTargetOverride(req.Execution)
+	if err != nil {
+		return domain.RunRequest{}, err
+	}
+	return domain.RunRequest{
+		PromptID:      req.PromptID,
+		PromptVersion: req.PromptVersion,
+		ProfileID:     req.ProfileID,
+		APIKey:        req.APIKey,
+		Inputs:        toDomainArtifactRefMap(req.Inputs),
+		Vars:          copyStringMap(req.Vars),
+		Execution:     execution,
+		Validation:    toDomainOutputContractPtr(req.Validation),
+		Metadata:      copyStringMap(req.Metadata),
+	}, nil
+}
+
+func fromDomainPreparedRun(prepared *domain.PreparedRun) *PreparedRun {
+	if prepared == nil {
+		return nil
+	}
+	return &PreparedRun{
+		PromptID:             prepared.PromptID,
+		PromptVersion:        prepared.PromptVersion,
+		PromptHash:           prepared.PromptHash,
+		SelectedProfileID:    prepared.SelectedProfileID,
+		EffectiveModelParams: fromDomainExecutionTarget(prepared.EffectiveModelParams),
+		OutputContract:       fromDomainOutputContract(prepared.OutputContract),
+		StructuredOutput:     fromDomainStructuredOutputSpec(prepared.StructuredOutput),
+		InputHashes:          copyStringMap(prepared.InputHashes),
+		SessionID:            prepared.SessionID,
+		RenderedPromptHash:   prepared.RenderedPromptHash,
+		Messages:             fromDomainRenderedMessages(prepared.Messages),
+		StartTime:            prepared.StartTime,
+		EndTime:              prepared.EndTime,
+		DurationMS:           prepared.DurationMS,
+	}
+}
+
+func fromDomainRunResult(result *domain.RunResult) *RunResult {
+	if result == nil {
+		return nil
+	}
+	return &RunResult{
+		RunID:                result.RunID,
+		Artifact:             fromDomainArtifact(result.Artifact),
+		RawOutput:            result.RawOutput,
+		Validation:           fromDomainValidationResult(result.Validation),
+		PromptID:             result.PromptID,
+		PromptVersion:        result.PromptVersion,
+		PromptHash:           result.PromptHash,
+		RenderedPromptHash:   result.RenderedPromptHash,
+		SelectedProfileID:    result.SelectedProfileID,
+		ModelName:            result.ModelName,
+		Endpoint:             result.Endpoint,
+		EffectiveModelParams: fromDomainExecutionTarget(result.EffectiveModelParams),
+		InputHashes:          copyStringMap(result.InputHashes),
+		Usage:                fromDomainTokenUsage(result.Usage),
+		StartTime:            result.StartTime,
+		EndTime:              result.EndTime,
+		Duration:             result.Duration,
+	}
+}
+
+func fromDomainGenerateRequest(req domain.GenerateRequest) GenerateRequest {
+	return GenerateRequest{
+		Prompt:           fromDomainRenderedPrompt(req.Prompt),
+		Target:           fromDomainExecutionTarget(req.Target),
+		TargetPresence:   fromDomainExecutionTargetPresence(req.TargetPresence),
+		StructuredOutput: fromDomainStructuredOutputSpec(req.StructuredOutput),
+		APIKey:           req.Target.APIKey,
+	}
+}
+
+func toDomainGenerateResponse(resp *GenerateResponse) *domain.GenerateResponse {
+	if resp == nil {
+		return nil
+	}
+	return &domain.GenerateResponse{
+		Content: resp.Content,
+		Usage:   toDomainTokenUsage(resp.Usage),
+	}
+}
+
+func fromDomainRenderedPrompt(prompt domain.RenderedPrompt) RenderedPrompt {
+	return RenderedPrompt{
+		SessionID: prompt.SessionID,
+		Messages:  fromDomainRenderedMessages(prompt.Messages),
+	}
+}
+
+func toDomainArtifactRefMap(src map[string]ArtifactRef) map[string]domain.ArtifactRef {
+	if src == nil {
+		return nil
+	}
+	out := make(map[string]domain.ArtifactRef, len(src))
+	for k, v := range src {
+		out[k] = toDomainArtifactRef(v)
+	}
+	return out
+}
+
+func toDomainArtifactRef(ref ArtifactRef) domain.ArtifactRef {
+	return domain.ArtifactRef{
+		Type: domain.ArtifactRefType(ref.Type),
+		URI:  ref.URI,
+		Body: ref.Body,
+	}
+}
+
+func fromDomainArtifact(artifact domain.Artifact) Artifact {
+	return Artifact{
+		Name:        artifact.Name,
+		ContentType: artifact.ContentType,
+		Body:        copyBytes(artifact.Body),
+		URI:         artifact.URI,
+		Size:        artifact.Size,
+		Hash:        artifact.Hash,
+	}
+}
+
+func toDomainExecutionTargetOverride(override *ExecutionTargetOverride) (*domain.ExecutionTargetOverride, error) {
+	if override == nil {
+		return nil, nil
+	}
+	extraParams, err := copyPublicJSONMap(override.ExtraParams)
+	if err != nil {
+		return nil, err
+	}
+	return &domain.ExecutionTargetOverride{
+		Endpoint:        override.Endpoint,
+		Model:           override.Model,
+		Temperature:     copyFloat64Ptr(override.Temperature),
+		MaxTokens:       copyIntPtr(override.MaxTokens),
+		TopP:            copyFloat64Ptr(override.TopP),
+		TimeoutSeconds:  copyIntPtr(override.TimeoutSeconds),
+		ServiceTier:     override.ServiceTier,
+		ReasoningEffort: override.ReasoningEffort,
+		APIKeyEnv:       override.APIKeyEnv,
+		ExtraParams:     extraParams,
+	}, nil
+}
+
+func fromDomainExecutionTarget(target domain.ExecutionTarget) ExecutionTarget {
+	return ExecutionTarget{
+		Endpoint:        target.Endpoint,
+		Model:           target.Model,
+		Temperature:     target.Temperature,
+		MaxTokens:       target.MaxTokens,
+		TopP:            target.TopP,
+		TimeoutSeconds:  target.TimeoutSeconds,
+		ServiceTier:     target.ServiceTier,
+		ReasoningEffort: target.ReasoningEffort,
+		APIKeyEnv:       target.APIKeyEnv,
+		ExtraParams:     copyAnyMap(target.ExtraParams),
+	}
+}
+
+func fromDomainExecutionTargetPresence(presence domain.ExecutionTargetPresence) ExecutionTargetPresence {
+	return ExecutionTargetPresence{
+		Temperature:    presence.Temperature,
+		MaxTokens:      presence.MaxTokens,
+		TopP:           presence.TopP,
+		TimeoutSeconds: presence.TimeoutSeconds,
+	}
+}
+
+func toDomainOutputContractPtr(contract *OutputContract) *domain.OutputContract {
+	if contract == nil {
+		return nil
+	}
+	out := toDomainOutputContract(*contract)
+	return &out
+}
+
+func toDomainOutputContract(contract OutputContract) domain.OutputContract {
+	return domain.OutputContract{
+		Format:         domain.OutputFormat(contract.Format),
+		ValidationMode: domain.ValidationMode(contract.ValidationMode),
+		SchemaPath:     contract.SchemaPath,
+		RepairAttempts: contract.RepairAttempts,
+	}
+}
+
+func fromDomainOutputContract(contract domain.OutputContract) OutputContract {
+	return OutputContract{
+		Format:         OutputFormat(contract.Format),
+		ValidationMode: ValidationMode(contract.ValidationMode),
+		SchemaPath:     contract.SchemaPath,
+		RepairAttempts: contract.RepairAttempts,
+	}
+}
+
+func fromDomainValidationResult(result domain.ValidationResult) ValidationResult {
+	return ValidationResult{
+		Status:         ValidationStatus(result.Status),
+		Mode:           ValidationMode(result.Mode),
+		Errors:         copyStringSlice(result.Errors),
+		SchemaPath:     result.SchemaPath,
+		RepairAttempts: result.RepairAttempts,
+		IsValid:        result.IsValid,
+	}
+}
+
+func fromDomainTokenUsage(usage domain.TokenUsage) TokenUsage {
+	return TokenUsage{
+		PromptTokens:     usage.PromptTokens,
+		CompletionTokens: usage.CompletionTokens,
+		TotalTokens:      usage.TotalTokens,
+		CachedTokens:     usage.CachedTokens,
+		CacheWriteTokens: usage.CacheWriteTokens,
+	}
+}
+
+func toDomainTokenUsage(usage TokenUsage) domain.TokenUsage {
+	return domain.TokenUsage{
+		PromptTokens:     usage.PromptTokens,
+		CompletionTokens: usage.CompletionTokens,
+		TotalTokens:      usage.TotalTokens,
+		CachedTokens:     usage.CachedTokens,
+		CacheWriteTokens: usage.CacheWriteTokens,
+	}
+}
+
+func fromDomainRenderedMessages(messages []domain.RenderedMessage) []RenderedMessage {
+	if messages == nil {
+		return nil
+	}
+	out := make([]RenderedMessage, len(messages))
+	for i, msg := range messages {
+		out[i] = RenderedMessage{
+			Role:         msg.Role,
+			Content:      msg.Content,
+			CacheControl: fromDomainCacheControl(msg.CacheControl),
+		}
+	}
+	return out
+}
+
+func fromDomainCacheControl(cacheControl *domain.CacheControl) *CacheControl {
+	if cacheControl == nil {
+		return nil
+	}
+	return &CacheControl{
+		Type: CacheControlType(cacheControl.Type),
+		TTL:  cacheControl.TTL,
+	}
+}
+
+func fromDomainStructuredOutputSpec(spec *domain.StructuredOutputSpec) *StructuredOutputSpec {
+	if spec == nil {
+		return nil
+	}
+	out := &StructuredOutputSpec{
+		Type: StructuredOutputType(spec.Type),
+	}
+	if spec.JSONSchema != nil {
+		out.JSONSchema = &StructuredOutputJSONSpec{
+			Name:   spec.JSONSchema.Name,
+			Strict: spec.JSONSchema.Strict,
+			Schema: copyAny(spec.JSONSchema.Schema),
+		}
+	}
+	return out
+}
+
+func copyStringMap(src map[string]string) map[string]string {
+	if src == nil {
+		return nil
+	}
+	out := make(map[string]string, len(src))
+	for k, v := range src {
+		out[k] = v
+	}
+	return out
+}
+
+func copyAnyMap(src map[string]any) map[string]any {
+	if src == nil {
+		return nil
+	}
+	out := make(map[string]any, len(src))
+	for k, v := range src {
+		out[k] = copyAny(v)
+	}
+	return out
+}
+
+func copyAny(value any) any {
+	if value == nil {
+		return nil
+	}
+	switch v := value.(type) {
+	case map[string]any:
+		return copyAnyMap(v)
+	case []any:
+		out := make([]any, len(v))
+		for i, item := range v {
+			out[i] = copyAny(item)
+		}
+		return out
+	case []string:
+		return copyStringSlice(v)
+	case []byte:
+		return copyBytes(v)
+	default:
+		return copyReflectValue(reflect.ValueOf(value)).Interface()
+	}
+}
+
+func copyReflectValue(value reflect.Value) reflect.Value {
+	if !value.IsValid() {
+		return value
+	}
+
+	switch value.Kind() {
+	case reflect.Interface:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		copied := copyReflectValue(value.Elem())
+		if copied.IsValid() && copied.Type().AssignableTo(value.Type()) {
+			return copied
+		}
+		out := reflect.New(value.Type()).Elem()
+		out.Set(copied)
+		return out
+	case reflect.Pointer:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		out := reflect.New(value.Type().Elem())
+		out.Elem().Set(copyReflectValue(value.Elem()))
+		return out
+	case reflect.Map:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		out := reflect.MakeMapWithSize(value.Type(), value.Len())
+		iter := value.MapRange()
+		for iter.Next() {
+			out.SetMapIndex(copyReflectValue(iter.Key()), copyReflectValue(iter.Value()))
+		}
+		return out
+	case reflect.Slice:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		out := reflect.MakeSlice(value.Type(), value.Len(), value.Cap())
+		for i := 0; i < value.Len(); i++ {
+			out.Index(i).Set(copyReflectValue(value.Index(i)))
+		}
+		return out
+	case reflect.Array:
+		out := reflect.New(value.Type()).Elem()
+		for i := 0; i < value.Len(); i++ {
+			out.Index(i).Set(copyReflectValue(value.Index(i)))
+		}
+		return out
+	default:
+		return value
+	}
+}
+
+func copyStringSlice(src []string) []string {
+	if src == nil {
+		return nil
+	}
+	out := make([]string, len(src))
+	copy(out, src)
+	return out
+}
+
+func copyBytes(src []byte) []byte {
+	if src == nil {
+		return nil
+	}
+	out := make([]byte, len(src))
+	copy(out, src)
+	return out
+}
+
+func copyFloat64Ptr(src *float64) *float64 {
+	if src == nil {
+		return nil
+	}
+	v := *src
+	return &v
+}
+
+func copyIntPtr(src *int) *int {
+	if src == nil {
+		return nil
+	}
+	v := *src
+	return &v
+}

docs/adr/0001-adopt-canonical-documentation-ownership.md

@@ -0,0 +1,48 @@
+# ADR 0001: Adopt Canonical Documentation Ownership
+
+## Status
+
+Accepted
+
+## Date
+
+2026-07-26
+
+## Context
+
+Scriptorium's documentation grew alongside its CLI, HTTP, public Go, and
+integration interfaces. As a result, several documents repeated mutable
+contracts such as flags, configuration fields, and status behavior. Those
+parallel definitions made it unclear which document to update when behavior
+changed and increased the risk of documentation drift.
+
+## Decision
+
+Assign each documentation topic one canonical owner, as defined in
+[`docs/policy/documentation.md`](../policy/documentation.md). Non-owning
+documents may provide short orientation and links, but do not redefine volatile
+contracts. Current behavior is documented outside `docs/roadmap/`; roadmaps own
+future work, sequencing, and implementation status.
+
+## Alternatives Considered
+
+- Keep broad reference material in several audience-specific documents. This
+  would preserve local convenience but leave conflicting contract definitions
+  likely.
+- Consolidate all documentation into one reference. This would reduce duplicate
+  text but would not serve the distinct needs of users, operators, consumers,
+  and contributors.
+
+## Rationale
+
+Canonical ownership retains audience-specific guidance while making the source
+of truth for each contract discoverable. It also makes documentation changes
+reviewable alongside the implementation change that requires them.
+
+## Consequences
+
+- Changes to behavior must update the canonical owner in the same change.
+- Cross-cutting documentation links to the owner instead of copying its
+  details.
+- Documentation restructuring followed a dedicated implementation roadmap;
+  repository history, not this ADR, records its completion.

docs/adr/0002-split-promptkit-from-scriptorium.md

@@ -0,0 +1,288 @@
+# ADR 0002: Split Promptkit From Scriptorium
+
+## Status
+
+Accepted
+
+## Date
+
+2026-07-26
+
+## Context
+
+Scriptorium currently combines two products in one Go module:
+
+- a reusable prompt-execution framework with a public Go facade; and
+- a runnable application with CLI and HTTP interfaces.
+
+Downstream Go projects increasingly import the framework directly and do not
+use the executable interfaces. Keeping both products in one module couples
+framework releases, dependencies, documentation, and public API evolution to
+application-specific transport concerns.
+
+Promptkit will become the framework project, and Scriptorium will become a slim
+application that consumes it. This ADR records that end-state boundary. It does
+not assert that the split has been implemented; until then, the current
+repository structure and contracts remain authoritative.
+
+## Decision
+
+### Projects And Module Paths
+
+Create a repository named `promptkit` alongside Scriptorium:
+
+| Project | Repository and Go module path | Root Go package |
+| --- | --- | --- |
+| Promptkit | `gitea.maximumdirect.net/eric/promptkit` | `promptkit` |
+| Scriptorium | `gitea.maximumdirect.net/eric/scriptorium` | No reusable root facade after migration |
+
+Promptkit will expose its supported public API from the module root. Its
+implementation packages will remain under `internal/` unless a real consumer
+extension point requires a public type or interface.
+
+Scriptorium will import only Promptkit's supported public packages. It will not
+import Promptkit implementation packages or reproduce Promptkit orchestration.
+
+### Product Responsibilities
+
+Promptkit owns application-neutral framework behavior:
+
+- the engine and its `Prepare` and `Run` workflow;
+- public request, result, profile, option, extension, and error APIs;
+- prompt-definition loading and rendering;
+- profile loading, overlays, and the embedded built-in profile registry;
+- schema loading and output validation;
+- provider-neutral model-client boundaries and the OpenAI-compatible client;
+- artifact types, artifact-reader injection, and general-purpose inline and
+  caller-selected file readers;
+- execution-setting resolution and framework defaults; and
+- framework-level secret redaction and error classification.
+
+Scriptorium owns executable and transport behavior:
+
+- the `scriptorium` process and its `run`, `render`, and `serve` commands;
+- CLI parsing, streams, output files, formatting, exit codes, and process
+  cancellation behavior;
+- application-configuration discovery and CLI-over-configuration precedence;
+- HTTP routing, strict request decoding, DTO mapping, response encoding,
+  status codes, and transport limits;
+- HTTP artifact-root containment and deployment policy;
+- server construction, server defaults, and process logging; and
+- executable release artifacts.
+
+The dependency direction is:
+
+```text
+Scriptorium CLI and HTTP adapters
+                |
+                v
+       Promptkit public API
+                |
+                v
+  injected sources, readers, and model clients
+```
+
+### Current Package Disposition
+
+Implementation may reorganize files during extraction, but each current package
+has this target owner:
+
+| Current package or file group | Target owner | Disposition |
+| --- | --- | --- |
+| Root `scriptorium` facade files and tests | Promptkit | Move and rename the public package to `promptkit`; Scriptorium retains no compatibility facade. |
+| `internal/domain`, `internal/usecase` | Promptkit | Move as internal engine implementation. |
+| `internal/promptdef`, `internal/prompt` | Promptkit | Move as internal prompt loading and rendering. |
+| `internal/profile`, `internal/profile/builtin` | Promptkit | Move with embedded built-in assets and registry tests. |
+| `internal/filecatalog` | Promptkit | Move as source-loading support. |
+| `internal/validate` | Promptkit | Move as schema and output-validation implementation. |
+| `internal/llm` | Promptkit | Move with the OpenAI-compatible integration. |
+| `internal/artifact` | Split | Move general inline/file reading to Promptkit; keep rooted, denied, and byte-limited HTTP file reading in Scriptorium behind a Promptkit reader interface. |
+| `internal/defaults` | Split | Move framework, execution, output-artifact, content-type, and model-client defaults to Promptkit; keep CLI, HTTP, and server defaults in Scriptorium. |
+| `internal/adapter/cli`, `internal/adapter/http` | Scriptorium | Keep and refactor to use Promptkit's public API. |
+| `internal/config` | Scriptorium | Keep application settings, discovery, validation, and CLI precedence. |
+| `internal/format` | Scriptorium | Keep prepared-run presentation, rewritten against Promptkit public values. |
+| `cmd/scriptorium` | Scriptorium | Keep as the process entrypoint. |
+
+Tests move with the behavior they protect. Cross-boundary tests will live with
+the consuming side: Promptkit protects framework contracts, while Scriptorium
+protects adapter mapping, HTTP containment, and executable behavior.
+
+### Public Boundary
+
+Promptkit's initial facade will preserve the useful shape of the current
+Scriptorium Go API where that reduces extraction risk. It will expose only the
+capabilities required by Promptkit consumers and by Scriptorium:
+
+- engine construction, preparation, and execution;
+- public request, result, profile, and error values;
+- prompt, profile, schema, artifact-reader, validator, and model-client source
+  or injection options that have demonstrated consumers; and
+- enough stable error identity for Scriptorium to map CLI and HTTP outcomes.
+
+Promptkit will not export its domain package, runner implementation,
+repositories, adapter DTOs, or general internal constructors merely to
+simplify the move.
+
+Scriptorium's CLI and HTTP adapters will depend on a small consumer-facing
+`Prepare`/`Run` interface where test substitution is needed. That interface
+belongs at the consuming boundary rather than forcing adapter concepts into
+Promptkit.
+
+### Artifact Reading And HTTP Containment
+
+Promptkit will define the artifact-reader extension point used during
+preparation. Its ordinary file reader may read a path deliberately supplied by
+an in-process or CLI caller and does not claim to be a deployment sandbox.
+
+Scriptorium will implement the HTTP-specific reader that:
+
+- denies file references when no artifact root is configured;
+- applies the configured artifact byte limit;
+- enforces Scriptorium's documented lexical root-containment rule; and
+- maps reader failures to Scriptorium HTTP error responses.
+
+Scriptorium will inject that reader through Promptkit's public construction
+boundary. Promptkit will not know about HTTP roots, status codes, request DTOs,
+or deployment policy.
+
+### Configuration And Default Ownership
+
+Configuration ownership follows the behavior configured, not the current file
+location:
+
+| Configuration category | Owner |
+| --- | --- |
+| Application configuration discovery, configuration-file precedence, `prompt_dir`, `profile_dir`, and `schema_dir` | Scriptorium |
+| CLI flags and their mapping to application settings or request overrides | Scriptorium |
+| `server.*`, render-output settings, HTTP byte limits, and server defaults | Scriptorium |
+| Prompt-definition, profile, and output-contract file formats | Promptkit |
+| Prompt/profile source selection, overlays, schema behavior, and built-in profiles | Promptkit |
+| Execution settings, presence-aware request overrides, and execution defaults | Promptkit |
+| Built-in OpenAI-compatible client settings, timeout behavior, and provider wire mapping | Promptkit |
+| HTTP request and response fields, including their mapping to framework values | Scriptorium |
+
+Scriptorium will translate its application settings and external request
+values into Promptkit construction options and requests. When an omitted
+Scriptorium setting means “use the framework default,” Scriptorium will omit
+the override rather than copy Promptkit's numeric default.
+
+### Compatibility And Versioning
+
+This migration is intentionally breaking:
+
+- new Go consumers will import `gitea.maximumdirect.net/eric/promptkit`;
+- Scriptorium will not provide aliases, forwarding wrappers, or deprecated
+  compatibility packages for its former Go facade;
+- existing consumers may remain pinned to the final framework-bearing
+  Scriptorium tag until migrated; and
+- intermediate migration phases need not preserve source compatibility, but
+  each merged phase must be internally buildable and tested.
+
+Promptkit's first release will be `v0.1.0`. During the migration, incompatible
+Promptkit changes may advance its minor version until a stable `v1` contract is
+declared. The first slim Scriptorium release will advance the Scriptorium minor
+version beyond the final framework-bearing release. Normal semantic-versioning
+rules apply independently to both projects after the migration.
+
+Promptkit must be tagged before Scriptorium or another consumer publishes a
+release that depends on it. Release branches must use tagged module
+dependencies, not local replacements or unpublished revisions.
+
+### Local Development And Cross-Repository Coordination
+
+For coordinated local work, place both repositories in a temporary Go
+workspace or use an uncommitted module replacement. `go.work`,
+`go.work.sum`, and local filesystem `replace` directives must not be committed
+to release branches.
+
+Cross-repository changes follow this order:
+
+1. land and tag the required Promptkit capability;
+2. update Scriptorium and other consumers to that tag;
+3. run each repository's own CI and smoke checks; and
+4. release consumers only after the Promptkit tag is available.
+
+Migration coordination must confirm out-of-band repository creation, Promptkit
+tags, and downstream migrations before dependent work proceeds.
+Cross-repository changes are coordinated, not treated as atomic commits.
+
+### Documentation And Maintained Assets
+
+Each repository will maintain its own README, contributor guide, architecture,
+documentation, testing, release, and operations material appropriate to that
+project. Cross-project documents will link to the canonical owner rather than
+copy its contract.
+
+Existing documentation and maintained assets have these target owners:
+
+| Current material | Target owner |
+| --- | --- |
+| Current README and executable quickstart | Scriptorium; Promptkit creates its own framework orientation |
+| Public Go package and Go-consumer guidance | Promptkit |
+| Prompt, profile, schema, execution-setting, and framework credential reference | Promptkit |
+| OpenAI-compatible integration contract and framework internal documents | Promptkit |
+| CLI, HTTP API, subprocess, and Scriptorium operations contracts | Scriptorium |
+| Consumer interface overview | Scriptorium, revised to route Go consumers to Promptkit |
+| Application-configuration discovery, server settings, and adapter internals | Scriptorium |
+| Current internal overview and source documentation | Split into repository-local overviews; Promptkit owns framework sources and Scriptorium owns HTTP containment |
+| This ADR and cross-project migration records | Scriptorium |
+| `examples/go-library` | Promptkit |
+| `examples/config*.yml`, `examples/render-markdown-summary.sh`, and `examples/http-run.json` | Scriptorium |
+| Example prompts, profiles, schemas, and synthetic fixtures used by the executable examples | Scriptorium |
+| Embedded built-in profile assets | Promptkit |
+| Scriptorium release workflow and executable packaging | Scriptorium |
+| Repository-level license, ignore rules, agent guidance, and development policies | Each repository maintains its own applicable copy |
+
+Promptkit will create or retain its own minimal framework examples and test
+fixtures rather than making either repository's tests depend on the other's
+working tree. Scriptorium's framework-format documentation will become a short
+version-appropriate link to Promptkit, while its maintained executable examples
+remain self-contained.
+
+## Alternatives Considered
+
+- Keep the current combined repository and improve package naming. This avoids
+  migration work but retains release and ownership coupling between the
+  framework and executable.
+- Add Promptkit as a wrapper around the Scriptorium public package. This gives
+  consumers a new import path but leaves framework ownership and dependency
+  direction inverted.
+- Extract Promptkit while retaining a Scriptorium compatibility facade. This
+  reduces immediate consumer changes but creates a second public API surface
+  and prolongs duplicate maintenance.
+- Move all artifact reading into Promptkit. This would place HTTP containment,
+  byte limits, and deployment policy in the application-neutral framework.
+- Keep Promptkit and Scriptorium as separate modules in one repository. This
+  separates imports but not repository permissions, release workflows,
+  issue ownership, or independent project evolution.
+
+## Rationale
+
+A separate Promptkit project makes the reusable framework the direct owner of
+the API that downstream Go projects already consume. Keeping Scriptorium as a
+public-API consumer exercises the same boundary as other consumers and prevents
+its adapters from relying on framework internals.
+
+The selected split keeps transport and deployment policy close to the
+Scriptorium interfaces that expose it, while allowing Promptkit to remain
+useful to in-process consumers with different IO and security requirements.
+Explicit package, configuration, documentation, and asset ownership reduces
+ambiguity during extraction and after release.
+
+## Consequences
+
+- All Go consumers of the framework must change their import path.
+- Promptkit and Scriptorium gain independent issue, release, CI, policy, and
+  documentation lifecycles.
+- Scriptorium becomes a real downstream integration test of Promptkit's public
+  facade.
+- Framework changes that affect Scriptorium require tagged, ordered
+  cross-repository coordination.
+- Some current packages, especially artifact reading and defaults, must be
+  separated by responsibility rather than moved intact.
+- Scriptorium's current configuration and documentation references must be
+  split between application and framework owners.
+- Maintainers must inventory and migrate downstream consumers explicitly; no
+  compatibility facade will hide incomplete migration.
+- Until the split is implemented, the current repository structure and
+  contracts remain authoritative.

docs/api.md

@@ -0,0 +1,145 @@
+# HTTP API Reference
+
+This is the canonical public HTTP contract for Scriptorium.
+
+## Service And Route
+
+`POST /v1/runs` runs one prompt request and returns generated output,
+validation, and metadata. The service has no built-in authentication or
+authorization; deploy it behind appropriate network and authentication controls.
+
+The service address and HTTP limits are configured as described in the
+[configuration reference](config.md). `serve` invocation is defined in the
+[CLI reference](cli.md).
+
+Requests and responses are JSON objects. Requests are decoded as JSON regardless
+of their `Content-Type`; successful JSON responses use
+`Content-Type: application/json`. There are no query parameters.
+
+## Request Limits
+
+The configured request-body limit includes inline artifact bodies. The artifact
+limit applies to HTTP `file` inputs. The response limit applies to the encoded
+response, including the artifact body and optional raw output. A limit of zero
+disables that limit.
+
+A request body over its limit returns `413 request_too_large`; an oversized
+file input returns `413 artifact_too_large`; an oversized encoded response
+returns `413 response_too_large`.
+
+## `POST /v1/runs`
+
+### Request Body
+
+The maintained [request example](../examples/http-run.json) is a complete
+copyable shape. The smallest valid shape is:
+
+```json
+{
+  "prompt_id": "generic.markdown_summary",
+  "inputs": {
+    "transcript": {"type": "inline", "body": "Source text"}
+  }
+}
+```
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `prompt_id` | yes | Non-blank prompt ID. |
+| `prompt_version` | no | Prompt version filter. |
+| `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. |
+| `inputs` | yes | Non-empty object mapping input names to references. |
+| `vars` | no | Object mapping template-variable names to strings. |
+| `model` | no | Runtime model-override object. |
+| `include_raw_output` | no | Include `raw_model_output` when true. |
+
+An input reference has a required `type` of `file` or `inline`. A `file`
+reference requires `uri`; an `inline` reference requires `body`.
+
+HTTP file references require a configured artifact root. Relative paths resolve
+within that root. Absolute paths must be lexically within it; traversal outside
+it is rejected with `400 artifact_not_allowed`. This lexical check does not
+resolve symlinks: the operating system follows symlinks inside the root,
+including ones that target outside it. Keep the root narrow and inaccessible to
+untrusted writers.
+
+The optional `model` object accepts `endpoint`, `model`, `temperature`,
+`max_tokens`, `top_p`, `timeout_seconds`, `service_tier`,
+`reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and
+credential supply are defined by the [configuration reference](config.md).
+Explicit zero values for the numeric fields are overrides; zero
+`timeout_seconds` disables the per-generation deadline only, retaining the
+request context and configured transport cap. The timeout layers are defined in
+the [outbound integration contract](integrations/openai-compatible-chat.md#authentication-and-timeout).
+
+Raw API-key values are not accepted. `api_key` and any other unknown model
+field cause `400 invalid_json`.
+
+### Strict JSON
+
+Request decoding rejects malformed JSON, unknown fields at every request level,
+and trailing JSON tokens with `400 invalid_json`. A blank `prompt_id` or
+empty `inputs` object returns `400 invalid_request`.
+
+### Success Response
+
+A completed run returns `200 OK`, including when generated content fails its
+validation contract. The response contains:
+
+- `artifact`: `name`, `content_type`, `body`, `size`, `hash`, and
+  optional `uri`;
+- `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus
+  optional `errors` and `schema_path`;
+- `metadata`: run, prompt, rendered-prompt, profile, model, input-hash, usage,
+  timing, validation, and repair-attempt metadata; and
+- optional `raw_model_output` when requested.
+
+`metadata.model_params` has `endpoint`, `model`, `temperature`,
+`max_tokens`, `top_p`, and `timeout_seconds`, plus optional
+`service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`.
+`metadata.usage` always includes `prompt_tokens`, `completion_tokens`,
+`total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable
+cache usage is reported as zero.
+
+A validation failure has `validation.status: "failed"`, `is_valid: false`,
+and any available diagnostic errors, while still returning the artifact and
+metadata.
+
+## Error Responses
+
+Errors have this shape:
+
+```json
+{"error":{"code":"invalid_request","message":"prompt_id is required"}}
+```
+
+Messages are concise and do not expose wrapped internal causes.
+
+| Status | Code | Meaning |
+| --- | --- | --- |
+| `400` | `invalid_json` | Malformed JSON, unknown field, or trailing JSON. |
+| `400` | `invalid_request` | Missing or invalid request data or runtime override. |
+| `400` | `profile_required` | No profile ID and no prompt default profile. |
+| `400` | `prompt_load_failed` | Prompt definition failed to load. |
+| `400` | `profile_load_failed` | Profile failed to load. |
+| `400` | `artifact_not_allowed` | HTTP file input is disabled or outside the artifact root. |
+| `400` | `artifact_read_failed` | Input artifact is invalid or cannot be read. |
+| `400` | `prompt_render_failed` | Prompt template rendering failed. |
+| `400` | `api_key_env_missing` | The selected credential environment variable is unset or empty. |
+| `404` | `not_found` | Route does not exist. |
+| `404` | `prompt_not_found` | Prompt ID or version does not exist. |
+| `404` | `profile_not_found` | Profile ID does not exist. |
+| `405` | `method_not_allowed` | The route does not accept the method. |
+| `413` | `request_too_large` | Encoded request exceeds its limit. |
+| `413` | `artifact_too_large` | File input exceeds its limit. |
+| `413` | `response_too_large` | Encoded response exceeds its limit. |
+| `500` | `validation_runtime_failed` | Schema or validator runtime failure. |
+| `500` | `internal_error` | Unclassified server failure. |
+| `502` | `llm_failed` | Outbound model request failed. |
+
+## Retry And Idempotency
+
+Scriptorium provides no idempotency keys, pagination, caching headers, or rate
+limits. Clients may retry transport failures or `5xx` responses only when
+their workflow tolerates another model call: a retry can produce different
+output and incur another provider request.

docs/cli.md

@@ -1,5 +1,10 @@
 # CLI Reference
 
+This is the canonical contract for invoking Scriptorium. Configuration discovery,
+precedence, directories, profiles, and schemas are defined in the
+[configuration reference](config.md). The [HTTP API reference](api.md) owns
+service request and response behavior.
+
 ## Shortest Useful Command
 
 ```bash
@@ -10,148 +15,134 @@ go run ./cmd/scriptorium render \
   --input glossary=./examples/fixtures/glossary.yml
 ```
 
-`render` prepares and formats the prompt without calling an LLM.
+`render` prepares a request without calling an LLM.
 
-## Command Overview
+## Commands
 
-- `scriptorium run`: prepare prompt, call the configured LLM, write generated output, print a run summary.
-- `scriptorium render`: prepare prompt only; write prepared-run output as `text` or `json`.
+- `scriptorium run`: prepare a prompt, call the configured LLM, and write the
+  generated artifact.
+- `scriptorium render`: prepare a prompt and write prepared-run output.
 - `scriptorium serve`: start the HTTP server.
 
-Integration references:
+All commands accept `--config <path>` and reject positional arguments. An
+effective `prompt_dir` is required for every command. Supply it through the
+configuration contract or the command's `--prompt-dir` flag.
 
-- [HTTP contract](integrations/http-api.md)
-- [Narratio subprocess contract](integrations/narratio.md)
+## `scriptorium run`
 
-## Common Argument Rules
+```text
+scriptorium run [flags]
+```
 
-- `--config` is supported by `run`, `render`, and `serve`.
-- `run` and `render` require:
-  - `--prompt`
-  - at least one `--input`
-  - an effective `prompt_dir` and `profile_dir` (from flags or config)
-- `serve` requires an effective `prompt_dir` and `profile_dir` (from flags or config).
-- Positional arguments are rejected.
-- Prompt cache control is configured in prompt YAML (`messages[].cache_control`), not with CLI flags.
-- Provider-specific `reasoning_effort` and `extra_params` are configured in profile YAML or HTTP model overrides, not with CLI flags.
+Required flags:
 
-## Flag Reference
+| Flag | Meaning |
+| --- | --- |
+| `--prompt <id>` | Prompt ID to execute. |
+| `--input name=path` | Input file mapping; repeat or use comma-separated mappings. |
 
-### `scriptorium run`
+Optional flags:
 
-- `--config <path>`: app config file path.
-- `--prompt-dir <dir>`: prompt definition directory.
-- `--profile-dir <dir>`: profile definition directory.
-- `--schema-dir <dir>`: schema base directory for `json_schema` validation.
-- `--prompt <id>`: prompt ID to execute. Required.
-- `--prompt-id <id>`: deprecated alias for `--prompt`.
-- `--profile <id>`: explicit profile override.
-- `--profile-id <id>`: deprecated alias for `--profile`.
-- `--input name=path`: input mapping (repeatable, comma-separated accepted).
-- `--var name=value`: template variable mapping (repeatable, comma-separated accepted).
-- `--out <path>`: write artifact body to file instead of stdout.
-- `--llm-base-url <url>`: runtime endpoint override.
-- `--model <name>`: runtime model override.
-- `--api-key-env <name>`: runtime API key environment-variable name override.
-- `--temperature <float>`: runtime temperature override.
-- `--max-tokens <int>`: runtime max tokens override.
-- `--top-p <float>`: runtime top-p override.
-- `--timeout <duration>`: runtime timeout override (Go duration syntax, for example `30s`, `2m`).
+| Flag | Meaning |
+| --- | --- |
+| `--config <path>` | Application configuration file. |
+| `--prompt-dir <dir>` | Prompt-definition directory override. |
+| `--profile-dir <dir>` | Custom profile-directory override. |
+| `--schema-dir <dir>` | Schema base-directory override. |
+| `--profile <id>` | Execution-profile override. |
+| `--var name=value` | Template-variable mapping; repeat or use comma-separated mappings. |
+| `--out <path>` | Write generated content to this file instead of stdout. |
+| `--llm-base-url <url>` | Runtime endpoint override. |
+| `--model <name>` | Runtime model override. |
+| `--api-key-env <name>` | Runtime API-key environment-variable name override. |
+| `--temperature <float>` | Runtime temperature override. |
+| `--max-tokens <int>` | Runtime maximum-token override. |
+| `--top-p <float>` | Runtime top-p override. |
+| `--timeout <duration>` | Runtime timeout override using Go duration syntax. |
 
-Numeric runtime override flags are presence-aware:
+Deprecated aliases: `--prompt-id` for `--prompt`, and `--profile-id` for
+`--profile`.
 
-- omitted numeric flags preserve the selected profile/default value
-- explicit zero values override the selected profile/default value (`--temperature 0`, `--max-tokens 0`, `--top-p 0`, `--timeout 0s`)
+Omitted numeric runtime flags preserve the selected effective value; explicit
+zero values override it. `--timeout 0s` disables the per-generation deadline
+only; the caller context and configured transport cap remain active. CLI
+durations are converted to whole seconds by truncation toward zero, so any
+duration whose absolute value is below one second becomes an explicit
+zero-second override. The timeout layers are defined in the
+[outbound integration contract](integrations/openai-compatible-chat.md#authentication-and-timeout).
 
-### `scriptorium render`
+There is no raw API-key flag. Use `--api-key-env`.
 
-- Supports the same flags as `run`, except:
-  - no `--schema-dir` flag.
-- Adds:
-  - `--format text|json`: prepared-run output format.
+## `scriptorium render`
 
-Notes:
-- `render` still resolves profile and runtime settings.
-- `render` still validates that `api_key_env` exists if the selected profile or overrides require it.
+```text
+scriptorium render [flags]
+```
 
-### `scriptorium serve`
+`--prompt <id>` and at least one `--input name=path` are required. The
+following optional flags are supported: `--config`, `--prompt-dir`,
+`--profile-dir`, `--profile`, `--var`, `--out`, `--llm-base-url`,
+`--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`,
+`--timeout`, and `--format text|json`. Their meanings match the corresponding
+`run` flags; `--format` selects prepared-run output and otherwise uses
+`defaults.render_format`.
 
-- `--config <path>`: app config file path.
-- `--addr <listen-address>`: HTTP listen address.
-- `--prompt-dir <dir>`: prompt definition directory.
-- `--profile-dir <dir>`: profile definition directory.
-- `--schema-dir <dir>`: schema base directory for `json_schema` validation.
+The same deprecated aliases and numeric/timeout behavior as `run` apply.
+`render` does not accept `--schema-dir`; configure `schema_dir` through the
+configuration file. It resolves profiles and schemas as part of preparation but
+does not call an LLM.
 
-Notes:
-- `serve` does not accept runtime model override flags such as `--model` or `--llm-base-url`.
+## `scriptorium serve`
+
+```text
+scriptorium serve [flags]
+```
+
+Optional flags:
+
+| Flag | Meaning |
+| --- | --- |
+| `--config <path>` | Application configuration file. |
+| `--addr <listen-address>` | HTTP listen-address override. |
+| `--prompt-dir <dir>` | Prompt-definition directory override. |
+| `--profile-dir <dir>` | Custom profile-directory override. |
+| `--schema-dir <dir>` | Schema base-directory override. |
+| `--artifact-root <dir>` | Root for HTTP `file` input references. |
+| `--max-request-bytes <n>` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
+| `--max-artifact-bytes <n>` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
+| `--max-response-bytes <n>` | Maximum encoded HTTP response bytes; `0` disables the limit. |
+
+`serve` accepts no runtime model override flags. HTTP request fields, response
+schemas, and error codes are defined in the [HTTP API reference](api.md).
 
 ## Input And Variable Syntax
 
-- `--input name=path` maps prompt input names to local file paths.
-- `--var name=value` maps template variable names to values.
-- If a prompt defines `session_id: "{{ .session_id }}"`, pass the OpenRouter sticky-routing value with `--var session_id=<value>`.
-- Both flags can be repeated.
-- Both flags also support comma-separated batches, for example:
-  - `--input transcript=./t.md,glossary=./g.yml`
-  - `--var session_id=42,session_date=2026-05-04`
+`--input name=path` maps an input name to a local file; `--var name=value`
+maps a template variable to a string. Both flags can be repeated or contain
+comma-separated mappings. Values may contain `=` after the first separator.
+Empty names and values are rejected.
 
-## Output Behavior
+CLI inputs are file references. HTTP inline inputs are defined by the
+[HTTP API reference](api.md).
 
-`run`:
-- Writes generated artifact content to stdout by default.
-- Writes generated artifact content to `--out` when provided.
-- Prints run summary metadata to stderr on success.
-- Appends `cached_tokens=<n> cache_write_tokens=<n>` to the summary only when the provider reports non-zero cache usage.
-- Prints errors to stderr on failure.
+## Output And Exit Behavior
 
-`render`:
-- Writes prepared-run output to stdout by default.
-- Writes prepared-run output to `--out` when provided.
-- Does not print a success summary line.
+- `run` writes generated content to stdout, or to `--out` when supplied, and
+  writes a concise summary to stderr.
+- `render` writes prepared-run output to stdout, or to `--out` when supplied,
+  without a success summary.
+- `serve` writes startup and server errors to stderr.
 
-`serve`:
-- Logs startup and server errors to stderr.
+Exit statuses:
 
-## Exit Codes
+| Status | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Parse, configuration, loading, rendering, generation, output-write, or other runtime error. |
+| `2` | `run` generated and wrote output, but validation failed. |
 
-- `0`: success.
-- `1`: runtime/parse/config/load/render/generation/output-write error.
-- `2`: `run` completed, output was generated, but validation status is `failed`.
+## Workflows And Examples
 
-When `run` exits `2`, output may already be written to stdout or `--out`.
-
-## Common Workflows
-
-Render prompt inputs and template variables as JSON:
-
-```bash
-go run ./cmd/scriptorium render \
-  --config ./examples/config.yml \
-  --prompt generic.markdown_summary \
-  --input transcript=./examples/fixtures/transcript.md \
-  --input glossary=./examples/fixtures/glossary.yml \
-  --var session_date=2026-05-04 \
-  --format json
-```
-
-Run a prompt with profile override and file output:
-
-```bash
-go run ./cmd/scriptorium run \
-  --config ./examples/config.yml \
-  --prompt generic.markdown_summary \
-  --profile local-fast \
-  --input transcript=./examples/fixtures/transcript.md \
-  --input glossary=./examples/fixtures/glossary.yml \
-  --out ./summary.md
-```
-
-Start the HTTP server with explicit config:
-
-```bash
-go run ./cmd/scriptorium serve --config ./examples/config.yml
-```
-
-Copyable example script:
-
-- `examples/render-markdown-summary.sh`
+The [maintained render script](../examples/render-markdown-summary.sh) is a
+copyable render workflow. The [HTTP request example](../examples/http-run.json)
+is for a running `serve` process.

docs/config.md

@@ -1,270 +1,173 @@
 # Configuration Reference
 
-## Config Discovery And Precedence
+This is the canonical reference for Scriptorium application settings and the
+prompt, profile, and schema files those settings select. For command syntax,
+see the [CLI reference](cli.md); for HTTP request shapes, limits, and outcomes,
+see the [HTTP API reference](api.md).
 
-Application settings are loaded in this order:
+## Discovery And Precedence
 
-1. Built-in defaults
-2. `config.yml` values
-3. CLI overrides
+Application settings are resolved in this order:
 
-When `--config` is not provided, Scriptorium searches for config files in this order:
+1. built-in defaults;
+2. a configuration file; then
+3. CLI overrides.
 
-1. `/usr/local/etc/scriptorium/config.yml`
-2. `/etc/scriptorium/config.yml`
+When `--config` is omitted, Scriptorium searches
+`/usr/local/etc/scriptorium/config.yml` and then `/etc/scriptorium/config.yml`.
+If neither exists, it uses built-in defaults. An explicit `--config` path must
+exist and decode successfully.
 
-If neither file exists, Scriptorium continues with built-in defaults.
+The maintained [minimal configuration](../examples/config.yml) and
+[full configuration](../examples/config.full.yml) are copyable examples.
 
-When `--config <path>` is provided, that file is required.
+## Application Configuration File
 
-## Minimal App Config
+Configuration is strict YAML: unknown fields are rejected. Empty string values
+do not override a prior value. Raw API-key fields are not accepted.
 
-```yaml
-prompt_dir: ./examples/prompts
-profile_dir: ./examples/profiles
-```
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `prompt_dir` | unset | Directory containing prompt-definition YAML. `run`, `render`, and `serve` require an effective value. |
+| `profile_dir` | unset | Directory containing custom profile YAML. Built-in profiles remain available. |
+| `schema_dir` | `.` | Base directory for relative JSON Schema paths. |
+| `server.addr` | `:8080` | Address used by `serve`. |
+| `server.artifact_root` | unset | Root that enables HTTP `file` input references. |
+| `server.max_request_bytes` | `16777216` | Maximum encoded HTTP request body bytes; `0` disables the limit. |
+| `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
+| `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. |
+| `defaults.render_format` | `text` | Default `render` output format: `text` or `json`. |
 
-This is enough to use `run` and `render` when prompt/profile files are valid.
-
-## Production-Oriented App Config
-
-```yaml
-prompt_dir: /opt/scriptorium/prompts
-profile_dir: /opt/scriptorium/profiles
-schema_dir: /opt/scriptorium/schemas
-
-server:
-  addr: 127.0.0.1:8080
-
-defaults:
-  render_format: text
-```
-
-## App Config File (`config.yml`)
-
-Top-level fields:
-
-- `prompt_dir` (optional): default prompt definition directory.
-- `profile_dir` (optional): default profile definition directory.
-- `schema_dir` (optional): base directory for schema files used by `json_schema` validation.
-- `server.addr` (optional): default listen address for `serve`.
-- `defaults.render_format` (optional): default `render` output format (`text` or `json`).
-
-Built-in defaults:
-
-- `schema_dir`: `.`
-- `server.addr`: `:8080`
-- `defaults.render_format`: `text`
-
-Validation behavior:
-
-- Config decoding is strict; unknown YAML fields are rejected.
-- Raw API key fields are not supported in `config.yml`.
+The three size fields must be zero or greater. The HTTP contract defines how
+each limit is enforced and reported. `server.artifact_root` configures the
+deployment boundary; see the [HTTP API reference](api.md) for request-path and
+containment behavior, and [operations](operations.md) for deployment handling.
 
 ## Prompt Definition Files
 
-Prompt definitions are YAML files anywhere under `prompt_dir`, including nested subdirectories.
+Prompt definitions are strict YAML files anywhere below `prompt_dir`. A prompt
+is selected by its YAML `id`, not by file path; nested directories are only for
+organization. See [maintained prompt examples](../examples/prompts/).
 
-Subdirectories are organizational only. Callers still select prompts by the YAML `id`, not by file path. For example, `prompts/dnd/recap.yaml` may still declare `id: dnd.recap`, and callers use `--prompt dnd.recap`.
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `id` | yes | Prompt identifier. |
+| `version` | yes | Prompt version. |
+| `default_profile` | no | Profile used when a request omits a profile ID. |
+| `description` | no | Human-readable description. |
+| `session_id` | no | Go-template string rendered from request variables and sent to a compatible provider when non-empty. |
+| `inputs` | no | Declared input metadata. |
+| `messages` | yes | Chat-message templates. |
+| `output` | yes | Output format and validation contract. |
 
-Example:
+### Inputs And Messages
 
-```yaml
-id: generic.structured_events
-version: "1.0.0"
-default_profile: local-quality
-description: Produce structured event JSON from a transcript.
+Each `inputs` item has a required `name` and optional `required`,
+`content_type`, and `description` fields. Input names must be unique.
 
-inputs:
-  - name: transcript
-    required: true
-    content_type: text/markdown
-    description: Source transcript content
-  - name: glossary
-    required: false
-    content_type: text/yaml
-    description: Optional glossary context
+Each message has a required `role`, exactly one of `content` or `content_file`,
+and optional `cache_control`. A `content_file` path is relative to the prompt
+file. `cache_control.type` must be `ephemeral`; its optional `ttl` is `1h`.
 
-messages:
-  - role: system
-    content_file: ./generic.structured_events.system.md
-  - role: user
-    content_file: ./generic.structured_events.user.md
+`session_id` uses the same template variables as messages. Empty rendered
+values are omitted. A rendered value may contain at most 256 Unicode code
+points.
 
-output:
-  format: json
-  validation_mode: json_schema
-  schema_path: structured_events.schema.json
-  repair_attempts: 0
-```
+### Output Contract
 
-Field reference:
-
-- `id` (required): prompt identifier.
-- `version` (required): prompt version.
-- `default_profile` (optional): profile ID used when request does not provide `profile_id`.
-- `description` (optional): prompt description.
-- `session_id` (optional): Go-template string for OpenRouter sticky-routing `session_id`; rendered from request vars.
-- `inputs` (optional list): expected named inputs.
-- `messages` (required list): prompt message templates.
-- `output` (required object): output contract.
-
-`inputs[]` fields:
-
-- `name` (required)
-- `required` (optional, boolean)
-- `content_type` (optional metadata)
-- `description` (optional)
-
-`messages[]` fields:
-
-- `role` (required)
-- `content` or `content_file` (exactly one is required)
-- `cache_control` (optional object): provider prompt-cache metadata for this message
-
-Message rules:
-
-- Repeated roles are allowed.
-- `content_file` is resolved relative to the prompt YAML file location.
-- Nested prompt files keep the same relative `content_file` behavior; `./recap.user.md` next to `dnd/recap.yaml` resolves from `dnd/`.
-- Prompt decoding is strict; unknown YAML fields are rejected.
-- Duplicate prompt IDs are invalid. If multiple files declare the requested prompt ID, Scriptorium fails instead of choosing one.
-
-`messages[].cache_control` fields:
-
-- `type` (required when `cache_control` is present): currently only `ephemeral`.
-- `ttl` (optional): currently only `1h`; omitted from outbound requests when unset.
-
-Example cache-controlled message:
-
-```yaml
-messages:
-  - role: system
-    content_file: ./stable_context.md
-    cache_control:
-      type: ephemeral
-      ttl: 1h
-  - role: user
-    content: |
-      {{input "transcript"}}
-```
-
-Use cache control on stable reusable prompt content. Dynamic per-run inputs before the cache-controlled message change the provider cache key.
-
-Example prompt-level session ID:
-
-```yaml
-session_id: "{{ .session_id }}"
-```
-
-When configured, `session_id` is rendered with the same variable context as messages. The rendered value is trimmed, omitted when empty, and rejected if longer than 256 characters. CLI callers pass the value through `--var session_id=<value>`; HTTP callers pass it through `"vars": {"session_id": "<value>"}`.
-
-`output` fields:
-
-- `format` (required): `text`, `markdown`, or `json`.
-- `validation_mode` (required): `none`, `basic`, `json`, or `json_schema`.
-- `schema_path` (required when `validation_mode: json_schema`).
-- `repair_attempts` (required): integer `>= 0`.
-
-Repair behavior boundary:
-
-- `repair_attempts` is part of the prompt contract.
-- CLI and HTTP currently construct the runner without a repairer, so normal `run`/`serve` execution does not perform output repair attempts.
+| Field | Required | Values or behavior |
+| --- | --- | --- |
+| `format` | yes | `text`, `markdown`, or `json`. |
+| `validation_mode` | yes | `none`, `basic`, `json`, or `json_schema`. |
+| `schema_path` | for `json_schema` | Schema path, relative to `schema_dir` unless absolute. |
+| `repair_attempts` | no | Integer greater than or equal to `0`; omitted means `0`. |
 
 ## Profile Definition Files
 
-Execution profiles are YAML files anywhere under `profile_dir`, including nested subdirectories.
+Profiles are strict YAML files anywhere below `profile_dir`. A profile is
+selected by YAML `id`; nested directories are organizational. See the
+[maintained profile examples](../examples/profiles/).
 
-Subdirectories are organizational only. Callers still select profiles by the YAML `id`, not by file path. For example, `profiles/local/local-quality.yaml` may still declare `id: local-quality`, and callers use `--profile local-quality`.
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `id` | yes | Profile identifier. |
+| `endpoint` | yes | OpenAI-compatible base URL, including its API version path when needed. |
+| `model` | yes | Provider model name. |
+| `temperature` | no | Number from `0` through `2`. |
+| `max_tokens` | no | Integer zero or greater. |
+| `top_p` | no | Number from `0` through `1`. |
+| `timeout_seconds` | no | Per-generation-call deadline in whole seconds; integer zero or greater. |
+| `service_tier` | no | Non-empty provider-specific request tier. |
+| `reasoning_effort` | no | Non-empty provider-specific reasoning setting. |
+| `api_key_env` | no | Environment-variable name containing the API key. |
+| `extra_params` | no | JSON-compatible provider-specific outbound request fields. |
 
-Example:
+Execution defaults before profile and request overrides are `temperature: 0`,
+`max_tokens: 0`, `top_p: 1`, and `timeout_seconds: 600`. Profile numeric values
+merge by non-zero value. Request overrides preserve presence, so an explicit
+zero can override a profile value. For `timeout_seconds`, explicit request zero
+disables the generation deadline while retaining the caller context and the
+built-in client's transport cap. See the
+[OpenAI-compatible integration contract](integrations/openai-compatible-chat.md#authentication-and-timeout)
+for the complete timeout interaction.
 
-```yaml
-id: local-fast
-endpoint: http://localhost:8000/v1
-model: gpt-4o-mini
-temperature: 0.2
-max_tokens: 500
-top_p: 1.0
-timeout_seconds: 90
-api_key_env: SCRIPTORIUM_API_KEY
-service_tier: priority
-reasoning_effort: medium
-extra_params:
-  provider_route: primary
-  provider_options:
-    retry_budget: 2
-```
+Custom profiles take precedence over built-ins with the same ID. Invalid custom
+profiles are errors; they do not fall back to a built-in profile. Raw `api_key`
+is rejected. Use `api_key_env`, or the public Go package's request-scoped key
+mechanism described in the [package contract](consumers/pkg-scriptorium.md).
 
-Field reference:
+`extra_params` keys must be non-empty and cannot be `model`, `session_id`,
+`messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`,
+`reasoning_effort`, or `response_format`.
 
-- `id` (required)
-- `endpoint` (required)
-- `model` (required)
-- `temperature` (optional): range `0..2`
-- `max_tokens` (optional): `>= 0`
-- `top_p` (optional): range `0..1`
-- `timeout_seconds` (optional): `>= 0`
-- `service_tier` (optional): provider-specific request tier such as OpenRouter `flex` or `priority`
-- `reasoning_effort` (optional): serialized as top-level `reasoning_effort` in outbound chat-completions requests
-- `api_key_env` (optional)
-- `extra_params` (optional map): JSON-compatible provider-specific parameters. Values may be strings, numbers, booleans, objects, or arrays.
+### Built-In Profile Catalog
 
-Profile rules:
+Each embedded profile uses `OPENROUTER_API_KEY`.
 
-- Profile decoding is strict; unknown YAML fields are rejected.
-- Raw `api_key` is rejected; use `api_key_env`.
-- If `api_key_env` is set, that environment variable must be set when preparing/running.
-- Duplicate profile IDs are invalid. If multiple files declare the requested profile ID, Scriptorium fails instead of choosing one.
-- `extra_params` keys must not be empty and must not collide with reserved outbound request fields: `model`, `session_id`, `messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`, `reasoning_effort`, or `response_format`.
+| Provider | ID | Model |
+| --- | --- | --- |
+| aion-labs | `aion-2` | `aion-labs/aion-2.0` |
+| anthropic | `claude-fable-latest` | `~anthropic/claude-fable-latest` |
+| anthropic | `claude-haiku-latest` | `~anthropic/claude-haiku-latest` |
+| anthropic | `claude-opus-latest` | `~anthropic/claude-opus-latest` |
+| anthropic | `claude-sonnet-latest` | `~anthropic/claude-sonnet-latest` |
+| deepseek | `deepseek-3-2` | `deepseek/deepseek-v3.2` |
+| deepseek | `deepseek-4-flash` | `deepseek/deepseek-v4-flash` |
+| deepseek | `deepseek-4-pro` | `deepseek/deepseek-v4-pro` |
+| google | `gemini-2-flash` | `google/gemini-2.5-flash` |
+| google | `gemini-2-flash-lite` | `google/gemini-2.5-flash-lite` |
+| google | `gemini-2-pro` | `google/gemini-2.5-pro` |
+| google | `gemini-3-flash-lite` | `google/gemini-3.1-flash-lite` |
+| google | `gemini-flash-latest` | `~google/gemini-flash-latest` |
+| google | `gemini-pro-latest` | `~google/gemini-pro-latest` |
+| google | `gemma-4-31b` | `google/gemma-4-31b-it:exacto` |
+| minimax | `minimax-m2` | `minimax/minimax-m2.5` |
+| minimax | `minimax-m3` | `minimax/minimax-m3` |
+| mistral | `mistral-large-2512` | `mistralai/mistral-large-2512` |
+| mistral | `mistral-medium-3-5` | `mistralai/mistral-medium-3-5` |
+| mistral | `mistral-small-3` | `mistralai/mistral-small-3.2-24b-instruct` |
+| mistral | `mistral-small-4` | `mistralai/mistral-small-2603` |
+| nvidia | `nemotron-3-ultra` | `nvidia/nemotron-3-ultra-550b-a55b` |
+| openai | `gpt-5-mini` | `openai/gpt-5.4-mini` |
+| openai | `gpt-5-nano` | `openai/gpt-5.4-nano` |
 
-Current outbound request behavior:
+## Schemas
 
-- The OpenAI-compatible client currently serializes: `model`, optional `session_id`, `messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`, `reasoning_effort`, optional `response_format` for `json_schema` prompts, and `extra_params`.
-- `extra_params` are flattened into provider-specific top-level JSON request fields. They are not wrapped in an `extra_params` object on the outbound provider request.
-- Messages without `cache_control` serialize with string `content`.
-- Messages with `cache_control` serialize as a single text content-block array containing `cache_control`.
+Schemas are JSON files, normally below `schema_dir`. `json_schema` output
+requires a `schema_path`. Relative paths resolve from `schema_dir`; absolute
+paths are used directly. Referenced nested schemas use relative paths and are
+not discovered by basename. An unreadable or invalid schema is a runtime
+validation error; generated content that fails JSON or schema validation is a
+validation result.
 
-## Schema Behavior
+## Credentials
 
-Schemas are JSON files, typically in `schema_dir`.
+Keep secrets in environment variables. Store only an environment-variable name
+in `api_key_env`; do not place raw keys in configuration, prompt or profile
+files, CLI arguments, examples, or HTTP payloads.
 
-Rules:
+## Related References
 
-- `output.validation_mode: json_schema` requires `output.schema_path`.
-- Relative `schema_path` values resolve from `schema_dir`, including explicit nested paths such as `dnd/structured_events.schema.json`.
-- Absolute `schema_path` values are used directly.
-- Scriptorium does not recursively search schemas by basename; nested schemas must be referenced by their relative path.
-- Missing or invalid schema documents cause runtime validation errors.
-- Invalid generated JSON causes validation status `failed` (not a runtime error).
-
-Supported artifact reference types for request inputs are `file` and `inline`.
-
-## Secrets Handling
-
-- Keep secret values in environment variables.
-- Store only environment-variable names in profile `api_key_env`.
-- Do not put raw API keys in config, prompts, profiles, CLI flags, or HTTP request bodies.
-
-## Maintained Examples
-
-- App config: `examples/config.yml`
-- Prompt examples: `examples/prompts/`
-- Profile examples: `examples/profiles/`
-- Schema examples: `examples/schemas/`
-- Input fixtures: `examples/fixtures/`
-- Render example script: `examples/render-markdown-summary.sh`
-- HTTP request example: `examples/http-run.json`
-
-Example organizational layout:
-
-```text
-examples/prompts/dnd/recap.yaml
-examples/profiles/local/local-quality.yaml
-examples/schemas/dnd/structured_events.schema.json
-```
-
-## Integration References
-
-- [Inbound HTTP contract](integrations/http-api.md)
-- [Outbound OpenAI-compatible contract](integrations/openai-compatible-chat.md)
+- [CLI reference](cli.md)
+- [HTTP API reference](api.md)
+- [OpenAI-compatible outbound contract](integrations/openai-compatible-chat.md)

docs/consumers/api.md

@@ -0,0 +1,59 @@
+# Consumer Integration Overview
+
+This guide helps applications choose a Scriptorium interface and understand
+their responsibilities. The linked contracts own interface syntax and wire
+semantics.
+
+| Interface | Use when |
+| --- | --- |
+| Go package | The consumer is Go and needs typed requests, results, or an injected LLM client. |
+| CLI subprocess | The consumer needs process isolation or is not written in Go. |
+| HTTP API | The consumer needs a service boundary or remote access. |
+
+- Go package: [package contract](pkg-scriptorium.md)
+- CLI subprocess: [subprocess integration](../integrations/subprocess.md)
+- HTTP service: [HTTP API reference](../api.md)
+- Prompt, profile, schema, and credential configuration: [configuration reference](../config.md)
+
+## Minimal Go Use
+
+```go
+engine, err := scriptorium.NewEngine(scriptorium.Config{
+	PromptDir:  "./examples/prompts",
+	ProfileDir: "./examples/profiles",
+})
+if err != nil {
+	return err
+}
+
+prepared, err := engine.Prepare(ctx, scriptorium.RunRequest{
+	PromptID: "generic.markdown_summary",
+	Inputs: map[string]scriptorium.ArtifactRef{
+		"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
+	},
+})
+if err != nil {
+	return err
+}
+_ = prepared
+```
+
+For a maintained program, see
+[`examples/go-library/prepare`](../../examples/go-library/prepare).
+
+## Consumer Responsibilities
+
+Consumers are responsible for:
+
+- selecting and deploying prompt, profile, and schema assets;
+- supplying required inputs and template variables;
+- supplying credentials through the applicable interface;
+- protecting rendered prompts and generated artifacts as potentially sensitive;
+- deciding whether validation-failed output is usable; and
+- retrying only when another model call is acceptable.
+
+Scriptorium does not persist run state. A retry can produce different output and
+can incur another provider request. CLI exit behavior belongs to the
+[CLI reference](../cli.md); HTTP status behavior belongs to the
+[HTTP API reference](../api.md); package errors and results belong to the
+[package contract](pkg-scriptorium.md).

docs/consumers/pkg-scriptorium.md

@@ -0,0 +1,203 @@
+# Package `scriptorium`
+
+Import path:
+
+```go
+import "gitea.maximumdirect.net/eric/scriptorium"
+```
+
+This is the canonical public Go contract for in-process prompt preparation and
+execution. Prompt, profile, and schema file formats are defined in the
+[configuration reference](../config.md).
+
+## Engine Construction
+
+`NewEngine(Config, ...Option)` constructs an engine. `Config` has these
+fields:
+
+| Field | Meaning |
+| --- | --- |
+| `PromptDir` | Prompt-definition directory, required unless a prompt source option is supplied. |
+| `ProfileDir` | Optional custom profile directory over built-ins. |
+| `SchemaDir` | Schema directory; empty uses `.`. |
+| `Timeout` | Transport-wide safety cap for the built-in OpenAI-compatible client when `HTTPClient` is absent or has a non-positive timeout. A non-positive value uses the internal ten-minute default. |
+| `HTTPClient` | Optional HTTP client for that built-in client. It is cloned; a positive `Timeout` on it is the transport cap and takes precedence over `Config.Timeout`. A non-positive client timeout is treated as unset. |
+
+Nil options are ignored. Invalid construction, including
+`WithLLMClient(nil)` and `WithArtifactReader(nil)`, returns an error matching
+`ErrInvalidConfig`.
+
+Profile and request `timeout_seconds` values select a per-generation-call
+deadline independently of the transport cap. An explicit request override of
+zero disables that generation deadline only. The complete interaction with the
+caller context is defined in the
+[OpenAI-compatible integration contract](../integrations/openai-compatible-chat.md#authentication-and-timeout).
+
+Source options replace their matching directory source:
+
+- prompts: `WithPromptFS(fsys, root)`, `WithPromptFile(path)`;
+- profiles: `WithProfileFS(fsys, root)`, `WithProfileFile(path)`, and
+  `WithProfiles(profiles...)`;
+- schemas: `WithSchemaFS(fsys, root)`, `WithSchemaFile(path)`; and
+- LLM client: `WithLLMClient(client)`; and
+- artifact reader: `WithArtifactReader(reader)`.
+
+`fs.FS` prompt-content and schema paths stay inside their configured roots.
+Single-file prompt and profile sources are selected by their YAML `id`, not
+their file names. `WithPromptFile` resolves relative `content_file` paths from
+the prompt file's directory. `WithSchemaFile` exposes its schema by the schema
+file's base name. In-memory profiles take precedence over an explicit or
+directory-backed profile source, which in turn takes precedence over built-ins.
+File and filesystem sources use the format and credential rules in the
+[configuration reference](../config.md).
+
+## Prepare And Run
+
+`Prepare(ctx, request)` resolves the prompt, profile, input artifacts,
+validation contract, and rendered messages without calling an LLM.
+`Run(ctx, request)` performs that preparation, calls the configured client,
+and validates generated content.
+
+```go
+engine, err := scriptorium.NewEngine(scriptorium.Config{
+	PromptDir:  "./examples/prompts",
+	ProfileDir: "./examples/profiles",
+})
+if err != nil {
+	return err
+}
+
+prepared, err := engine.Prepare(ctx, scriptorium.RunRequest{
+	PromptID: "generic.markdown_summary",
+	Inputs: map[string]scriptorium.ArtifactRef{
+		"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
+	},
+})
+if err != nil {
+	return err
+}
+_ = prepared.Messages
+```
+
+The maintained package example is
+[`examples/go-library/prepare`](../../examples/go-library/prepare).
+
+`PreparedRun` exposes prompt, selected-profile, effective-model, output
+contract, structured-output, input-hash, rendered-message, and timing
+information. It does not include a resolved API key, model output, validation
+result, or target-presence metadata.
+
+`RunResult` adds run ID, artifact, raw output, validation, model metadata,
+usage, and duration. Generated-content validation failures return a result with
+`Validation.Status == ValidationFailed`; schema or validator runtime failures
+return an error matching `ErrValidation`.
+
+## Public Values
+
+`ArtifactRef` has `Type`, `URI`, and `Body`; `Artifact` has `Name`,
+`ContentType`, `Body`, `URI`, `Size`, and `Hash`. `ExecutionTarget` exposes the
+effective endpoint, model, numeric settings, credential-environment name,
+service tier, reasoning effort, and extra parameters. `ValidationResult`
+contains status, mode, errors, schema path, repair attempts, and validity.
+
+The exported constants define these serialized values:
+
+- artifact types: `inline` and `file`;
+- output formats: `text`, `markdown`, and `json`;
+- validation modes: `none`, `basic`, `json`, and `json_schema`; and
+- validation statuses: `passed`, `failed`, and `skipped`.
+
+`TokenUsage` reports prompt, completion, total, cached, and cache-write token
+counts. `RenderedPrompt`, `RenderedMessage`, `CacheControl`, and
+`StructuredOutputSpec` are the public shapes used by injected LLM clients.
+
+`ArtifactReader` implements
+`Read(context.Context, ArtifactRef) (*Artifact, error)`. Supplying it through
+`WithArtifactReader` replaces, rather than extends, the engine's default inline
+and file reader for every input. Omitting the option retains that default;
+`WithArtifactReader(nil)` makes engine construction fail with
+`ErrInvalidConfig`.
+
+Reader failures are surfaced as errors matching `ErrArtifactLoad` while
+preserving the reader's original error identity for `errors.Is`. A `(nil, nil)`
+reader response is also an artifact-load failure. Readers are responsible for
+artifact metadata, although the engine assigns the input-map name when the
+returned name is empty; readers should not retain or mutate caller values.
+
+## Requests, Inputs, And Overrides
+
+`RunRequest` fields are `PromptID`, `PromptVersion`, `ProfileID`,
+`APIKey`, `Inputs`, `Vars`, `Execution`, `Validation`, and
+`Metadata`.
+
+Input helpers are:
+
+- `File(path)` for a file-backed artifact;
+- `Inline(body)` for inline content; and
+- `InlineWithURI(uri, body)` for inline content with URI metadata.
+
+Required declared inputs must be supplied. Template rendering must also resolve
+every input name the prompt actually references. Extra entries in `Inputs`
+are not rejected solely because they are undeclared.
+
+`ExecutionTargetOverride` supplies endpoint, model, credential-environment,
+service-tier, reasoning-effort, and extra-parameter overrides. Its numeric
+fields (`Temperature`, `MaxTokens`, `TopP`, and `TimeoutSeconds`) are
+pointers so explicit zero values are preserved. `OutputContract` supplies
+`Format`, `ValidationMode`, `SchemaPath`, and `RepairAttempts`.
+
+`ExtraParams` accepts JSON-compatible values: strings, booleans, finite
+numbers, objects with string keys, arrays or slices, and nil. Unsupported
+values, non-string map keys, non-finite floats, and cycles return
+`ErrInvalidConfig` for profiles or `ErrInvalidRequest` for request
+overrides.
+
+## Profiles And Credentials
+
+`OpenAICompatibleProfile(OpenAICompatibleProfileConfig)` creates an
+in-memory `Profile`. Its public fields are `ID`, `Endpoint`, `Model`,
+`Temperature`, `MaxTokens`, `TopP`, `TimeoutSeconds`, `ServiceTier`,
+`ReasoningEffort`, `APIKeyRequired`, and `ExtraParams`.
+`WithProfiles` rejects duplicate IDs in one call.
+
+A direct `RunRequest.APIKey` is request-scoped and takes precedence over
+`api_key_env` for the built-in client. It is excluded from JSON output and
+from `PreparedRun` and `RunResult`. The package's `String` and
+`GoString` methods report only whether a direct key is set. Do not use
+reflection-based dumps of request structs, which can bypass that redaction.
+
+## Injected LLM Clients
+
+`LLMClient` implements:
+
+```go
+Generate(context.Context, GenerateRequest) (*GenerateResponse, error)
+```
+
+Injected clients receive the rendered prompt, effective execution target, numeric
+target-presence metadata, optional structured-output specification, and direct
+request API key. `GenerateResponse` returns content and `TokenUsage`.
+Custom clients should avoid logging raw prompts or credentials.
+
+## Errors
+
+Public methods preserve these sentinel checks through `errors.Is`:
+
+- `ErrInvalidConfig`
+- `ErrInvalidRequest`
+- `ErrPromptNotFound`
+- `ErrProfileNotFound`
+- `ErrProfileRequired`
+- `ErrPromptLoad`
+- `ErrProfileLoad`
+- `ErrAPIKeyEnvMissing`
+- `ErrArtifactLoad`
+- `ErrPromptRender`
+- `ErrLLMGenerate`
+- `ErrValidation`
+
+`ErrProfileRequired` and `ErrAPIKeyEnvMissing` each also match
+`ErrInvalidRequest`, so callers can select either the broad request category or
+the specific condition.
+
+For the HTTP interface, see the [HTTP API reference](../api.md).

docs/development.md

@@ -0,0 +1,63 @@
+# Development
+
+This is the contributor entry point for Scriptorium. Use the task-specific
+reading guide below before making changes. Canonical architecture, contracts,
+component behavior, and policies remain in their owning documents.
+
+## Initial Orientation
+
+Before starting work:
+
+1. inspect the working tree and preserve unrelated changes;
+2. read the architecture policy for code or design work;
+3. read the policy, contract, and internal documents listed for the task;
+4. inspect the relevant implementation and tests before deciding how to change
+   them.
+
+Start with:
+
+- [Architecture policy](policy/architecture.md) for system boundaries,
+  invariants, and non-goals;
+- [Internal component overview](internal/overview.md) for the current package
+  and component map;
+- [Documentation policy](policy/documentation.md) before changing
+  documentation;
+- [Testing policy](policy/testing.md) before adding, rewriting, or deleting
+  tests.
+
+## Task-Specific Reading Guide
+
+| Task | Read before changing |
+| --- | --- |
+| Repository orientation or component responsibility | [Internal component overview](internal/overview.md) and [architecture policy](policy/architecture.md) |
+| Public Go package or engine behavior | [Go package consumer contract](consumers/pkg-scriptorium.md), [internal component overview](internal/overview.md), [runner internals](internal/runner.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
+| CLI commands, flags, output, or exit behavior | [CLI contract](cli.md), [internal component overview](internal/overview.md), and [adapter internals](internal/adapters.md) |
+| HTTP routes, DTOs, limits, or status mapping | [HTTP API contract](api.md), [internal component overview](internal/overview.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
+| Application configuration | [Configuration contract](config.md), [internal component overview](internal/overview.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
+| Prompt, profile, schema, or artifact loading | [Configuration contract](config.md), [internal component overview](internal/overview.md), and [source internals](internal/sources.md) |
+| Runner orchestration, rendering, validation, or repair | [Runner internals](internal/runner.md) and [source internals](internal/sources.md) |
+| OpenAI-compatible request or response behavior | [OpenAI-compatible integration](integrations/openai-compatible-chat.md), [LLM internals](internal/llm.md), [runner internals](internal/runner.md), and [adapter internals](internal/adapters.md) |
+| Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) |
+| Runtime operation or recovery | [Operations](operations.md) |
+| Examples or copyable assets | The owning contract for the demonstrated behavior and the related files under `examples/` |
+| Architecture decisions or future work | The [documentation policy](policy/documentation.md), relevant accepted ADRs such as [ADR 0001](adr/0001-adopt-canonical-documentation-ownership.md), and relevant roadmap documents under `roadmap/` |
+
+For cross-cutting changes, follow every applicable row. Internal component
+documents own detailed subsystem change recipes.
+
+## Baseline Validation
+
+Use focused checks while iterating, then run validation proportionate to the
+change and the risks described by the testing policy.
+
+The repository-level baseline for code changes is:
+
+```bash
+go test ./...
+go vet ./...
+go build ./cmd/scriptorium
+```
+
+Documentation-only work does not require the full Go suite unless it changes
+commands, examples, generated output, or another behavior that the suite
+validates. Always check changed links, paths, examples, and canonical ownership.

docs/integrations/http-api.md

@@ -1,210 +0,0 @@
-# HTTP API Integration
-
-## Scope
-
-This document defines the implemented inbound HTTP contract for Scriptorium.
-
-Current scope is only:
-
-- `POST /v1/runs`
-
-For CLI behavior, see the [CLI reference](../cli.md).
-
-## Endpoint
-
-- Method: `POST`
-- Path: `/v1/runs`
-- Content type: JSON request/response
-
-Route behavior:
-
-- unknown path: `404 not_found`
-- unsupported method on `/v1/runs`: `405 method_not_allowed`
-
-Copyable request example file:
-
-- `examples/http-run.json`
-
-## Request Body
-
-```json
-{
-  "prompt_id": "generic.structured_events",
-  "profile_id": "local-quality",
-  "prompt_version": "1.0.0",
-  "inputs": {
-    "transcript": {"type": "file", "uri": "./examples/fixtures/transcript.md"},
-    "glossary": {"type": "inline", "body": "party:\n  - Rin"}
-  },
-  "vars": {
-    "session_date": "2026-05-04"
-  },
-  "model": {
-    "endpoint": "http://localhost:8000/v1",
-    "model": "gpt-4o-mini",
-    "temperature": 0.0,
-    "max_tokens": 800,
-    "top_p": 1.0,
-    "timeout_seconds": 120,
-    "service_tier": "priority",
-    "reasoning_effort": "medium",
-    "api_key_env": "SCRIPTORIUM_API_KEY",
-    "extra_params": {
-      "route": "primary",
-      "provider_options": {
-        "retry_budget": 2
-      }
-    }
-  },
-  "include_raw_output": false
-}
-```
-
-Required fields:
-
-- `prompt_id`
-- `inputs` (must contain at least one named input)
-
-Input reference types currently supported by runtime artifact loading:
-
-- `file`
-- `inline`
-
-Model override notes:
-
-- Numeric model override fields distinguish omitted values from explicit zero values. For example, omitting `temperature` preserves the selected profile/default value, while `"temperature": 0` explicitly sets the effective temperature to zero.
-- `extra_params` accepts JSON-compatible values: strings, numbers, booleans, objects, and arrays.
-- `extra_params` are passed through effective model metadata and flattened into top-level provider request fields by the OpenAI-compatible client.
-- `extra_params` keys must not be empty and must not collide with reserved outbound fields: `model`, `session_id`, `messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`, `reasoning_effort`, or `response_format`.
-- Raw API-key values are not accepted. Use `api_key_env` to name an environment variable.
-
-## Strict JSON Rules
-
-Request decoding uses strict JSON field checks:
-
-- unknown request fields are rejected with `400 invalid_json`
-- unknown `model` fields are rejected with `400 invalid_json`
-- raw API-key payload fields such as `api_key` are rejected as unknown fields
-
-## Success Response
-
-Status: `200 OK`
-
-Response shape:
-
-```json
-{
-  "artifact": {
-    "name": "output",
-    "content_type": "application/json",
-    "body": "{\"summary\":\"...\"}",
-    "uri": "",
-    "size": 123,
-    "hash": "..."
-  },
-  "validation": {
-    "status": "passed",
-    "mode": "json_schema",
-    "errors": [],
-    "schema_path": "structured_events.schema.json",
-    "repair_attempts": 0,
-    "is_valid": true
-  },
-  "metadata": {
-    "run_id": "...",
-    "prompt_id": "generic.structured_events",
-    "prompt_version": "1.0.0",
-    "prompt_hash": "...",
-    "rendered_prompt_hash": "...",
-    "selected_profile_id": "local-quality",
-    "model_name": "gpt-4o-mini",
-    "endpoint": "http://localhost:8000/v1",
-    "model_params": {
-      "endpoint": "http://localhost:8000/v1",
-      "model": "gpt-4o-mini",
-      "temperature": 0,
-      "max_tokens": 800,
-      "top_p": 1,
-      "timeout_seconds": 120,
-      "service_tier": "priority",
-      "reasoning_effort": "medium",
-      "api_key_env": "SCRIPTORIUM_API_KEY",
-      "extra_params": {
-        "route": "primary",
-        "provider_options": {
-          "retry_budget": 2
-        }
-      }
-    },
-    "input_hashes": {
-      "transcript": "..."
-    },
-    "usage": {
-      "prompt_tokens": 11,
-      "completion_tokens": 22,
-      "total_tokens": 33,
-      "cached_tokens": 0,
-      "cache_write_tokens": 0
-    },
-    "start_time": "2026-05-04T12:00:00Z",
-    "end_time": "2026-05-04T12:00:01Z",
-    "duration_ms": 1000,
-    "validation_mode": "json_schema",
-    "validation_status": "passed",
-    "repair_attempts_used": 0
-  }
-}
-```
-
-`raw_model_output` is omitted by default.
-
-`metadata.usage.cached_tokens` and `metadata.usage.cache_write_tokens` are always present as numbers. They are `0` when the provider omits compatible cache usage fields or reports no cache activity.
-
-To include it, send:
-
-- `"include_raw_output": true`
-
-## Validation Failure Behavior
-
-Validation content failures do not map to HTTP error status.
-
-Behavior:
-
-- status remains `200 OK`
-- `validation.status` is `failed`
-- validation errors are returned in `validation.errors`
-
-## Error Responses
-
-Error body shape:
-
-```json
-{
-  "error": {
-    "code": "invalid_request",
-    "message": "prompt_id is required"
-  }
-}
-```
-
-Current error mapping (non-exhaustive):
-
-- `400 invalid_json`: malformed JSON or unknown JSON fields
-- `400 invalid_request`: missing/invalid request fields
-- `400 profile_required`: no explicit `profile_id` and prompt has no `default_profile`
-- `400 prompt_load_failed`: prompt definition invalid/unloadable
-- `400 profile_load_failed`: profile invalid/unloadable
-- `400 artifact_read_failed`: input artifact loading failed
-- `400 prompt_render_failed`: template render failed
-- `400 api_key_env_missing`: named API-key environment variable is missing
-- `404 prompt_not_found`
-- `404 profile_not_found`
-- `502 llm_failed`: outbound model request failed
-- `500 validation_runtime_failed`: validator runtime/schema-load failure
-- `500 internal_error`
-
-## Security And Deployment Note
-
-The HTTP adapter has no built-in authentication or authorization.
-
-Deploy behind trusted controls (for example authenticated gateway/reverse proxy and network boundaries).

docs/integrations/narratio.md

@@ -1,114 +0,0 @@
-# Narratio Subprocess Integration
-
-## Purpose
-
-This document defines the supported subprocess contract for Narratio invoking Scriptorium through the public CLI.
-
-This is a CLI contract, not an internal Go package integration.
-
-## Supported Commands
-
-Narratio should invoke:
-
-- `scriptorium run`
-- `scriptorium render`
-
-Use `run` for generation.
-
-Use `render` for preflight/debug output without LLM execution.
-
-## Recommended Invocation Shapes
-
-Run:
-
-```bash
-scriptorium run \
-  --prompt <prompt_id> \
-  --input transcript=<path> \
-  --out <artifact_path>
-```
-
-Render:
-
-```bash
-scriptorium render \
-  --prompt <prompt_id> \
-  --input transcript=<path> \
-  --format json
-```
-
-Narratio may add:
-
-- `--config <path>`
-- `--profile <profile_id>`
-- repeatable `--input name=path`
-- repeatable `--var name=value`
-- runtime overrides when explicitly needed (`--model`, `--llm-base-url`, `--timeout`, etc.)
-
-## Config And Directory Behavior
-
-Narratio can rely on resolved app config or pass explicit paths.
-
-- default config search order:
-  1. `/usr/local/etc/scriptorium/config.yml`
-  2. `/etc/scriptorium/config.yml`
-- explicit `--config` requires file existence and valid syntax
-- CLI flags override config values
-
-## Profile Selection
-
-Profile selection follows runner behavior:
-
-1. explicit `--profile`
-2. prompt `default_profile`
-3. error if neither is available
-
-Narratio should treat prompt/profile IDs as deployment configuration, not hardcoded logic.
-
-## Input And Variable Contract
-
-- Inputs use repeated `--input name=path`.
-- Input names must match prompt definition input names.
-- Variables use repeated `--var name=value` for small metadata values.
-- Prefer file inputs for large content.
-
-## Environment Contract
-
-- Pass through required API-key environment variables referenced by `api_key_env`.
-- Never pass raw API keys via CLI arguments.
-- Keep subprocess environment scoped to required variables.
-
-## Output And Error Handling
-
-`run`:
-
-- stdout: artifact body unless `--out` is used
-- `--out`: writes artifact to file
-- stderr: success summary and errors
-
-`render`:
-
-- stdout: prepared-run output unless `--out` is used
-- stderr: errors
-
-Narratio should capture stdout and stderr separately.
-
-## Exit Status Contract
-
-- `0`: success
-- `1`: parse/config/load/render/generation/IO/runtime error
-- `2`: run completed but validation failed
-
-A `run` exit code `2` can still produce output (stdout or `--out`).
-
-## Security Notes
-
-- Treat generated artifacts and stderr logs as potentially sensitive.
-- Avoid logging full rendered prompts by default in production contexts.
-- Use controlled output paths and access controls for persisted artifacts.
-
-## Canonical References
-
-- CLI behavior: [CLI reference](../cli.md)
-- Config behavior: [Configuration reference](../config.md)
-- Operations and failure handling: [Operations guide](../operations.md), [Troubleshooting](../troubleshooting.md)

docs/integrations/openai-compatible-chat.md

@@ -1,118 +1,67 @@
 # OpenAI-Compatible Chat Integration
 
-## Scope
+This is the outbound wire contract for Scriptorium's OpenAI-compatible
+chat-completions client.
 
-This document defines the outbound LLM contract implemented by `internal/llm/openai_compatible_client.go`.
+## Endpoint And Method
 
-It documents only fields and behaviors currently serialized by code.
+Scriptorium uses the request endpoint override when present; otherwise it uses
+the configured client base URL. It removes a trailing slash and sends
+`POST /chat/completions`.
 
-## Endpoint Construction
+For example, `http://localhost:8000/v1` becomes
+`http://localhost:8000/v1/chat/completions`.
 
-Request endpoint is built as:
+## Request Payload
 
-1. choose base URL:
-   - `GenerateRequest.Target.Endpoint` if set
-   - otherwise client config `BaseURL`
-2. trim trailing slash
-3. append `/chat/completions`
+The payload always contains `model` and rendered `messages`. It additionally
+contains these fields when applicable:
 
-Example:
+| Field | Inclusion |
+| --- | --- |
+| `session_id` | Non-empty rendered prompt session ID. |
+| `temperature` | Non-zero effective value or an explicit zero override. |
+| `max_tokens` | Non-zero effective value or an explicit zero override. |
+| `top_p` | Non-zero effective value or an explicit zero override. |
+| `service_tier` | Any non-empty configured value. |
+| `reasoning_effort` | Any non-empty configured value. |
+| `response_format` | Structured output is requested. |
+| provider-specific fields | Flattened from `extra_params`. |
 
-- base URL: `http://localhost:8000/v1`
-- final URL: `http://localhost:8000/v1/chat/completions`
+`service_tier` and `reasoning_effort` are forwarded without a provider value
+catalog; the selected backend decides which values it supports.
 
-## Request Fields Sent
+`extra_params` are top-level JSON fields, not a nested object. Keys cannot be
+empty or collide with `model`, `session_id`, `messages`, `temperature`,
+`max_tokens`, `top_p`, `service_tier`, `reasoning_effort`, or
+`response_format`. Values must be JSON-serializable.
 
-Serialized JSON fields:
+A rendered `session_id` is sent as a top-level JSON field, not as a header.
+Empty values are omitted. The maximum length is 256 Unicode code points.
 
-- `model` (required after fallback resolution)
-- `session_id` (only when the rendered prompt includes a non-empty session ID)
-- `messages` (rendered prompt messages)
-- `temperature` (when non-zero, or when explicitly overridden to zero)
-- `max_tokens` (when non-zero, or when explicitly overridden to zero)
-- `top_p` (when non-zero, or when explicitly overridden to zero)
-- `service_tier` (only when non-empty)
-- `reasoning_effort` (only when non-empty)
-- `response_format` (only when structured output is provided)
-- profile/request `extra_params` as additional provider-specific top-level fields
-
-`service_tier` is provider-specific. OpenRouter currently documents request values such as `flex` and `priority`; Scriptorium forwards any non-empty configured value and lets the backend validate support.
-
-`reasoning_effort` is provider-specific. Scriptorium forwards any non-empty configured value as top-level `reasoning_effort` and lets the backend validate support.
-
-`extra_params` are flattened into the outbound JSON object. They are not wrapped in an `extra_params` object:
-
-```json
-{
-  "model": "gpt-4o-mini",
-  "messages": [
-    {
-      "role": "user",
-      "content": "rendered text"
-    }
-  ],
-  "provider_route": "primary",
-  "provider_options": {
-    "retry_budget": 2
-  }
-}
-```
-
-`extra_params` values must be JSON-compatible. Supported value shapes include strings, numbers, booleans, objects, and arrays.
-
-Reserved `extra_params` keys are rejected before the HTTP request is made:
-
-- `model`
-- `session_id`
-- `messages`
-- `temperature`
-- `max_tokens`
-- `top_p`
-- `service_tier`
-- `reasoning_effort`
-- `response_format`
-
-Empty `extra_params` keys and values that cannot be encoded as JSON are also rejected before the HTTP request is made.
-
-`session_id` is rendered from prompt YAML using request variables and serialized as a top-level JSON request field. Scriptorium does not send an `x-session-id` header. Empty rendered session IDs are omitted, and values longer than 256 characters are rejected before the HTTP request.
-
-Messages without prompt cache control serialize with string `content`:
+Messages without cache control use string `content`. A message with cache
+control uses one text block:
 
 ```json
 {
   "role": "system",
-  "content": "rendered text"
+  "content": [{
+    "type": "text",
+    "text": "rendered text",
+    "cache_control": {"type": "ephemeral", "ttl": "1h"}
+  }]
 }
 ```
 
-Messages with prompt cache control serialize as a single text content-block array:
-
-```json
-{
-  "role": "system",
-  "content": [
-    {
-      "type": "text",
-      "text": "rendered text",
-      "cache_control": {
-        "type": "ephemeral",
-        "ttl": "1h"
-      }
-    }
-  ]
-}
-```
-
-When cache-control `ttl` is unset in the prompt definition, `ttl` is omitted from the outbound payload.
-
-Structured output is currently `json_schema` only, serialized as:
+When the prompt omits cache-control `ttl`, the payload omits `ttl`.
+Structured JSON Schema output is sent as:
 
 ```json
 {
   "response_format": {
     "type": "json_schema",
     "json_schema": {
-      "name": "...",
+      "name": "schema name",
       "strict": true,
       "schema": {"type": "object"}
     }
@@ -120,69 +69,53 @@ Structured output is currently `json_schema` only, serialized as:
 }
 ```
 
-## Authentication Header
+## Authentication And Timeout
 
-If `Target.APIKeyEnv` is set:
+When a direct request API key is present, Scriptorium sends
+`Authorization: Bearer <key>` and does not read `api_key_env`. Otherwise, it
+resolves the configured non-empty `api_key_env` at request time and sends the
+same header. If neither mechanism supplies a key, it sends no
+`Authorization` header.
 
-- resolve environment variable value at request time
-- set `Authorization: Bearer <value>`
+The transport-wide safety cap is chosen at client construction. A positive
+timeout on a supplied `http.Client` takes precedence over a positive
+`Config.Timeout`; if neither is positive, the internal ten-minute default is
+used. The supplied client is cloned, and zero or negative timeout values are
+treated as unset.
 
-If the environment variable is unset/empty:
+Separately, a positive effective `timeout_seconds` creates a deadline for each
+outbound generation call. Its value follows the execution-setting hierarchy:
+an explicit request override, then a non-zero profile value, then the
+600-second framework default. An explicit request override of zero disables
+only this generation deadline. Negative values are rejected before a request
+is sent.
 
-- request fails before HTTP call (`ErrInvalidRequest`)
+The complete observable rule is that the earliest caller-context deadline,
+transport cap, or positive generation deadline terminates the call. Transport
+and cancellation failures retain the generation-error classification.
 
-If `Target.APIKeyEnv` is empty:
+## Response Subset And Failures
 
-- no `Authorization` header is sent
+A successful provider response must supply non-empty
+`choices[0].message.content`. Scriptorium reads these optional or required
+usage fields when present:
 
-## Timeout Behavior
-
-Base timeout comes from client configuration.
-
-Per-request override:
-
-- if `Target.TimeoutSeconds > 0`, use that value for request timeout
-- if `Target.TimeoutSeconds == 0` and the value came from an explicit request override, disable the HTTP client timeout
-- if `Target.TimeoutSeconds < 0`, request is rejected (`ErrInvalidRequest`)
-
-## Response Expectations
-
-Expected successful response shape (subset used):
-
-- `choices[0].message.content`
 - `usage.prompt_tokens`
 - `usage.completion_tokens`
 - `usage.total_tokens`
-- `usage.prompt_tokens_details.cached_tokens` (optional)
-- `usage.cache_write_tokens` (optional)
+- `usage.prompt_tokens_details.cached_tokens`
+- `usage.cache_write_tokens`
 
-Absent cache usage fields are treated as zero. Parsed cache usage is exposed through run results and adapter response surfaces as:
+Missing cache usage is reported as zero. Invalid JSON, an empty choices array,
+or empty first-choice content is a malformed provider response. Network and
+request-construction failures, non-2xx responses, and malformed responses fail
+the outbound call. Provider response bodies are not exposed by this client.
 
-- `cached_tokens`
-- `cache_write_tokens`
+The client does not implement built-in retries, tool calls, top-level
+`cache_control`, or multi-request payload modes.
 
-Malformed response conditions include:
+## Related References
 
-- invalid JSON
-- empty `choices`
-- empty `choices[0].message.content`
-
-Malformed responses return `ErrMalformedResponse`.
-
-## Error Handling
-
-- network/request-construction failures: `ErrRequestFailed`
-- non-2xx HTTP status: `ErrUnexpectedStatus` (includes status code and trimmed response body snippet)
-- malformed response shape/content: `ErrMalformedResponse`
-
-## Unsupported Or Non-Serialized Fields
-
-The client does not serialize top-level `cache_control`.
-
-No built-in retries, tool-calls, or multi-request payload modes are implemented in this client.
-
-## Relationship To Runner
-
-When prompt validation mode is `json_schema`, runner prepares a structured-output schema spec and passes it to the client as `StructuredOutput`.
-
-The client only serializes the provider request payload; it does not load schema files itself.
+Prompt schema preparation and runner orchestration are described in
+[runner internals](../internal/runner.md). Prompt and profile configuration is
+defined by the [configuration reference](../config.md).

docs/integrations/subprocess.md

@@ -0,0 +1,41 @@
+# Subprocess Integration
+
+This document covers process-boundary behavior for callers that invoke
+Scriptorium as a child process. Command syntax, flags, output, and exit codes
+are defined by the [CLI reference](../cli.md). Interface selection belongs in
+the [consumer integration overview](../consumers/api.md).
+
+## Process Contract
+
+Use `scriptorium render` when the caller needs prepared output without a model
+call, and `scriptorium run` for generation. Pass an explicit `--config` or
+make the configuration search paths available to the child process; configuration
+discovery, fields, profile selection, and credential mechanisms are defined in
+the [configuration reference](../config.md).
+
+Pass required API-key environment variables through the child environment. Do
+not place raw API keys in arguments. Keep the environment limited to the values
+needed for the selected profile.
+
+## Streams And Output Ownership
+
+Capture stdout and stderr separately. Stdout contains the requested artifact or
+prepared output unless the caller selects an output file; stderr contains
+summaries, diagnostics, and server messages. The exact destinations and status
+meanings are part of the [CLI reference](../cli.md), not a stable stderr data
+protocol.
+
+When using `--out`, the caller owns the output path, its permissions, and
+cleanup. Treat rendered prompts, generated artifacts, stdout, and stderr as
+potentially sensitive.
+
+## Cancellation And Recovery
+
+A CLI invocation performs one synchronous request and creates no durable run
+state. A supervising process that needs cancellation must terminate the child
+process according to its own process-management policy. A later invocation is a
+new request and can make another model call; there is no resume or checkpoint
+protocol.
+
+For deployment, filesystem permissions, and sensitive-artifact handling, see
+the [operations guide](../operations.md).

docs/internal/adapters.md

@@ -1,156 +1,116 @@
-# Adapter And Repository Internals
+# Adapter Internals
 
 ## Purpose
 
-This document describes implemented adapter/repository boundaries and their current behavior.
+Adapters translate external inputs into public engine requests and translate
+public results or errors back to their interface. They own IO and presentation
+mechanics; use-case decisions remain behind the root `scriptorium` facade.
 
-## Adapter Map
+External contracts are canonical in the [CLI reference](../cli.md), [HTTP API
+reference](../api.md), and [Go package contract](../consumers/pkg-scriptorium.md).
 
-- `internal/adapter/cli`: CLI command parsing, app wiring, stdout/stderr handling, exit codes.
-- `internal/adapter/http`: HTTP request/response mapping for `POST /v1/runs`.
-- `internal/promptdef`: filesystem prompt-definition repository.
-- `internal/profile`: filesystem execution-profile repository.
-- `internal/artifact`: input artifact reader.
-- `internal/prompt`: Go-template renderer.
-- `internal/llm`: OpenAI-compatible LLM client implementation.
-- `internal/validate`: output validator.
-- `internal/format`: prepared-run formatters for `render` output.
+## Components And Collaborators
 
-## Inputs And Outputs
+- `cmd/scriptorium` passes process arguments and streams to
+  `internal/adapter/cli`.
+- `internal/adapter/cli` parses commands, resolves application settings through
+  `internal/config`, constructs the public engine, and owns process output
+  handling.
+- `internal/adapter/http` decodes DTOs, maps them to public run requests,
+  calls its local public `Runner` interface, and maps public errors and results
+  to HTTP DTOs.
+- The root `scriptorium` package maps its public types and options to internal
+  collaborators and maps selected internal errors to public sentinels.
+- `internal/format` formats public prepared runs for the CLI.
 
-CLI adapter:
+## Wiring Flows
 
-- Input: process args, filesystem config/assets, environment.
-- Output: exit code, stdout artifact/prepared output, stderr summaries/errors.
-- `run` summaries include cache usage counters only when either parsed cache counter is non-zero.
+### CLI
 
-HTTP adapter:
+The CLI resolves configuration before constructing the public engine. `run`
+calls `Engine.Run` with a public request and `render` calls `Engine.Prepare`
+with the same request mapping. `serve` constructs the HTTP-owned restricted
+artifact reader, injects it with `WithArtifactReader`, passes the resulting
+engine directly to the HTTP handler, and starts the server.
 
-- Input: JSON request body (`runRequestDTO`).
-- Output: JSON success/error body with mapped status codes.
-- Success metadata includes token usage plus cache usage counters.
+Parser state records whether numeric runtime values were explicitly supplied.
+That presence is carried into `scriptorium.ExecutionTargetOverride`, allowing
+the engine to distinguish omitted values from explicit zero overrides.
 
-Filesystem repositories:
+### HTTP
 
-- Input: prompt/profile YAML files under configured directories.
-- Output: normalized domain definitions/profiles or typed errors.
+The handler first enforces transport limits, strict JSON decoding, and the
+minimal request shape. It maps DTO values to public types without deciding
+prompt selection, source behavior, or validation semantics. On success it maps
+the public result to the response DTO; on failure it uses `errors.Is` over
+public framework errors and HTTP-local artifact-policy errors to choose the
+public error mapping.
 
-Artifact reader:
+The [HTTP API reference](../api.md) owns the route, DTO schema, status codes,
+and externally observable limit behavior.
 
-- Input: `domain.ArtifactRef`.
-- Output: loaded `domain.Artifact`.
+### Public Go Facade
 
-LLM adapter:
+`NewEngine` applies public options, selects filesystem, `fs.FS`, single-file,
+or in-memory dependencies, and constructs a runner. The conversion functions
+copy maps and slices across the boundary so callers do not receive internal
+domain values. The facade maps selected internal errors to the public sentinel
+set and keeps direct request API keys out of public results.
 
-- Input: `domain.GenerateRequest`.
-- Output: `domain.GenerateResponse`.
+## Package-Local Guarantees
 
-Validator:
+- Adapters do not embed framework orchestration or source-loading decisions.
+- Configuration is resolved before adapter dependency composition.
+- CLI and HTTP consume the public engine without a repairer; a repairer remains
+  available only through explicit internal runner construction.
+- DTO conversion preserves explicit numeric-override presence.
+- Error mapping matches error identities, not error text.
+- No adapter creates durable run state; caller-selected output files are not
+  application state.
 
-- Input: artifact body + output contract.
-- Output: validation result or runtime validation error.
+## Failure And Verification Boundaries
 
-## Boundaries
+Keep external error payloads concise, preserve strict external decoding, and do
+not serialize resolved secret values. Validation content failures remain result
+state; runtime failures remain errors for the relevant adapter to map.
 
-- Adapters convert external representations to domain requests and back.
-- Use-case decisions remain in `internal/usecase`.
-- External dependency details stay scoped to adapter packages.
-
-## Config Fields Used
-
-Primary app settings consumed by adapters:
-
-- `prompt_dir`
-- `profile_dir`
-- `schema_dir`
-- `server.addr`
-- `defaults.render_format`
-
-Execution profile/request settings used through runner:
-
-- `endpoint`, `model`, `temperature`, `max_tokens`, `top_p`, `timeout_seconds`, `service_tier`, `api_key_env`, `reasoning_effort`, `extra_params`
-- CLI and HTTP request adapters preserve caller intent for numeric runtime overrides. Omitted values remain absent; explicit zero values are mapped as explicit overrides.
-- HTTP `extra_params` accepts JSON-compatible values and maps them to domain request overrides without provider-specific adapter logic.
-
-## External Dependencies
-
-- YAML decoding: `gopkg.in/yaml.v3` (strict known-fields mode in config/prompt/profile loaders).
-- JSON Schema validation: `github.com/santhosh-tekuri/jsonschema/v6`.
-- HTTP client/server: Go standard library.
-
-## Failure Behavior
-
-Strict decoding and input checks:
-
-- config/prompt/profile loaders reject unknown YAML fields.
-- prompt/profile repositories scan nested subdirectories recursively.
-- prompt/profile lookup uses YAML `id` values; subdirectory paths are organizational only.
-- duplicate prompt/profile IDs are invalid and fail instead of using first-match behavior.
-- HTTP DTO decoder rejects unknown JSON fields.
-- raw API key payload fields are rejected by strict decoding in profile/http paths.
-
-Artifact refs:
-
-- Supported reference types: `inline`, `file`.
-- Unsupported types return `ErrUnsupportedRefType`.
-
-LLM adapter:
-
-- endpoint appends `/chat/completions`.
-- rendered messages without cache control serialize with string `content`.
-- rendered messages with cache control serialize as one text content block with `cache_control`.
-- non-empty `reasoning_effort` serializes as a top-level provider request field.
-- `extra_params` flatten into provider-specific top-level JSON request fields.
-- reserved `extra_params` keys are rejected before the provider call: `model`, `session_id`, `messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`, `reasoning_effort`, and `response_format`.
-- empty `extra_params` keys and values that cannot be JSON-encoded are rejected before the provider call.
-- compatible cache usage response fields are parsed into domain token usage.
-- non-2xx responses map to request failure errors.
-- malformed responses (including missing/empty first choice content) are errors.
-
-Validator:
-
-- `basic`, `json`, `json_schema` content failures return `ValidationFailed` results.
-- schema load/compile/path failures are runtime errors.
-- schema lookup uses explicit `schema_path` values relative to `schema_dir`; it does not recursively search by basename.
-
-HTTP error mapping:
-
-- maps domain/use-case errors to stable HTTP code + error code/message.
-- distinguishes missing profile selection and missing `api_key_env` variable using stable use-case sentinel errors.
-- avoids returning internal wrapped-cause details in response payload.
-
-## CLI Adapter Semantics
-
-Implemented commands:
-
-- `run`
-- `render`
-- `serve`
-
-Behavior highlights:
-
-- `run` exit `2` indicates validation failed after generation.
-- `render` does not call the LLM.
-- `serve` exposes HTTP handler only; no built-in auth.
-- `render` supports `--format text|json`; `render` does not expose `--schema-dir`.
-- deprecated aliases `--prompt-id` and `--profile-id` are still accepted.
-
-## Tests To Inspect Before Changing
+Inspect focused tests when changing this area:
 
 - `internal/adapter/cli/run_test.go`
 - `internal/adapter/http/handler_test.go`
-- `internal/promptdef/repository_test.go`
-- `internal/profile/repository_test.go`
-- `internal/artifact/reader_test.go`
-- `internal/prompt/renderer_test.go`
-- `internal/llm/openai_compatible_client_test.go`
-- `internal/validate/standard_validator_test.go`
+- `engine_test.go`
 - `internal/format/prepared_run_test.go`
 
-## Architectural Invariants
+Run the affected adapter package tests and recheck the relevant canonical
+contract. The [testing policy](../policy/testing.md) owns global test
+sufficiency guidance.
 
-- Adapter packages do not own runner decision logic.
-- External request/response strictness is part of contract stability.
-- Prepared-render output never includes resolved API key values.
-- Outbound OpenAI-compatible request includes currently serialized first-class fields (`model`, optional `session_id`, `messages`, optional `temperature`, `max_tokens`, `top_p`, optional `service_tier`, optional `reasoning_effort`, optional `response_format`) plus validated `extra_params` flattened as provider-specific top-level fields.
-- Outbound cache control is message-level only; no top-level cache-control field is serialized.
+## Change Recipes
+
+### Application Configuration Fields
+
+1. Add the field to the relevant `internal/config` shape and default handling.
+2. Parse and validate it, then preserve configuration and CLI-override
+   precedence while wiring it through its consuming adapter.
+3. Add focused configuration and adapter tests for parsing, mapping, and
+   effective behavior.
+4. Update the [configuration contract](../config.md) and any affected external
+   contract.
+
+### CLI Flags
+
+1. Add the flag to the relevant parser in `internal/adapter/cli/run.go`.
+2. Keep command scope and application-configuration precedence intentional.
+3. Add or update parser and command tests in
+   `internal/adapter/cli/run_test.go`.
+4. Update the [CLI contract](../cli.md) and affected maintained examples.
+
+### Adapter Capabilities
+
+1. Define or reuse an adapter-local consumer interface with public facade
+   types when a test seam is needed.
+2. Implement translation and IO behavior without moving framework decisions out
+   of the public engine.
+3. Add focused mapping, parsing, and error-behavior tests.
+4. Update this document and the affected public or integration contract. Update
+   [source internals](sources.md) when source-loading behavior changes.

docs/internal/llm.md

@@ -0,0 +1,86 @@
+# LLM Internals
+
+## Purpose
+
+`internal/llm` defines the provider-neutral `Client` interface and the
+OpenAI-compatible client implementation. The [OpenAI-compatible integration
+contract](../integrations/openai-compatible-chat.md) owns the outbound HTTP wire
+format and protocol behavior.
+
+## Construction
+
+`NewOpenAICompatibleClient` validates a non-empty configured base URL, records
+an optional default model, and resolves one transport cap. A supplied client
+with a positive timeout supplies that cap; otherwise a positive configured
+timeout is used, then the internal default.
+
+When callers supply an `http.Client`, construction clones it rather than
+mutating the caller's instance. A supplied client with a zero or negative
+timeout receives the resolved transport cap in the clone. The client stores the
+trimmed base URL, default model, and cloned client.
+
+## Generate Flow
+
+`Generate` receives a `domain.GenerateRequest` from the runner:
+
+1. validate the effective timeout and choose the request endpoint;
+2. map the domain request to the internal wire-request representation;
+3. validate and flatten extra parameters and encode JSON;
+4. derive a child context when the effective generation timeout is positive,
+   then create the HTTP request with that context;
+5. prefer a direct API key, otherwise resolve the configured key environment
+   variable;
+6. execute with the construction-time HTTP client, reject non-success status
+   responses without returning
+   provider response bodies; and
+7. decode the response subset into `domain.GenerateResponse`.
+
+`openAIChatRequestFromGenerateRequest` is the conversion boundary for effective
+model defaults, explicit numeric-presence state, rendered messages, structured
+output, and session-ID validation. `openAIChatRequestPayload` protects reserved
+fields and JSON encoding before an HTTP call. The external payload shape is
+defined only in the [integration contract](../integrations/openai-compatible-chat.md).
+
+## Error Categories
+
+The package uses these internal sentinels:
+
+- `ErrInvalidConfig` for invalid client construction;
+- `ErrInvalidRequest` for invalid effective generation input;
+- `ErrRequestFailed` for request construction or transport failures;
+- `ErrUnexpectedStatus` for non-success HTTP responses; and
+- `ErrMalformedResponse` for invalid or incomplete successful-response data.
+
+The runner maps an invalid LLM request to its invalid-request category and
+other LLM failures to its generation category. Adapters then apply their public
+error contracts.
+
+## Package-Local Guarantees
+
+- The default-model fallback happens before wire encoding.
+- Per-generation timeout handling derives a request context; it never replaces
+  or mutates the configured HTTP client's transport cap.
+- Direct API keys take precedence over environment lookup within this client.
+- Provider response bodies are discarded for non-success status responses.
+- The client does not implement retries, tool calls, or a stateful session
+  store.
+
+## Verification And Change Recipe
+
+Inspect:
+
+- `internal/llm/openai_compatible_client_test.go`
+- `internal/usecase/runner_test.go`
+- `internal/adapter/http/handler_test.go`
+
+When changing the client:
+
+1. keep domain-to-wire mapping inside `internal/llm` and preserve the `Client`
+   interface;
+2. test construction, timeout selection, mapping, and error categorization;
+3. update the [OpenAI-compatible integration contract](../integrations/openai-compatible-chat.md)
+   for any observable wire or protocol change; and
+4. update [runner internals](runner.md) if the client boundary or structured
+   output handoff changes.
+
+The [testing policy](../policy/testing.md) owns global test sufficiency.

docs/internal/overview.md

@@ -0,0 +1,48 @@
+# Internal Component Overview
+
+## Purpose
+
+This is the inventory of Scriptorium's implemented components for contributors.
+The [architecture policy](../policy/architecture.md) owns normative boundaries
+and invariants; public behavior belongs in the linked contracts.
+
+## Public And Command Entrypoints
+
+| Component | Implemented responsibility | References |
+| --- | --- | --- |
+| Root package `scriptorium` | Public Go facade that constructs the engine, exposes request/result types and options, and maps internal errors. | [Go package contract](../consumers/pkg-scriptorium.md), [adapter internals](adapters.md) |
+| `cmd/scriptorium` | Process entrypoint that delegates command execution to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
+
+## Adapters, Domain, And Use Case
+
+| Component | Implemented responsibility | References |
+| --- | --- | --- |
+| `internal/adapter/cli` | Parses CLI commands, constructs the public engine from application settings, and handles process input and output. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
+| `internal/adapter/http` | Maps HTTP requests and responses through public engine values, maps public errors, and owns restricted HTTP artifact policy. | [HTTP API contract](../api.md), [adapter internals](adapters.md) |
+| `internal/domain` | Defines core request, result, output-contract, and LLM-boundary types. | [runner internals](runner.md) |
+| `internal/usecase` | Implements `Runner` preparation, execution, validation coordination, and the repairer boundary. | [runner internals](runner.md) |
+
+## Configuration And Sources
+
+| Component | Implemented responsibility | References |
+| --- | --- | --- |
+| `internal/config` | Loads application settings, applies defaults, and applies CLI overrides. | [configuration contract](../config.md), [adapter internals](adapters.md) |
+| `internal/defaults` | Holds compile-time default values used when application settings are resolved. | [configuration contract](../config.md) |
+| `internal/promptdef` | Loads prompt definitions from filesystem and `fs.FS` sources. | [configuration contract](../config.md), [source internals](sources.md) |
+| `internal/profile` | Loads filesystem and `fs.FS` execution profiles and combines profile repositories. | [configuration contract](../config.md), [source internals](sources.md) |
+| `internal/profile/builtin` | Provides embedded built-in execution profiles as a repository. | [configuration contract](../config.md), [source internals](sources.md) |
+| `internal/filecatalog` | Provides shared YAML discovery and source-root helpers. | [source internals](sources.md) |
+| `internal/artifact` | Provides the framework's ordinary inline and unrestricted file artifact reader. | [configuration contract](../config.md), [source internals](sources.md) |
+| `internal/prompt` | Renders prompt templates into messages. | [runner internals](runner.md) |
+
+## Formatting, Validation, And Model Access
+
+| Component | Implemented responsibility | References |
+| --- | --- | --- |
+| `internal/format` | Formats public prepared-run information for CLI output. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
+| `internal/validate` | Defines validation interfaces and provides standard filesystem and `fs.FS` schema validation. | [configuration contract](../config.md), [source internals](sources.md), [runner internals](runner.md) |
+| `internal/llm` | Defines the provider-neutral LLM client boundary and its OpenAI-compatible implementation. | [OpenAI-compatible integration](../integrations/openai-compatible-chat.md), [LLM internals](llm.md), [runner internals](runner.md) |
+
+Focused internal documents describe the components that have detailed
+orchestration, adapter, or source behavior. Package tests live alongside the
+implementation and are identified in those focused documents where relevant.

docs/internal/runner.md

@@ -2,165 +2,119 @@
 
 ## Purpose
 
-`internal/usecase.Runner` is the core use case orchestrator for prompt preparation and execution.
+`internal/usecase.Runner` is the prompt-execution orchestrator. It prepares
+domain requests, invokes an injected LLM client, validates output, and returns
+domain results. Transport parsing, response mapping, and public type conversion
+remain outside this package.
 
-It owns request validation, prompt/profile resolution, runtime-parameter merge, artifact loading, prompt rendering, structured-output setup, LLM invocation, output validation, and result metadata.
+The [configuration reference](../config.md) owns prompt, profile, schema, and
+runtime-setting definitions. Public error behavior is defined by the
+[HTTP API](../api.md) and [Go package](../consumers/pkg-scriptorium.md)
+contracts.
 
-## Inputs And Outputs
+## Dependencies And Construction
 
-Primary input type:
+`Runner` receives these collaborators:
 
-- `domain.RunRequest`
+- `promptdef.Repository`;
+- `profile.Repository`;
+- `artifact.Reader`;
+- `prompt.Renderer`;
+- `llm.Client`;
+- `validate.Validator`; and
+- an optional `OutputRepairer`.
 
-Primary output types:
-
-- `domain.PreparedRun` from `Prepare`
-- `domain.RunResult` from `Run`
-
-LLM boundary types:
-
-- `domain.GenerateRequest`
-- `domain.GenerateResponse`
-
-## Boundaries
-
-`Runner` coordinates the following interfaces:
-
-- `promptdef.Repository`
-- `profile.Repository`
-- `artifact.Reader`
-- `prompt.Renderer`
-- `llm.Client`
-- `validate.Validator`
-- optional `usecase.OutputRepairer`
-
-Transport concerns (CLI flags, HTTP DTO parsing, status-code mapping) stay outside runner.
-
-## Config Fields Used
-
-`Runner` does not read app config files directly.
-
-It receives fully constructed repositories/readers/validators from adapters. Effective behavior depends on adapter wiring, including:
-
-- prompt/profile directories
-- schema base directory
-- selected profile/runtime overrides in request
-
-## External Adapters Used
-
-`Runner` works with adapter implementations via interfaces. Current wiring from CLI/HTTP uses:
-
-- filesystem prompt/profile repositories
-- composite artifact reader
-- Go-template prompt renderer
-- OpenAI-compatible LLM client
-- standard validator
-
-## State And Resume Behavior
-
-`Runner` is stateless across requests.
-
-- No durable run-state storage.
-- No built-in resume/skip checkpoints.
-- Each `Run`/`Prepare` executes from request inputs and current repositories.
-
-## Failure Behavior
-
-Primary runner error classes:
-
-- `ErrInvalidRequest`: invalid run request envelope.
-- `ErrProfileRequired`: specific invalid-request reason when neither request `profile_id` nor prompt `default_profile` is available.
-- `ErrAPIKeyEnvMissing`: specific invalid-request reason when `api_key_env` is set but the named environment variable is unset/empty.
-- `ErrProfileLoad`: prompt/profile repository load failures.
-- `ErrArtifactLoad`: artifact read failures.
-- `ErrPromptRender`: template render failures.
-- `ErrLLMGenerate`: outbound model request failures.
-- `ErrValidation`: validation runtime failures (including structured-output schema load/compile failures).
-
-Reason sentinel behavior:
-
-- `ErrProfileRequired` and `ErrAPIKeyEnvMissing` are wrapped with `ErrInvalidRequest`.
-- Adapters can use `errors.Is` for stable reason mapping without matching runner prose.
-
-Validation content failures are not run errors:
-
-- `Run` can succeed with `Validation.Status == failed`.
-- CLI maps this to exit code `2`.
-- HTTP returns `200` with failed validation details.
+`NewRunner` constructs a runner without a repairer. `NewRunnerWithRepairer`
+accepts one explicitly. The public engine chooses concrete repositories and
+readers; executable adapters reach the runner only through that engine. The
+runner does not load application configuration.
 
 ## Prepare Flow
 
-`Prepare` performs:
+`Prepare` performs one deterministic preparation pass for a request:
 
-1. validate request basics (prompt ID present).
-2. load prompt definition by ID/version.
-3. select profile ID:
-   - explicit request profile ID
-   - prompt `default_profile`
-   - otherwise return an invalid request with `ErrProfileRequired`
-4. load execution profile.
-5. merge effective runtime target:
-   - built-in execution defaults
-   - selected profile values
-   - request overrides
-   - request numeric overrides are presence-aware, so omitted values preserve the current effective value and explicit zero values override it
-6. verify required `api_key_env` environment variable:
-   - missing/empty env value returns an invalid request with `ErrAPIKeyEnvMissing`
-   - only the environment-variable name is retained; secret value is never returned
-7. resolve output contract and structured-output schema payload when `json_schema` mode is active.
-8. read input artifacts.
-9. render prompt messages, including any normalized message cache-control metadata.
-10. compute prompt/input/render hashes and return `PreparedRun`.
+1. validate the prompt ID and load the prompt definition;
+2. hash the definition and select the explicit or default profile;
+3. load the profile and resolve effective execution settings;
+4. validate endpoint, model, and credential availability;
+5. resolve the output contract and, for JSON Schema output, load a structured
+   schema document before model execution;
+6. read and hash input artifacts;
+7. render messages and the session ID; and
+8. return a `PreparedRun` containing the effective state and rendered-prompt
+   hash.
 
-`rendered_prompt_hash` includes cache-control metadata when present because it affects the outbound provider request. Prompts without cache control keep the role/content hash behavior.
+Execution settings merge defaults, profile values, and a request override.
+Numeric override presence is retained so explicit zero values are not confused
+with omissions.
 
-`Prepare` does not call the LLM.
+## Run And Validation Flow
 
-Runtime target notes:
+`Run` creates a run ID and timestamps, then calls `Prepare` rather than
+duplicating preparation. It sends the prepared prompt, effective target,
+target-presence state, and optional structured-output specification to the LLM
+client. It converts the returned content to an output artifact, validates it,
+and returns the artifact, validation, hashes, usage, and timing metadata.
 
-- Profile `extra_params` and request `extra_params` carry JSON-compatible values through prepared output, run metadata, and `domain.GenerateRequest.Target`.
-- The OpenAI-compatible client serializes non-empty `reasoning_effort` as a top-level provider request field.
-- The OpenAI-compatible client flattens `extra_params` into provider-specific top-level JSON request fields.
-- Empty `extra_params` keys, reserved outbound field names, and values that cannot be JSON-encoded fail before the provider request.
-- Resolved API-key values are never stored in `PreparedRun`, `RunResult`, logs, or HTTP responses.
+A validator can return a content result or an operational error. Content
+failures stay in the result; schema loading, compilation, and validator
+operational failures are returned as `ErrValidation`. The canonical distinction
+for callers is documented by the public contracts.
 
-## Run Flow
+## Repair Boundary
 
-`Run` performs:
+Repair is an internal optional loop. It starts only when a repairer is present,
+the output contract permits one or more attempts, validation failed, and the
+validation mode is JSON or JSON Schema. Each repair receives the previous
+output, validation errors, effective target, structured-output specification,
+and attempt metadata; every repaired result is validated again.
 
-1. generate run ID.
-2. call `Prepare`.
-3. call LLM with prepared messages/effective target/structured-output spec.
-4. build output artifact content type from output format.
-5. validate output.
-6. optionally attempt bounded repair when repairer is injected and contract allows it.
-7. return `RunResult` with artifact, raw output, validation, hashes, profile/model metadata, token/cache usage, and timestamps.
+`NewDefaultOutputRepairer` delegates to the injected LLM client. The public
+engine, and therefore CLI and HTTP, uses `NewRunner` and does not inject this
+repairer.
 
-## Repair Hook Boundary
+## Error Translation
 
-Repair attempts occur only when all are true:
+Runner sentinels identify failure categories for adapters:
 
-- repairer is injected
-- `repair_attempts > 0`
-- validation status is `failed`
-- validation mode is `json` or `json_schema`
+- `ErrInvalidRequest`
+- `ErrProfileRequired`
+- `ErrAPIKeyEnvMissing` and `ErrAPIKeyRequired`
+- `ErrPromptLoad`, `ErrProfileLoad`, and `ErrArtifactLoad`
+- `ErrPromptRender`
+- `ErrLLMGenerate`
+- `ErrValidation`
 
-Current production wiring boundary:
+Wrap errors with those sentinels and preserve their identities through
+`errors.Is`; adapters must not classify errors by message text. The runner
+passes direct keys only to the LLM boundary and never includes resolved key
+values in prepared or run results.
 
-- CLI and HTTP adapters call `usecase.NewRunner(...)` (no repairer argument).
-- Therefore normal CLI/HTTP execution does not perform repair attempts today.
+## Package-Local Guarantees
 
-## Tests To Inspect Before Changing
+- `Run` always reuses `Prepare`.
+- Schema documents are loaded before the initial LLM call when structured output
+  is required.
+- Output validation records attempts used, including repair attempts.
+- Runner state is per request; the package does not create a durable run store
+  or manifest.
+- Source, renderer, validator, and LLM implementations remain injected
+  boundaries.
+
+## Verification And Change Recipe
+
+Inspect:
 
 - `internal/usecase/runner_test.go`
-- `internal/usecase/integration_test.go`
-- `internal/adapter/cli/run_test.go`
-- `internal/adapter/http/handler_test.go`
+- `engine_test.go`
 
-## Architectural Invariants
+When changing orchestration:
 
-- `Run` reuses `Prepare`; prepare logic is not duplicated.
-- Effective API-key environment-variable name may appear; resolved secret value must not.
-- Structured-output schema document must load before LLM call for `json_schema` mode.
-- Repair loops are bounded by `repair_attempts` and repairer presence.
-- Runner stays transport-agnostic.
+1. identify the collaborator boundary and the affected `Prepare` or `Run` state;
+2. preserve the `Run`-through-`Prepare` path and error identity;
+3. add focused runner or integration tests for changed state transitions,
+   validation, or repair behavior; and
+4. update the owning external contract and any affected source or LLM internal
+   document.
+
+The [testing policy](../policy/testing.md) owns global test sufficiency.

docs/internal/sources.md

@@ -0,0 +1,99 @@
+# Source Internals
+
+## Purpose
+
+This document describes how source packages load prompt definitions, profiles,
+schemas, and artifacts. The [configuration reference](../config.md) owns their
+user-facing formats and settings. The [HTTP API reference](../api.md) owns
+HTTP-visible artifact outcomes; [operations](../operations.md) owns deployment
+handling.
+
+## Prompt Definitions
+
+`internal/promptdef` provides filesystem and `fs.FS` repositories. Both use
+`internal/filecatalog` for recursive YAML discovery, deterministic ordering,
+display paths, and root cleaning.
+
+Repositories select a prompt by YAML ID and optional version rather than by
+path. They decode through strict YAML handling, reject duplicate matching
+definitions, and resolve `content_file` relative to the definition. The `fs.FS`
+implementation resolves content paths inside its source root; absolute paths and
+traversal outside that root are rejected before file access.
+
+## Profiles And Built-Ins
+
+`internal/profile` provides filesystem, `fs.FS`, and overlay repositories.
+`internal/profile/builtin` exposes embedded assets through the same repository
+interface.
+
+An overlay asks its primary source first. It falls back only when the primary
+reports `ErrProfileNotFound`; invalid YAML, duplicate IDs, validation failures,
+and raw-key failures are returned rather than hidden by fallback. This makes a
+custom ID override a built-in ID while retaining errors in the custom source.
+
+The public engine can overlay in-memory profiles ahead of both file-backed and
+built-in repositories. Profile field definitions, validation ranges, and the
+built-in catalog remain in the [configuration reference](../config.md).
+
+## Schemas
+
+`internal/validate` supplies `StandardValidator` for filesystem sources and
+`FSValidator` for `fs.FS` sources. Directory-backed validation loads the named
+schema path; it does not search directories by basename. `fs.FS` schema paths
+are cleaned and checked against their configured root, while a single-file
+source matches its file base name.
+
+The runner requests a schema document before generation when it needs
+structured output. JSON and schema mismatches in generated content are
+validation results; source access, decoding, registration, and compilation
+failures are operational errors.
+
+## Artifacts
+
+`internal/artifact` owns the framework's ordinary inline and unrestricted file
+reader. The public engine uses it by default and permits consumers to replace it
+for every input through the public `ArtifactReader` extension. The
+HTTP adapter owns its restricted reader for HTTP containment: `serve` injects
+that reader into the public engine with `WithArtifactReader`.
+
+The rooted reader cleans paths and applies lexical containment without resolving
+symlinks. It checks relative references against the configured root and accepts
+absolute references only when they remain inside that lexical root. The OS still
+follows symlinks after that check. The public containment outcome is documented
+by the [HTTP API reference](../api.md); deployment permissions belong in
+[operations](../operations.md).
+
+## Failure Boundaries
+
+Source packages report repository, decoding, duplicate, validation, and read
+failures to their callers. They do not select public status codes or response
+schemas. The runner categorizes source failures and the public engine preserves
+the corresponding public error identities; adapters map those identities to
+their own external contract.
+
+Source reads use current filesystem or `fs.FS` content for each request. These
+packages create no manifests, checkpoints, or durable run state.
+
+## Verification And Change Recipe
+
+Inspect:
+
+- `internal/promptdef/repository_test.go`
+- `internal/profile/repository_test.go`
+- `internal/profile/builtin/repository_test.go`
+- `internal/artifact/reader_test.go`
+- `internal/adapter/http/artifact_reader_test.go`
+- `internal/validate/standard_validator_test.go`
+- `engine_test.go`
+
+When updating prompt, profile, schema, or built-in assets:
+
+1. keep assets valid for the strict loader and the relevant source boundary;
+2. update the [configuration reference](../config.md) when a file-format,
+   catalog, or default changes;
+3. run focused source and integration tests, including the built-in repository
+   test when embedded assets change; and
+4. update this document when discovery, precedence, containment, or failure
+   mechanics change.
+
+The [testing policy](../policy/testing.md) owns global test sufficiency.

docs/operations.md

@@ -1,125 +1,157 @@
 # Operations Guide
 
-## Scope
+## Scope And References
 
-This document covers day-to-day operation of the CLI and HTTP service for currently implemented behavior.
+This runbook covers deployment, normal operation, capacity planning, and safe
+recovery for Scriptorium. It does not redefine invocation syntax, configuration
+fields, or HTTP wire behavior.
 
-For command syntax, see [CLI reference](cli.md). For file formats and defaults, see [Configuration reference](config.md).
+- [CLI reference](cli.md): commands, output destinations, and exit codes.
+- [Configuration reference](config.md): configuration, prompt/profile/schema
+  formats, defaults, and credentials.
+- [HTTP API reference](api.md): route, request/response schema, status codes,
+  limits, and HTTP artifact access.
+- [Consumer integration overview](consumers/api.md): caller responsibilities.
 
-## Operational Model
+## Operational Model And State
 
-Scriptorium executes one request at a time per CLI invocation or HTTP request.
+Scriptorium handles one prompt request for each CLI invocation or HTTP request.
+It has no durable run store, archive, checkpoint, cache, or resume mechanism.
+A failed or interrupted request is recovered by correcting its inputs,
+configuration, or environment and submitting a new request.
 
-Important boundaries:
+Generated artifacts, rendered prompts, model output, and run metadata are
+caller-owned data. Retention, encryption, backup, and deletion are deployment
+responsibilities.
 
-- No durable run state is stored.
-- No built-in resume, checkpoint, archive, or backup workflow exists.
-- Recovery is rerun-based: fix inputs/config, then rerun.
+## Deploy The Filesystem And Process
 
-## Filesystem Layout And Config
+Provide the process with readable prompt, profile, and schema sources. Keep
+prompt templates adjacent to the prompt definitions that reference them. For an
+HTTP deployment that accepts file artifacts, use a dedicated, narrow artifact
+directory rather than a general-purpose or sensitive filesystem tree.
 
-Scriptorium depends on:
+Run Scriptorium under an identity that can:
 
-- prompt definition files (`prompt_dir`)
-- execution profile files (`profile_dir`)
-- optional JSON schemas (`schema_dir`)
+- read only the prompt, profile, schema, and allowed input-artifact paths it
+  needs;
+- read the required credential environment variables without writing them to
+  files or logs; and
+- write only caller-selected output locations when CLI output files are used.
 
-Config discovery order when `--config` is omitted:
+Do not make the HTTP artifact directory writable by untrusted users. The HTTP
+artifact containment behavior is lexical and the operating system follows
+symlinks; account for that when choosing ownership and mount boundaries. See
+the [HTTP API reference](api.md) for the externally observable behavior.
 
-1. `/usr/local/etc/scriptorium/config.yml`
-2. `/etc/scriptorium/config.yml`
+## Supply Credentials And Protect Runtime Data
 
-If neither exists, built-in defaults are used. If `--config <path>` is provided, that file must exist and parse successfully.
+Set secret values in the process environment and configure only their
+environment-variable names. Do not put raw keys in configuration, prompt or
+profile files, process arguments, HTTP payloads, captured command lines, or
+debug dumps.
 
-Built-in defaults relevant to operations:
+Treat stdout, stderr, prepared-run output, generated artifacts, and HTTP
+responses as potentially sensitive. Send service logs to a controlled collector
+and apply the same retention and access rules as for model input and output.
 
-- `schema_dir: .`
-- `server.addr: :8080`
-- `defaults.render_format: text`
+## Run A Normal Workflow
 
-## Normal CLI Workflow
+Before changing production inputs, profiles, or schemas:
 
-Use `render` first when you need to verify prompt resolution and runtime settings without calling a model.
+1. confirm the deployed configuration selects the intended sources and model
+   credentials;
+2. use [`render`](cli.md) with the same request inputs and variables to confirm
+   preparation without a model call;
+3. use [`run`](cli.md) for generation; and
+4. retain or discard validation-failed output according to the caller's
+   policy.
 
-Use `run` for generation.
+The [maintained render script](../examples/render-markdown-summary.sh) is a
+copyable preflight example. The CLI reference owns its complete invocation and
+exit semantics.
 
-Typical sequence:
+## Expose The HTTP Service
 
-1. Confirm prompt/profile directories resolve through config or flags.
-2. Confirm required input files exist and map to prompt input names.
-3. Confirm required API-key environment variables are set.
-4. Confirm the selected profile's model endpoint is reachable from the process environment.
-5. Run `render` for preflight when changing prompt/profile/input wiring.
-6. Run `run` for actual generation.
+The HTTP service has no built-in authentication or authorization. Place it on a
+trusted network or behind an authenticated reverse proxy, API gateway, or
+equivalent access control. Restrict who can reach it and who can read the
+artifact root.
 
-## Secrets Handling
+Use a service manager or supervisor appropriate to the deployment to manage
+process lifetime, restart policy, log capture, and environment injection. The
+[HTTP API reference](api.md) owns client request shapes, status behavior, and
+artifact-access outcomes.
 
-Raw API keys are not accepted in config files, profile files as `api_key`, CLI flags, or HTTP request bodies.
+## Plan Capacity And Limits
 
-Operational pattern:
+Capacity is primarily determined by concurrent model calls, input and output
+sizes, schema complexity, provider latency, and network behavior. Size limits
+protect request bodies, HTTP file artifacts, and encoded responses; configure
+them through the [configuration reference](config.md) and rely on the
+[HTTP API reference](api.md) for their response effects.
 
-- Set environment variables that hold secret values.
-- Set profile `api_key_env` (or runtime override `api_key_env`) to the environment variable name.
-- Keep process environments scoped to only required variables.
+Before increasing a limit:
 
-## HTTP Service Operation
+1. measure representative input, generated-output, and optional raw-output
+   sizes;
+2. confirm memory, network, and upstream-provider capacity;
+3. retain an upstream request-size and authentication boundary; and
+4. test the intended workload in a non-production environment.
 
-Start service with:
+For large local inputs, prefer a controlled file-artifact directory over
+placing arbitrary paths on the service host. Avoid disabling a limit unless an
+equivalent trusted control exists elsewhere.
 
-```bash
-go run ./cmd/scriptorium serve --config ./examples/config.yml
-```
+## Diagnose And Recover
 
-Current inbound API behavior:
+### Preparation Or Configuration Failure
 
-- Route: `POST /v1/runs`
-- JSON request parsing rejects unknown fields.
-- Validation content failures still return `200 OK` with `validation.status: "failed"`.
+Capture the CLI diagnostic or HTTP error response, then verify the selected
+configuration, prompt ID, profile selection, source readability, and input
+mapping. Use `render` with the same request when it is unclear whether failure
+occurs before model execution. Consult the [CLI reference](cli.md), the
+[configuration reference](config.md), and the [HTTP API reference](api.md) for
+the exact interface contract.
 
-Security caveat:
+### Credential Or Provider Failure
 
-- `serve` has no built-in authentication or authorization.
-- Deploy only behind trusted controls (private network boundary, authenticated reverse proxy, API gateway, or equivalent).
+Confirm that the process environment contains the configured credential name
+without printing the secret. Check endpoint reachability and provider health
+from the process network. If preparation succeeds but generation fails, inspect
+the selected model settings in prepared output and the service's controlled
+logs. Correct the deployment or provider issue, then submit a new request.
 
-## Output, Logs, And Exit Codes
+### Artifact Or Permission Failure
 
-`run` command:
+Verify that the process can read the intended local input. For HTTP file
+artifacts, verify the deployment's artifact root, ownership, path layout, and
+file size. Do not widen filesystem permissions or the allowed root merely to
+make an arbitrary path work; move or copy the required artifact into the
+controlled location instead.
 
-- Generated artifact body goes to stdout by default.
-- `--out` writes generated artifact to a file.
-- Summary metadata line is written to stderr on success.
-- Exit code `2` means generation completed but validation failed.
+### Validation Failure
 
-`render` command:
+A generated-content validation failure is distinct from a runtime failure.
+CLI `run` reports the validation result and error count in its success summary;
+it does not print the individual validation messages. For HTTP, inspect the
+validation object in the response according to the [HTTP API reference](api.md).
 
-- Prepared-run output goes to stdout by default.
-- `--out` writes prepared-run output to a file.
-- Exit code is `0` on success and `1` on failure.
+Use rendered input and generated output to determine whether prompt instructions,
+the selected model, or the schema needs correction. If schema loading or
+compilation itself fails, correct the source deployment or schema document
+before rerunning.
 
-`serve` command:
+### HTTP Limit Or Request Failure
 
-- Startup and server errors are written to stderr.
+Compare the request, artifact, or expected response size with the deployed
+configuration, and validate the request against the [HTTP API reference](api.md).
+Reduce the payload, use an appropriate controlled artifact source, omit
+unneeded raw output, or adjust the deployment limit after capacity review.
 
-## Validation Behavior In Operations
+## Cleanup And Reruns
 
-Validation modes (`none`, `basic`, `json`, `json_schema`) are defined by prompt output contract.
-
-Operational interpretation:
-
-- Validation runtime errors are hard failures (`run` exit `1`; HTTP error response).
-- Validation content failures are soft failures (`run` exit `2`; HTTP `200` with failed status).
-
-A failed validation run can still produce output. Decide whether to keep or discard that output in your surrounding workflow.
-
-## Safe Recovery Steps
-
-For failed runs or requests:
-
-1. Capture stderr output or HTTP error code/message.
-2. Confirm config path and directory settings.
-3. Verify prompt/profile IDs and input mappings.
-4. Verify API-key environment-variable presence when required.
-5. Reproduce with `render --format json` when prompt/profile/input resolution is uncertain.
-6. Rerun after correction.
-
-Because Scriptorium does not persist run state, rerun is the canonical recovery path.
+Because no run state is retained, cleanup concerns caller-owned output files,
+logs, and artifacts only. Remove or rotate them using the deployment's normal
+retention policy. After a correction, rerun the request from the beginning;
+there is no safe resume point.

docs/policy/architecture.md

@@ -4,59 +4,41 @@ This document is the development architecture policy for Scriptorium.
 
 It is for developers and LLM coding agents. User-facing behavior belongs in `README.md` and the docs under `docs/` that target operators/users.
 
-## Project Shape
+## System Shape
 
-Scriptorium is a narrow prompt-execution application with three entry paths:
-
-- CLI `run`
-- CLI `render`
-- HTTP `POST /v1/runs` through `serve`
+Scriptorium is a narrow prompt-execution application with three executable
+entry paths: CLI `run`, CLI `render`, and the HTTP service started by `serve`.
+It also provides a public Go package for in-process use. Executable adapters
+consume framework behavior through that public facade; the facade continues to
+compose the framework implementation inside this single repository. Its current
+component inventory is maintained in the [internal overview](../internal/overview.md).
 
 Domain behavior is centralized in `internal/usecase` and `internal/domain`.
 
 ## Core Principles
 
 - Keep orchestration narrow: Scriptorium executes one prompt request; it is not a multi-step workflow engine.
-- Keep adapter logic thin: adapters map external shapes to domain requests/results and should not hold domain decisions.
+- Keep adapter logic thin: adapters map external shapes to public engine
+  requests/results and should not hold framework decisions.
 - Keep boundaries explicit: repositories/loaders/renderers/validators/LLM client stay behind package interfaces.
-- Keep config strict: YAML/JSON decoding for external inputs should reject unknown fields.
+- Keep external decoding strict: configuration, prompt, and profile YAML and
+  HTTP JSON should reject unknown fields.
 - Keep secrets out of payloads: raw API key values must not be accepted or emitted.
 
-## Package Boundaries
+## Dependency Direction
 
-Current package map:
-
-- `cmd/scriptorium`: process entrypoint.
-- `internal/adapter/cli`: command parsing, app wiring for CLI commands, output behavior.
-- `internal/adapter/http`: HTTP DTO mapping and error/status mapping.
-- `internal/config`: application settings loading and CLI override precedence.
-- `internal/defaults`: compile-time default constants.
-- `internal/domain`: core request/result and contract types.
-- `internal/usecase`: `Runner` prepare/run orchestration and repair-hook boundary.
-- `internal/promptdef`: filesystem prompt-definition repository.
-- `internal/profile`: filesystem execution-profile repository.
-- `internal/artifact`: artifact reference readers.
-- `internal/prompt`: template renderer.
-- `internal/llm`: provider-neutral LLM client interface and OpenAI-compatible implementation.
-- `internal/validate`: validator interfaces and standard implementation.
-- `internal/format`: prepared-run output formatting.
-
-Detailed component behavior is documented in:
-
-- `docs/internal/runner.md`
-- `docs/internal/adapters.md`
-
-## Configuration And Precedence
-
-Application settings are resolved as:
-
-1. built-in defaults
-2. config file values
-3. CLI overrides
-
-`config.yml` is for application wiring (directories, server address, render default format), not prompt/profile runtime execution settings.
-
-Profile selection and runtime model resolution remain use-case concerns.
+- Adapters translate external shapes and IO concerns; they do not make
+  use-case decisions.
+- Executable adapters and prepared-run formatting use the public facade for
+  framework behavior rather than importing framework implementation packages
+  directly.
+- Use-case and domain code depend on explicit repository, renderer, validator,
+  and LLM interfaces rather than adapter implementations.
+- Source, rendering, validation, and LLM implementations remain behind their
+  package boundaries.
+- Dependency-specific types must not leak across unrelated package boundaries.
+- Prefer the standard library; add an external dependency only when it
+  materially reduces risk or complexity.
 
 ## State And Persistence Policy
 
@@ -65,43 +47,32 @@ Scriptorium has no durable run-state store.
 - No built-in resume/checkpoint/archive behavior.
 - Recovery model is rerun after correcting inputs/config/environment.
 
-## External Integration Policy
+## Contract Ownership
 
-Current external contracts:
-
-- inbound HTTP contract: `POST /v1/runs`
-- outbound model contract: OpenAI-compatible chat completions subset
-- subprocess contract for integrators: CLI `run`/`render`
-
-Integration docs belong under `docs/integrations/`.
+The [CLI](../cli.md), [configuration](../config.md), [HTTP API](../api.md),
+[public Go package](../consumers/pkg-scriptorium.md), and
+[integration](../integrations/) documents own their respective external
+contracts. This policy keeps only the architectural boundaries that govern
+their implementation.
 
 ## Error Handling And Logging
 
 - Wrap errors with domain/operation context.
-- Map domain errors to adapter-appropriate statuses/codes without leaking sensitive internals.
-- Keep stderr summaries concise for CLI success/error paths.
+- Map public error identities to adapter-appropriate statuses/codes without
+  leaking sensitive internals.
 - Never emit raw secret values.
 
-## Testing Expectations
+## Testing And Documentation
 
-- Core runner behavior should be covered with isolated unit tests and fixture-based integration tests.
-- Adapter behavior should be tested for parse/mapping/error semantics.
-- Config parsing, prompt/profile loading, validator behavior, and LLM client error handling should remain covered by package tests.
-- Repository-level docs/examples that claim runnable behavior should be validated by tests or smoke commands.
-
-## Documentation Expectations
-
-- Document implemented behavior only outside `docs/roadmap/`.
-- Keep canonical reference locations stable (`docs/cli.md`, `docs/config.md`, `docs/operations.md`, `docs/troubleshooting.md`, `docs/internal/`).
-- Update docs in the same change when architecture-relevant behavior changes.
+Testing philosophy and change-validation expectations are defined by the
+[testing policy](testing.md). Documentation ownership and maintenance rules are
+defined by the [documentation policy](documentation.md).
 
 ## Architectural Invariants
 
 - `Runner.Run` reuses `Runner.Prepare` flow.
-- CLI and HTTP currently instantiate `Runner` without a repairer.
-- Artifact reading supports `inline` and `file` references.
-- Unknown input fields in config/prompt/profile/http JSON should be rejected by strict decoding.
-- Raw API key values must not be accepted through config/HTTP payloads.
+- Raw API key values must not be accepted through external configuration or
+  request payloads, and resolved secret values must not be emitted.
 
 ## Non-Goals
 

docs/policy/development.md

@@ -1,103 +0,0 @@
-# Development Guide
-
-This document defines contributor workflow for Scriptorium.
-
-## Repository Layout
-
-- `cmd/scriptorium`: application entrypoint.
-- `internal/domain`: core contracts.
-- `internal/usecase`: runner orchestration.
-- `internal/adapter/cli`: CLI adapter.
-- `internal/adapter/http`: HTTP adapter.
-- `internal/config`: application settings loading and precedence.
-- `internal/defaults`: default constants.
-- `internal/promptdef`: prompt-definition repository.
-- `internal/profile`: execution-profile repository.
-- `internal/artifact`: artifact readers.
-- `internal/prompt`: prompt rendering.
-- `internal/llm`: LLM client interface and OpenAI-compatible implementation.
-- `internal/validate`: validation interfaces and implementation.
-- `internal/format`: prepared-run formatting.
-- `docs/`: canonical documentation.
-- `examples/`: copyable maintained examples and fixtures.
-
-## Common Commands
-
-Build:
-
-```bash
-go build ./cmd/scriptorium
-```
-
-Test:
-
-```bash
-go test ./...
-```
-
-Targeted test runs commonly used during changes:
-
-```bash
-go test ./internal/adapter/cli ./internal/adapter/http ./internal/usecase
-```
-
-## Coding Conventions
-
-- Prefer small interfaces at package boundaries.
-- Keep adapter packages focused on translation and IO concerns.
-- Keep domain/use-case logic outside adapters.
-- Wrap errors with operation context.
-- Use strict decoding for user-provided YAML/JSON where applicable.
-- Avoid introducing dependencies unless they materially reduce risk/complexity.
-
-## Dependency Policy
-
-- Prefer standard library unless an external library is clearly justified.
-- Current non-stdlib dependencies are intentionally small:
-  - `gopkg.in/yaml.v3` for YAML decoding.
-  - `github.com/santhosh-tekuri/jsonschema/v6` for JSON Schema validation.
-- Do not leak dependency-specific types across unrelated package boundaries.
-
-## How To Add App Config Fields
-
-1. Add fields in `internal/config/config.go` (`Config`, `AppSettings`, and/or `CLIOverrides` as needed).
-2. Apply defaults in `BuiltInDefaults()` when required.
-3. Parse and validate in `applyConfig` / `ApplyCLIOverrides`.
-4. Wire the field through the consuming adapter(s).
-5. Add/update config tests in `internal/config/config_test.go`.
-6. Update canonical docs (`docs/config.md`, and other affected docs).
-
-## How To Add CLI Flags
-
-1. Add flags in `internal/adapter/cli/run.go` for the relevant command.
-2. Ensure precedence behavior remains consistent with app config rules.
-3. Keep `run`, `render`, and `serve` flag surfaces intentionally scoped.
-4. Add/update parser and command tests in `internal/adapter/cli/run_test.go`.
-5. Update `docs/cli.md` and any related docs/examples.
-
-## How To Add Adapters Or Adapter Capabilities
-
-1. Define or reuse the appropriate interface boundary in domain/use-case packages.
-2. Implement adapter code under `internal/adapter/<name>` (or relevant boundary package).
-3. Keep business decisions in `internal/usecase`.
-4. Add focused adapter tests for mapping, parse, and error behavior.
-5. Document the new/changed boundary in `docs/internal/adapters.md`.
-6. If external contract changes, update `docs/integrations/` in the same change.
-
-## How To Update Prompt/Profile/Schema Assets
-
-1. Keep prompt/profile/schema files valid under strict loaders.
-2. Keep examples secret-free.
-3. Re-run tests that cover prompt/profile/validation behavior.
-4. Update `docs/config.md` and any docs that reference changed contracts.
-
-## Documentation Update Expectations
-
-When behavior changes:
-
-1. Update canonical doc locations, not duplicate files.
-2. Keep non-roadmap docs limited to implemented behavior.
-3. Update links after file moves/renames.
-4. Re-run relevant tests and smoke commands.
-
-Docs work is complete only when code/tests/examples/docs agree.

docs/policy/documentation.md

@@ -1,356 +1,163 @@
-# Go Project Documentation Policy
+# Documentation Policy
 
 ## Purpose
 
-Project documentation must help four audiences:
-
-1. users who need to run the application;
-2. administrators/operators who need to configure and operate it;
-3. developers who need to understand and change it safely;
-4. LLM coding agents that need clear scope, boundaries, and invariants.
-
-Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition.
+This policy assigns each documentation topic to one canonical owner. Its goal is
+to keep this repository's documentation accurate, concise, discoverable, and
+resistant to drift for users, operators, developers, integrators, and LLM
+coding agents.
 
 ## Core Rules
 
-### 1. Keep docs concise
+### One Canonical Owner
 
-Each document should cover a defined scope and only the essentials for that scope.
+Each authoritative fact belongs in one document. A non-owning document may give
+a short, stable summary for orientation, but it must link to the canonical owner
+instead of repeating volatile details.
 
-Avoid:
-- long background explanations;
-- repeated reference material;
-- implementation detail in user-facing docs;
-- aspirational language outside roadmap docs;
-- verbose examples where one minimal example is clearer.
+Volatile details include commands, flags, configuration fields and defaults,
+module keys, schemas, file names, paths, status codes, retry behavior, and
+runtime guarantees. If readers could reasonably treat a statement as a
+contract, maintain it only in the owning document.
 
-### 2. Document only implemented behavior outside roadmap files
+Minimal tested usage examples are allowed outside the owning contract when this
+policy assigns them an orientation or instructional purpose. They must link to
+the canonical contract and must not redefine complete syntax, defaults, or
+semantics.
+
+### Current And Future Behavior
+
+Outside `docs/roadmap/`, documentation describes implemented behavior only.
+Partial features may be described only to their implemented boundary.
 
-Unimplemented, planned, aspirational, experimental, or future work may be described only under:
+ADRs are the narrow exception: an ADR may record an accepted architectural
+decision before implementation, but acceptance must not be presented as proof
+that the behavior exists. The roadmap owns implementation status and sequencing
+until the decision is implemented. Current architecture, user, operator,
+integration, and internal documentation are updated when the behavior lands.
 
-- `docs/roadmap/`
+### Audience And Detail
+
+Write for the document's stated audience and include only the detail needed for
+its owned topic. User and operator docs should not expose implementation detail.
+Developer docs should link to user-facing and external contracts rather than
+restate them.
+
+### Examples
+
+Complete copyable files belong in `examples/`. Documentation may use the
+smallest illustrative snippet needed to explain its owned topic, but should link
+to maintained examples instead of embedding a second complete copy.
+
+Examples must be valid, secret-free, and tested where practical. Commands and
+configuration used in documentation should match the application.
 
-No other documentation file, including `README.md`, should describe code, features, modules, stages, commands, config fields, or behaviors that do not currently exist.
+### Security And Privacy
 
-If a feature is partial, non-roadmap docs may describe only the implemented portion and its current boundary.
-
-### 3. Use canonical homes
-
-Each type of information should have one canonical location.
-
-Canonical homes:
-
-- project purpose and quickstart: `README.md`
-- development principles: `docs/policy/architecture.md`
-- configuration reference: `docs/config.md`
-- CLI reference: `docs/cli.md`
-- operations and recovery: `docs/operations.md`
-- troubleshooting: `docs/troubleshooting.md`
-- implemented internals: `docs/internal/`
-- future work: `docs/roadmap/`
-- contributor workflow: `docs/policy/development.md`
-- copyable examples: `examples/`
-
-Other files should summarize briefly and link to the canonical source.
-
-### 4. Keep examples real
-
-Examples should be valid, maintained, and free of secrets.
-
-Where practical:
-- example configs should load successfully;
-- example commands should match real CLI syntax;
-- important examples should be covered by tests.
-
-## Documentation Profiles
-
-All projects require:
-
-- `README.md`
-- `docs/policy/architecture.md`
-
-Additional docs depend on the project.
-
-### Small library
-
-Recommended:
-- `docs/policy/development.md`, if contributor conventions are non-obvious
-
-### Simple CLI
-
-Required:
-- `docs/cli.md`
-
-Recommended:
-- `docs/policy/development.md`
-
-### Config-driven CLI
-
-Required:
-- `docs/cli.md`
-- `docs/config.md`
-
-Recommended:
-- `examples/`
-- `docs/policy/development.md`
-
-### Stateful or operator-facing application
-
-Required:
-- `docs/cli.md`, if CLI-based
-- `docs/config.md`, if config-driven
-- `docs/operations.md`
-
-Recommended:
-- `docs/troubleshooting.md`
-- `examples/`
-- `docs/policy/development.md`
-
-### Modular, staged, service-oriented, or orchestration application
-
-Required:
-- `docs/cli.md`, if CLI-based
-- `docs/config.md`, if config-driven
-- `docs/operations.md`
-- `docs/internal/`
-- `docs/policy/development.md`
-
-Recommended:
-- `docs/troubleshooting.md`
-- validated examples under `examples/`
-
-## Required Documents
-
-### README.md
-
-**Audience:** users, administrators, operators
-
-The README is the outward-facing project orientation page.
-
-It should include, in order:
-
-1. concise description;
-2. elevator pitch;
-3. shortest useful command or usage example;
-4. links to targeted docs.
-
-The README should be short. It is not a manual.
-
-The “shortest useful command” means the simplest command that performs the project’s core use case. (It does not mean `app --help`.)
-
-### docs/policy/architecture.md
-
-**Audience:** developers, LLM coding agents
-
-`docs/policy/architecture.md` is required for every project.
-
-It is an inward-facing development policy document. It should describe how the project is intended to be built and changed.
-
-It should include:
-
-- project shape;
-- core design principles;
-- package and boundary philosophy;
-- state/persistence philosophy, if applicable;
-- external integration philosophy, if applicable;
-- error-handling and logging principles;
-- testing expectations;
-- documentation expectations;
-- architectural invariants;
-- explicit non-goals, if useful.
-
-For small projects, this file may be brief. It may simply state that the project is intentionally narrow, monolithic, and dependency-light.
-
-### docs/policy/development.md
-
-**Audience:** developers, LLM coding agents
-
-Required for projects maintained by humans and LLM coding agents.
-
-It should include:
-
-- repository layout;
-- build/test commands;
-- coding conventions;
-- dependency policy;
-- how to add config fields;
-- how to add CLI flags;
-- how to add stages/modules/adapters, if applicable;
-- how to update examples;
-- documentation update expectations.
-
-### docs/config.md
-
-**Audience:** administrators, operators, advanced users
-
-Required for applications with configuration files.
-
-It should include, in order:
-
-1. config file locations and discovery precedence;
-2. minimal working config;
-3. production-oriented config;
-4. full configuration reference;
-5. secrets handling, if applicable;
-6. links to maintained examples.
-
-The full configuration reference should be canonical.
-
-### docs/cli.md
-
-**Audience:** users, administrators, operators
-
-Required for CLI applications.
-
-It should include, in order:
-
-1. shortest useful command;
-2. command overview;
-3. complete flag reference;
-4. common workflows;
-5. diagnostic or recovery commands, if applicable.
-
-Explain when commands are useful, not just their syntax.
-
-### docs/operations.md
-
-**Audience:** administrators, operators
-
-Required for applications that maintain state, support resume behavior, run multiple stages, write durable artifacts, use remote storage, or require recovery procedures.
-
-It should cover:
-
-- normal workflow;
-- filesystem layout;
-- remote storage layout, if applicable;
-- logs and manifests;
-- resume/retry behavior;
-- cleanup behavior;
-- archive/backup behavior;
-- safe recovery procedures;
-- operational caveats.
-
-### docs/troubleshooting.md
-
-**Audience:** administrators, operators
-
-Recommended once recurring failure modes exist.
-
-Each entry should include:
-
-- symptom;
-- likely cause;
-- diagnostic command or inspection step;
-- safe fix;
-- relevant links.
-
-### docs/internal/
-
-**Audience:** developers, LLM coding agents
-
-Required for modular, staged, service-oriented, or orchestration projects.
-
-This directory describes implemented internal components. It is not the roadmap.
-
-Use one file per major component where useful.
-
-Each component doc should include:
-
-1. purpose;
-2. inputs and outputs;
-3. boundaries;
-4. config fields used;
-5. external adapters used;
-6. state or manifest behavior, if applicable;
-7. skip/resume behavior, if applicable;
-8. failure behavior;
-9. tests to inspect before changing;
-10. architectural invariants.
-
-### docs/roadmap/
-
-**Audience:** maintainers, developers, LLM coding agents
-
-This is the only place for planned, future, aspirational, experimental, or unimplemented work.
-
-Roadmap docs should clearly distinguish:
-
-- proposed work;
-- accepted plans;
-- deferred ideas;
-- rejected ideas;
-- implementation prompts or task breakdowns, if useful.
-
-Roadmap docs should not be confused with current behavior.
-
-### docs/integrations/
-
-**Audience:** developers, LLM coding agents
-
-Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
-
-This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses.
-
-Use one file per integration where useful.
-
-## Examples Directory
-
-Projects with non-trivial configuration or workflows should include `examples/`.
-
-Useful examples include:
-
-- minimal working config;
-- production-oriented config;
-- full annotated config;
-- local development config;
-- remote/object-storage config;
-- minimal session/input file.
-
-Examples should be valid, maintained, tested when practical, and linked from relevant docs.
-
-## Security and Privacy
-
-Docs and examples must not include:
-
-- real API keys;
-- tokens;
-- passwords;
-- private keys;
-- private environment dumps;
-- sensitive user data;
-- raw private transcripts;
-- private infrastructure details unless intentionally public.
-
-Document secret-handling mechanisms, not actual secret values.
-
-## Maintenance Rules
-
-When docs change, verify the affected behavior.
-
-Where practical:
-
-- load example config files in tests;
-- test CLI examples or command parser behavior;
-- validate documented flags against real flags;
-- remove stale references;
-- update links after renames;
-- keep roadmap content out of non-roadmap docs.
-
-If documentation and code disagree, fix the documentation and/or open a roadmap item; do not leave aspirational behavior in current-behavior docs.
-
-Documentation is complete only when it matches the current code.
-
-## Documentation Change Checklist
-
-Before merging documentation changes, verify:
-
-- README is concise and orientation-focused.
-- `docs/policy/architecture.md` describes development principles.
-- Future work appears only under `docs/roadmap/`.
-- User-facing docs avoid unnecessary internals.
-- Developer-facing docs preserve boundaries and invariants.
-- Config examples match the schema.
-- CLI examples match real commands and flags.
-- Defaults appear in the canonical config reference.
-- No secrets or private data are included.
-- Links are accurate.
+Documentation and examples must not contain real credentials, private keys,
+private environment dumps, sensitive source material, or private infrastructure
+details unless intentionally public. Document secret-handling mechanisms, not
+secret values.
+
+## Canonical Ownership
+
+| Topic | Canonical owner | Owned content | Content owned elsewhere |
+| --- | --- | --- | --- |
+| Product orientation and minimal end-to-end quickstart | `README.md` | What this project is, why it is useful, one shortest successful invocation, and links onward. | Complete command reference, configuration reference, operational procedures, implementation detail. |
+| Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, and detailed change recipes, which belong in the relevant internal component document. |
+| Current application architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
+| Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. |
+| Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression-test policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
+| CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
+| Configuration contract | `docs/config.md` | Discovery and precedence, file schema, fields, defaults, environment overrides, validation rules, and user-selectable module or validator keys. | Complete example files, CLI syntax, runtime state lifecycle, module implementation details. |
+| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache, and debug handling, resume, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. |
+| Public HTTP contract | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. |
+| Consumer guidance | `docs/consumers/` | Task-oriented use of the public interface, minimal client examples, and consumer responsibilities. | HTTP wire semantics, external protocol contracts, internal implementation detail. |
+| External and durable integration contracts | `docs/integrations/` | External file formats and protocols, upstream and downstream contracts, logical output bundle paths and schemas, media types, and compatibility behavior. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
+| Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
+| Internal component behavior | Other files under `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
+| Architectural decision history | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
+| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status; sequencing; and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
+| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other files intended to be copied or run. | Field-by-field reference, command reference, prose explanation. |
+
+Documents that do not exist are required only when the corresponding interface
+or responsibility exists. Do not create placeholder API, consumer, integration,
+or operations documents for behavior the application does not have.
+
+## Boundary Rules
+
+### Orientation
+
+The README owns product orientation. The developer guide routes contributors.
+Architecture owns normative structure. Internal overview owns the current
+concrete component map. These documents may link to one another but should not
+maintain parallel package or behavior descriptions.
+
+### Commands, Configuration, And Operations
+
+CLI documentation answers how to invoke the application. Configuration
+documentation answers what settings mean. Operations answers what happens to
+runtime state and how to operate or recover the application. When a workflow
+crosses these topics, choose the document that owns the task and link to the
+other contracts.
+
+### Contracts And Implementation
+
+Integration and API documents define externally observable shapes and
+semantics. Internal documents explain how this project implements or consumes
+those contracts. Internal docs may name a field, file, or protocol to identify
+a dependency, but must link to its canonical contract for the definition.
+
+### Security Topics
+
+This policy owns what documentation and examples may contain. Architecture owns
+application security invariants. Configuration owns credential-supply
+mechanisms. Operations owns permissions and handling of sensitive runtime
+artifacts. Internal docs own implementation mechanisms only.
+
+## Architecture Decision Records
+
+Use sequentially numbered ADR filenames such as
+`0001-record-architecture-decisions.md`. Follow the lightweight Nygard format:
+
+1. title;
+2. status;
+3. date;
+4. context;
+5. decision;
+6. alternatives considered;
+7. consequences.
+
+Use one of these statuses:
+
+- **Proposed:** the decision is under consideration and may change;
+- **Accepted:** the decision is approved, whether or not implementation is
+  complete;
+- **Rejected:** the proposed decision was considered and not adopted;
+- **Superseded:** a later ADR replaces the accepted decision.
+
+A proposed ADR transitions to accepted or rejected. An accepted ADR transitions
+to superseded only when a later accepted ADR replaces it. An ADR may be created
+as accepted when the decision has already been made.
+
+Treat the decision content of an accepted ADR as immutable. Its status and
+supersession metadata may be updated, but a changed decision requires a new ADR.
+A superseded ADR must link to its replacement, and the replacement must link
+back to the superseded ADR. Rejected architectural alternatives belong in the
+ADR; rejected product ideas belong in the roadmap.
+
+## Maintenance
+
+When behavior changes, update its canonical owner in the same change. If
+ownership moves, remove the old definition and replace it with a link where
+navigation remains useful.
+
+Before completing documentation work:
+
+- verify affected behavior and examples;
+- check commands, flags, fields, defaults, schemas, and paths against their
+  implementation;
+- keep unimplemented behavior in the roadmap, subject to the ADR exception;
+- remove stale references and validate links;
+- confirm that non-owning documents summarize and link rather than redefine;
+- confirm that no secrets or sensitive private data were added.

docs/policy/testing.md

@@ -0,0 +1,296 @@
+# Testing Policy
+
+## Purpose
+
+Our tests exist to make **incorrect changes expensive and correct changes cheap**.
+
+We do not optimize for test count, line coverage, exhaustive isolation, or the fewest possible tests. We optimize for sufficient confidence in important behavior while imposing as little unnecessary friction as possible on future development.
+
+## Every test has a cost
+
+Testing is not an unqualified good. Every test imposes both an immediate cost and a continuing lifetime cost.
+
+A test must be:
+
+- written and reviewed;
+- understood by future maintainers and coding agents;
+- executed in local and CI workflows;
+- diagnosed when it fails;
+- updated when legitimate behavior changes;
+- maintained as fixtures, APIs, and dependencies evolve; and
+- removed or rewritten when it becomes redundant, brittle, misleading, or obsolete.
+
+Tests also create cognitive and architectural friction. They can constrain refactoring, duplicate policy, slow feedback loops, add noise to failures, and cause harmless implementation changes to require unrelated edits across the suite.
+
+A test is warranted only when the confidence it provides justifies these costs.
+
+Apply this cost-benefit analysis at two levels:
+
+1. **Per test:** What realistic defect does this test detect, how consequential would that defect be, and is that protection worth the test's lifetime cost?
+2. **Across the suite:** Does this collection provide materially more confidence than a smaller, simpler suite would?
+
+The preferred test suite is a **lean suite that provides sufficient confidence in the risks that matter, without redundant or low-value tests**. We seek sufficient confidence with the least unnecessary testing friction, not the fewest possible tests.
+
+Some friction is intentional. Tests should make dangerous changes—such as breaking compatibility, corrupting data, violating security boundaries, or reintroducing subtle bugs—require deliberate review. They should not make ordinary internal changes needlessly expensive.
+
+The cost of a test is not a reason to omit testing by default. Do not cite maintenance cost abstractly. When omitting a plausible test, be able to state why the protected failure is low-risk, already covered, obvious, reversible, or cheaper to detect elsewhere. For consequential, subtle, or difficult-to-observe behavior, the presumption should favor testing.
+
+## Default testing style
+
+Use a **classical/Detroit-style** approach:
+
+- Test observable behavior, resulting state, contracts, and invariants.
+- Use real internal collaborators when they are fast and deterministic.
+- Use fakes, stubs, or mocks primarily at expensive, nondeterministic, destructive, or external boundaries.
+- Prefer package-level behavioral tests over tests coupled to private helpers or internal call sequences.
+- Treat exact collaborator interactions as testable behavior only when the interaction itself is a requirement.
+
+Examples of appropriate seams include clocks, randomness, subprocesses, remote APIs, object storage, email, and paid LLM calls.
+
+## Test execution requirements
+
+Tests in the default suite must be deterministic, offline, and independent of real credentials. They must not invoke paid APIs or depend on mutable external services. Tests that require live infrastructure must be explicitly opt-in and clearly separated from the default suite.
+
+Control clocks, randomness, environment variables, and other process-global or machine-specific state when they affect behavior. Tests should be safe to run repeatedly and alongside other tests without depending on execution order or state left by an earlier test.
+
+## What deserves tests
+
+Prioritize tests for:
+
+1. Public and package-level contracts.
+2. Domain rules and important invariants.
+3. Boundary conditions and malformed input.
+4. Failure handling, cancellation, retries, recovery, and partial success.
+5. Serialization, schemas, compatibility, and round trips.
+6. Previously observed or plausible regressions.
+7. Representative integration and end-to-end workflows.
+
+A package-level contract is behavior relied upon by another package or major collaborator, not every observable detail of a package implementation.
+
+For behavior involving **data integrity, destructive operations, compatibility, security, concurrency, idempotency, or recovery**, presume that durable tests are required unless the behavior is already credibly protected at another layer.
+
+Do not add tests merely because a function, branch, or line exists. Do not add a test when the same meaningful risk is already adequately protected elsewhere.
+
+## Choose the right test boundary
+
+Test through the narrowest stable boundary that expresses the behavior clearly.
+
+This is often the package API, but it may instead be:
+
+- a smaller pure function when dense domain logic is most clearly isolated there;
+- a package-level operation when several internal collaborators jointly produce the behavior; or
+- a larger integration boundary when correctness emerges from interaction with a real dependency.
+
+Do not force all behavior through oversized end-to-end tests. Do not test every private helper merely because it exists. Choose the boundary that gives durable confidence with the least incidental coupling.
+
+## Test behavior, not implementation
+
+A test should protect a decision, contract, or invariant—not memorialize the current implementation.
+
+Before adding or retaining a test, ask:
+
+> What realistic defect would this test catch?
+
+A test is suspect when its main purpose is to detect that someone:
+
+- changed an internal constant;
+- renamed or split a private helper;
+- reordered equivalent internal operations;
+- changed incidental formatting;
+- replaced one correct algorithm with another; or
+- refactored internal object structure without changing behavior.
+
+Refactoring should normally require no test edits unless the refactored structure is itself part of the contract.
+
+A test can be factually correct and still have negative value. Accurately describing current behavior is not enough; the protected behavior must be important enough to justify the future friction.
+
+## Expected effects of different changes
+
+Use the following expectations when evaluating test failures and test maintenance:
+
+| Change | Expected effect on tests |
+|---|---|
+| Internal refactor that preserves behavior | Existing tests should normally remain unchanged and continue to pass. |
+| Change to an internal default with no contractual significance | Behavioral tests should normally remain unchanged; tests should derive expectations from configuration or relationships rather than duplicate the old value. |
+| Intentional change to public behavior, policy, schema, or compatibility guarantees | The relevant tests should be reviewed and changed deliberately. |
+| Accidental violation of a contract or invariant | Tests should fail; fix the production code rather than rewriting the tests to accept the defect. |
+
+A test failing is not the same as a test needing to be edited. Many tests may correctly fail because of one production defect. The maintenance smell is a correct internal change that requires unrelated expectation updates throughout the suite.
+
+## Separate mechanism from policy
+
+Configurable thresholds and defaults must not be duplicated throughout the test suite.
+
+For example, do not encode an internal concurrency limit indirectly:
+
+```go
+// Production policy:
+const maxConcurrency = 4
+
+// Brittle test:
+err := startProcesses(5)
+require.Error(t, err)
+```
+
+Instead, test the mechanism relationally:
+
+```go
+const limit = 2
+runner := NewRunner(limit)
+
+require.NoError(t, runner.Start(limit))
+require.ErrorIs(t, runner.Start(limit+1), ErrTooMuchConcurrency)
+```
+
+The test should prove:
+
+- the configured limit is accepted; and
+- one beyond the configured limit is rejected.
+
+The production default should be tested exactly only when its literal value is itself a public, operational, safety, protocol, or compatibility requirement.
+
+Apply the same rule to limits, timeouts, capacities, retry counts, and ranges: test relationships and behavior, not duplicated literals.
+
+For concurrency limits, test both kinds of behavior when relevant:
+
+1. **Configuration enforcement:** invalid or excessive requested values are handled correctly.
+2. **Runtime enforcement:** observed peak concurrency never exceeds the configured limit.
+
+Use a test-controlled limit and measure the behavior relative to that limit. Do not merely assert today's default value.
+
+## Avoid semantic duplication across layers
+
+Each behavior should have a clear test owner.
+
+- Parser tests own parsing cases.
+- Validator tests own validation rules.
+- Domain tests own transformations and invariants.
+- Adapter tests own external integration behavior.
+- Orchestrator tests own coordination and failure propagation.
+- CLI tests own argument and configuration mapping.
+- End-to-end tests prove that representative assembled workflows work.
+
+Higher-level tests should not repeat every lower-level case. A single intentional policy change should not require unrelated edits across many test files.
+
+Tests that are individually reasonable may still be collectively redundant. Evaluate the marginal value of each additional test in light of the protection already provided by the rest of the suite.
+
+## Use test doubles deliberately
+
+Choose the least elaborate test double that provides the required control or observation.
+
+As a default:
+
+1. Prefer real collaborators when they are fast and deterministic.
+2. Use small in-memory fakes when realistic stateful behavior is helpful.
+3. Use stubs when a dependency only needs to provide controlled responses.
+4. Use mocks when the interaction itself is contractual.
+
+Mocks are appropriate when the contract includes facts such as:
+
+- a notification is sent exactly once;
+- a transaction is committed only after successful writes;
+- cancellation reaches a subprocess;
+- an expensive API is called no more than once; or
+- a security audit event is emitted.
+
+Do not use mocks merely to isolate every object or reproduce the implementation's call graph.
+
+## Go-specific guidance
+
+Use:
+
+- table-driven tests for meaningful behavioral categories and boundaries;
+- `t.TempDir()` for real filesystem behavior;
+- `httptest.Server` for realistic HTTP interactions;
+- fuzz tests for parsers, normalization, path handling, and broad input spaces;
+- golden files only when the complete output is intentionally stable;
+- integration tests where correctness depends on component interaction; and
+- a small number of representative end-to-end tests.
+
+Avoid exact error-string assertions unless the wording is itself contractual. Prefer `errors.Is`, `errors.As`, typed errors, or structured error fields.
+
+At CLI boundaries, prefer exit classifications, structured output, and the smallest stable semantic fragment needed to identify the error. Do not snapshot complete diagnostic wording unless it is contractual.
+
+Golden-file updates must require an explicit local flag. CI must not update golden files automatically, and reviewers must inspect the semantic diff before accepting an update.
+
+Keep tests readable and direct. Test helpers and fixture frameworks must earn their own maintenance cost; do not build elaborate test infrastructure for small or isolated needs.
+
+## Coverage
+
+Coverage is a diagnostic, not a target.
+
+Use it to find untested critical branches and unexpectedly weak packages. Do not write low-value tests solely to increase a percentage, and do not infer test quality from coverage alone.
+
+Pure domain logic will often warrant higher coverage than CLI wiring or external adapters. Uneven coverage is acceptable when it reflects risk.
+
+Increasing coverage is valuable only when the newly covered behavior protects a meaningful risk at an acceptable cost.
+
+## Regression tests
+
+A bug fix should normally include a regression test that fails before the fix and passes afterward.
+
+Retain the test when the defect could realistically recur and its consequences justify the ongoing cost. Prefer the narrowest durable test of the violated contract or invariant; do not preserve accidental implementation details from the original bug.
+
+Not every historical bug requires a permanent test. If the underlying design has made recurrence impossible, the test has become redundant, or a stronger invariant test now subsumes it, remove or consolidate it.
+
+## Deleting or rewriting tests
+
+Tests are maintained code, not permanent historical artifacts.
+
+Delete or rewrite a test when its maintenance cost exceeds the confidence it provides.
+
+Strong candidates include tests that:
+
+- require updates after harmless internal changes;
+- directly assert private constants without protecting a real contract;
+- duplicate the same policy across several layers;
+- verify mock choreography rather than outcomes;
+- snapshot large amounts of incidental output;
+- test trivial private helpers already exercised through stable package behavior;
+- protect risks already covered more effectively elsewhere;
+- are flaky, misleading, obsolete, or disproportionately expensive to diagnose; or
+- no longer correspond to a plausible failure mode.
+
+Several brittle tests may encode one genuine requirement. Replace them with one durable behavior-level or invariant test rather than preserving all of them.
+
+Deleting a low-value test can improve the quality of the suite by reducing noise, maintenance burden, and friction around legitimate change.
+
+## Reviewing a proposed test
+
+Use the following questions when the value, boundary, or durability of a proposed test is not self-evident. Significant test additions should be reviewable against them, but written answers are not required for every routine test.
+
+1. What realistic defect would it catch?
+2. How likely is that defect?
+3. How consequential would it be?
+4. Is the behavior already protected elsewhere?
+5. At which layer should this behavior be owned?
+6. Does the test assert a durable contract or an incidental implementation detail?
+7. Could the implementation be refactored without changing the behavior and without editing this test?
+8. What should cause this test to fail?
+9. What legitimate changes should not cause this test to fail?
+10. What ongoing maintenance, execution, and diagnostic cost will the test impose?
+11. Is there a smaller or more direct test that protects the same risk?
+
+Do not add the test when its expected lifetime cost exceeds its expected protective value.
+
+When deciding not to test plausible behavior, record or be able to explain why the risk is low, already protected, obvious, reversible, or cheaper to detect elsewhere.
+
+## Definition of sufficient
+
+A test suite is sufficient when:
+
+- important contracts and invariants are protected;
+- meaningful boundaries and failure modes are exercised;
+- realistic and consequential regressions are credibly protected against silent recurrence;
+- behavior involving data integrity, destructive operations, compatibility, security, concurrency, idempotency, and recovery is credibly protected;
+- important external boundaries have realistic integration coverage;
+- representative complete workflows are tested;
+- failures provide useful signal rather than redundant noise;
+- legitimate internal changes usually do not require test edits; and
+- additional tests would mostly repeat existing protection or preserve inconsequential implementation details.
+
+Sufficiency is a risk judgment, not a coverage percentage or test count. Reassess it as the application, its users, and the consequences of failure evolve.
+
+The governing rule is:
+
+> Test heavily where failure is consequential, subtle, or difficult to detect after the fact. Test lightly where failure is obvious, reversible, and inexpensive—and retain no test whose lifetime cost exceeds the confidence it provides.

docs/roadmap/implementation.md

@@ -1,262 +1,62 @@
-# Runtime Parameter Implementation Plan
+# Migration Step 4 Implementation Plan
 
-This plan implements the target state in `docs/roadmap/params.md`.
+## Status
 
-Audience: LLM coding agents implementing the feature in order. Follow `docs/policy/architecture.md`, `docs/policy/development.md`, and `docs/policy/documentation.md` before changing code.
+Complete as of 2026-07-28. The public-facade adapter boundary and its
+post-implementation remediation are fully revalidated.
+
+## Objective
+
+This plan completed the target state in the
+[Step 4 public-facade adapter roadmap](step4.md) without changing the intended
+CLI, HTTP, or public Go contracts.
+
+The [accepted split decision](../adr/0002-split-promptkit-from-scriptorium.md)
+owns the long-term Promptkit/Scriptorium boundary. The
+[testing policy](../policy/testing.md) governs test value and ownership. The
+[documentation policy](../policy/documentation.md) governs completion
+bookkeeping and canonical ownership.
 
 ## Constraints
 
-- Keep adapters thin. CLI and HTTP should capture caller intent and map it into domain request types; merge decisions belong in `internal/usecase`.
-- Keep external decoding strict. Unknown YAML/JSON fields must continue to fail.
-- Do not accept or emit raw API key values.
-- Do not add dependencies unless there is a clear need. This feature should use the standard library plus existing dependencies.
-- Do not expand the HTTP API surface beyond `POST /v1/runs`.
-- Do not add provider-specific adapter packages.
-- Keep each stage passing `go test ./...` before moving to the next stage.
+- Keep this work in the Scriptorium repository. Do not modify the sibling
+  Promptkit repository or infer that Migration Step 5 is complete merely from
+  its local presence.
+- Preserve the public `ArtifactReader`, error sentinel, CLI, HTTP, containment,
+  artifact-size, formatting, timeout, credential, and redaction contracts.
+- Do not add compatibility shims, begin framework extraction, change the module
+  path, or add dependencies.
+- Keep tests deterministic, offline, independent of machine MIME databases,
+  and focused at the narrowest stable owner.
+- Preserve unrelated working-tree changes.
 
-## Stage 1: Presence-Aware Request Overrides
+## Completed Work
 
-Goal: make per-request numeric execution overrides presence-aware while keeping resolved execution settings concrete.
+The original implementation established the Step 4 boundary:
 
-### Domain Changes
+- the root facade now exposes `ArtifactReader` and `WithArtifactReader`, copies
+  mutable artifact bodies, handles nil responses, and exposes the two specific
+  public request-error identities required by HTTP;
+- the restricted artifact reader and its containment and byte-limit policy now
+  belong to the HTTP adapter and use public artifact types;
+- prepared-run formatting and CLI `run` and `render` consume public prepared,
+  request, and result values;
+- the HTTP handler consumes a local interface expressed in public types, and
+  CLI `serve` injects the restricted reader into the public engine;
+- the legacy restricted framework reader was removed, current-behavior
+  documentation was reconciled, and an initial dependency guard was added; and
+- the initial validation pass covered the full suite, vet, build, race and
+  repeated tests, maintained examples, configuration loading, links, and
+  whitespace.
 
-1. In `internal/domain/domain.go`, add a request-only type:
+The post-implementation remediation is also complete:
 
-```go
-type ExecutionTargetOverride struct {
-	Endpoint        string         `json:"endpoint,omitempty"`
-	Model           string         `json:"model,omitempty"`
-	Temperature     *float64       `json:"temperature,omitempty"`
-	MaxTokens       *int           `json:"max_tokens,omitempty"`
-	TopP            *float64       `json:"top_p,omitempty"`
-	TimeoutSeconds  *int           `json:"timeout_seconds,omitempty"`
-	ServiceTier     string         `json:"service_tier,omitempty"`
-	ReasoningEffort string         `json:"reasoning_effort,omitempty"`
-	APIKeyEnv       string         `json:"api_key_env,omitempty"`
-	ExtraParams     map[string]any `json:"extra_params,omitempty"`
-}
-```
-
-2. Change `domain.RunRequest.Execution` from `*ExecutionTarget` to `*ExecutionTargetOverride`.
-3. Change `ExecutionProfile.ExtraParams` and `ExecutionTarget.ExtraParams` from `map[string]string` to `map[string]any`.
-4. Keep `ExecutionTarget` concrete. It represents the resolved effective runtime target after defaults, profile, and request overrides are merged.
-
-### Runner Changes
-
-1. Update `internal/usecase/runner.go` so profile values still merge over built-in defaults and request overrides merge over that result.
-2. Keep the existing concrete profile merge semantics for profile numeric fields.
-3. Add a separate request override merge path that uses pointer presence:
-   - `nil` numeric pointer means omitted; preserve the current value.
-   - non-nil numeric pointer means explicit override, even when the value is `0`.
-4. Validate request override numeric values before or during merge:
-   - `temperature`: `0 <= value <= 2`
-   - `max_tokens`: `value >= 0`
-   - `top_p`: `0 <= value <= 1`
-   - `timeout_seconds`: `value >= 0`
-5. Preserve existing validation after merge:
-   - effective endpoint required
-   - effective model required
-   - `api_key_env`, when set, must name a non-empty environment variable
-6. Preserve secret handling. The resolved API key value must never be stored in `PreparedRun`, `RunResult`, logs, or HTTP responses.
-
-### CLI Changes
-
-1. Update `internal/adapter/cli/run.go` request construction to build `domain.ExecutionTargetOverride`.
-2. Use the existing `flagWasSet` booleans to populate numeric pointers only when the user provided the flag.
-3. Required behavior:
-   - omitted `--temperature` preserves profile/default temperature;
-   - `--temperature 0` explicitly sets temperature to zero;
-   - omitted `--top-p` preserves profile/default top-p;
-   - `--top-p 0` explicitly sets top-p to zero;
-   - omitted `--max-tokens` preserves profile/default max tokens;
-   - `--max-tokens 0` explicitly sets max tokens to zero;
-   - omitted `--timeout` preserves profile/default timeout;
-   - `--timeout 0s` explicitly sets timeout seconds to zero.
-4. Do not add new CLI flags in this stage.
-
-### HTTP Changes
-
-1. Update `internal/adapter/http/dto.go` so numeric model override fields are pointers:
-   - `Temperature *float64`
-   - `MaxTokens *int`
-   - `TopP *float64`
-   - `TimeoutSeconds *int`
-2. Update DTO mapping in `internal/adapter/http/handler.go` to build `domain.ExecutionTargetOverride`.
-3. Preserve strict JSON decoding and existing error mapping.
-4. Required behavior:
-   - omitted numeric JSON fields preserve profile/default values;
-   - explicit numeric zero JSON fields override profile/default values.
-
-### Tests
-
-Add or update tests in:
-
-- `internal/usecase/runner_test.go`
-- `internal/adapter/cli/run_test.go`
-- `internal/adapter/http/handler_test.go`
-
-Required test coverage:
-
-- Runner preserves profile value when request numeric override is omitted.
-- Runner applies explicit zero request override for `temperature`.
-- Runner applies explicit zero request override for `top_p`.
-- Runner applies explicit zero request override for `max_tokens`.
-- Runner applies explicit zero request override for `timeout_seconds`.
-- Invalid request override ranges fail as invalid request errors.
-- CLI `--temperature 0` reaches effective settings as zero.
-- HTTP `"temperature": 0` reaches effective settings as zero.
-- HTTP omitted `temperature` preserves profile/default value.
-
-### Verification
-
-Run:
-
-```bash
-go test ./...
-```
-
-## Stage 2: JSON-Compatible `extra_params`
-
-Goal: allow provider-specific parameters to carry JSON-compatible values throughout profile, HTTP, prepared output, metadata, and LLM request construction.
-
-### Domain And Loader Changes
-
-1. Complete all compile fixes from changing `ExtraParams` to `map[string]any`.
-2. Ensure `internal/profile/filesystem_repository.go` continues to decode profiles strictly while allowing nested JSON-compatible values under `extra_params`.
-3. Add profile repository tests for `extra_params` containing:
-   - string
-   - number
-   - boolean
-   - nested object or array
-4. Ensure formatter output remains deterministic:
-   - keep sorting `extra_params` keys in `internal/format/prepared_run.go`;
-   - render non-string values with stable JSON encoding in text output.
-5. Preserve JSON formatter behavior through normal `encoding/json` output.
-
-### HTTP Changes
-
-1. Change HTTP model override `ExtraParams` to `map[string]any`.
-2. Add handler tests proving HTTP accepts JSON-compatible `extra_params` values.
-3. Preserve strict rejection of unknown fields and raw API-key payload fields.
-
-### Verification
-
-Run:
-
-```bash
-go test ./...
-```
-
-## Stage 3: Outbound Serialization
-
-Goal: serialize `reasoning_effort` and `extra_params` to the OpenAI-compatible chat-completions request.
-
-### LLM Adapter Changes
-
-1. In `internal/llm/openai_compatible_client.go`, add first-class outbound support for `reasoning_effort`.
-2. Add `extra_params` support by flattening `domain.ExecutionTarget.ExtraParams` into additional top-level JSON request fields.
-3. Implement reserved-field collision checks before the HTTP request is made.
-4. Reserved keys must include:
-   - `model`
-   - `session_id`
-   - `messages`
-   - `temperature`
-   - `max_tokens`
-   - `top_p`
-   - `service_tier`
-   - `reasoning_effort`
-   - `response_format`
-5. Reject empty `extra_params` keys.
-6. Ensure each `extra_params` value can be marshaled as JSON. If marshaling fails, return `ErrInvalidRequest` with context.
-7. Keep existing request behavior unchanged when `reasoning_effort` and `extra_params` are unset.
-
-### Recommended Implementation Shape
-
-Use a custom marshal path for the outbound chat request rather than string manipulation.
-
-One acceptable shape:
-
-- Add `ReasoningEffort string` and `ExtraParams map[string]any` to the internal `openAIChatRequest`.
-- Add a helper that converts `openAIChatRequest` into `map[string]any`, inserts first-class fields when set, then inserts `ExtraParams` after collision validation.
-- Marshal that map with `encoding/json`.
-
-Do not construct outbound JSON with manual string concatenation.
-
-### Tests
-
-Update `internal/llm/openai_compatible_client_test.go`.
-
-Required test coverage:
-
-- outbound JSON includes `reasoning_effort` when set;
-- outbound JSON omits `reasoning_effort` when unset;
-- outbound JSON includes string, number, boolean, object, and array `extra_params`;
-- reserved `extra_params` keys fail before provider call;
-- empty `extra_params` keys fail before provider call;
-- existing message, cache-control, service-tier, response-format, and usage parsing tests continue to pass.
-
-### Verification
-
-Run:
-
-```bash
-go test ./...
-```
-
-## Stage 4: Documentation And Examples
-
-Goal: move implemented behavior from roadmap to canonical docs after code is complete.
-
-Update only after Stages 1 through 3 are implemented.
-
-### Required Docs
-
-Update:
-
-- `docs/config.md`
-- `docs/cli.md`
-- `docs/integrations/http-api.md`
-- `docs/integrations/openai-compatible-chat.md`
-- `docs/internal/runner.md`
-- `docs/internal/adapters.md`
-
-Required documentation content:
-
-- `reasoning_effort` is serialized outbound when set.
-- `extra_params` serializes as provider-specific top-level outbound JSON fields.
-- `extra_params` supports JSON-compatible values.
-- reserved `extra_params` fields are rejected.
-- per-request numeric overrides distinguish omitted values from explicit zero values.
-- CLI explicit zero behavior for existing numeric flags.
-- HTTP explicit zero behavior for model override numeric fields.
-- no raw API-key values are accepted or emitted.
-
-### Examples
-
-Update examples only if needed to keep them accurate and runnable.
-
-If adding an `extra_params` example, keep it secret-free and simple. Prefer a harmless provider-routing example over a vendor-specific feature that requires special credentials.
-
-### Verification
-
-Run:
-
-```bash
-go test ./...
-go run ./cmd/scriptorium render \
-  --config ./examples/config.yml \
-  --prompt generic.markdown_summary \
-  --input transcript=./examples/fixtures/transcript.md \
-  --input glossary=./examples/fixtures/glossary.yml \
-  --format json
-```
-
-## Final Checks
-
-Before considering the feature complete:
-
-1. Confirm `git diff` contains only intended code, test, doc, and example changes.
-2. Confirm all non-roadmap docs describe implemented behavior only.
-3. Confirm no output path exposes raw API key values.
-4. Confirm `go test ./...` passes.
-5. Confirm the render smoke command passes.
+- public error mapping retains collaborator identities while adding the active
+  operation's public category;
+- HTTP artifact MIME coverage uses a built-in media type while retaining the
+  unknown-extension fallback check;
+- the dependency guard recursively scans production adapter and formatter
+  sources and rejects descendants of forbidden framework package families; and
+- the final validation passed full and repeated tests, vet, a temporary-output
+  build, race checks, maintained examples, both maintained configuration files,
+  import and link inspection, and whitespace validation.

docs/roadmap/migration.md

@@ -0,0 +1,316 @@
+# Promptkit Migration Roadmap
+
+## Status
+
+Accepted plan. Steps 1 through 4 are complete. Steps 5 through 9 remain
+proposed and are not yet implemented.
+
+## Objective
+
+Split the current repository into two projects:
+
+- **Promptkit**: the reusable Go framework, public Go facade, execution engine,
+  source and validation support, OpenAI-compatible client, extension
+  interfaces, and built-in execution-profile registry.
+- **Scriptorium**: a slim runnable application that imports Promptkit and
+  provides the CLI and HTTP interfaces.
+
+Scriptorium will become another downstream Promptkit consumer rather than the
+owner of the framework.
+
+## Compatibility And Migration Policy
+
+This is an intentionally breaking change.
+
+- New and migrated Go consumers must import Promptkit instead of Scriptorium.
+- Scriptorium will not retain type aliases, forwarding packages, deprecated
+  facade APIs, or other source-compatibility shims.
+- Existing consumers may continue using a previously tagged Scriptorium module
+  version until they are migrated.
+- The migration does not need to preserve compatibility between intermediate
+  development states. Each completed phase must instead leave the affected
+  repository internally consistent and tested.
+- Promptkit should initially preserve the useful shape and behavior of the
+  current public Go facade where doing so reduces extraction risk. Broader API
+  redesign should follow the split unless required to establish the new
+  boundary.
+
+## Target Ownership
+
+Promptkit should own application-neutral framework behavior:
+
+- public engine, request, result, option, extension, and error APIs;
+- prompt-definition loading and rendering;
+- execution profiles, overlays, and the built-in profile registry;
+- artifact-loading interfaces and general-purpose `file` and `inline` support;
+- schema loading and output validation;
+- LLM client boundaries and the OpenAI-compatible implementation;
+- preparation and execution orchestration;
+- framework and execution defaults.
+
+Scriptorium should own executable and transport concerns:
+
+- the `scriptorium` command and its `run`, `render`, and `serve` interfaces;
+- CLI parsing, output formatting, exit codes, and process behavior;
+- application-config discovery and CLI precedence;
+- HTTP routing, request and response DTOs, limits, and error/status mapping;
+- HTTP artifact-root and deployment security policy;
+- server and adapter defaults;
+- executable examples, operations guidance, and transport documentation.
+
+The intended dependency direction is:
+
+```text
+Scriptorium CLI and HTTP adapters
+                |
+                v
+             Promptkit
+                |
+                v
+     consumer-supplied sources and clients
+```
+
+Scriptorium must use Promptkit's public API. It must not depend on Promptkit
+implementation packages or reproduce framework orchestration.
+
+## Migration Steps
+
+### Step 1: Refresh And Synchronize Documentation
+
+Perform a repository-wide documentation refresh before migration development.
+
+At minimum:
+
+- reconcile all current-behavior documentation with the code, tests, examples,
+  defaults, and current public contracts;
+- introduce the planned documentation-policy updates;
+- establish an architecture decision record policy and canonical ADR location;
+- resolve stale, duplicated, or misplaced material;
+- validate documentation links and maintained examples;
+- leave future migration behavior in `docs/roadmap/` until implemented.
+
+**Gate:** Do not begin architectural migration work until the documentation
+refresh and policy updates are merged and the repository has an agreed,
+accurate baseline.
+
+**Gate status:** Complete as of 2026-07-26. The completed documentation
+refresh, follow-up verification, and layered-timeout correction remain recorded
+in repository history. Step 1 remains complete after that validation.
+
+### Step 2: Record The Architectural Decision And Detailed Boundary
+
+Create an ADR, under the policy established in Step 1, that records:
+
+- the decision to split Promptkit from Scriptorium;
+- the target ownership and dependency direction;
+- the selected Promptkit repository and Go module paths;
+- the breaking-change and versioning policy;
+- ownership of configuration fields and defaults;
+- artifact-reader and HTTP containment responsibilities;
+- local multi-repository development and release coordination;
+- documentation ownership after the split.
+
+Use the ADR to resolve any remaining public-boundary decisions before code is
+moved.
+
+**Gate:** The ADR is accepted, and every existing package, public contract,
+configuration category, and maintained asset has a target owner.
+
+**Gate status:** Complete as of 2026-07-26.
+[ADR 0002: Split Promptkit From Scriptorium](../adr/0002-split-promptkit-from-scriptorium.md)
+is accepted and records the required ownership and coordination decisions.
+
+### Step 3: Characterize Existing Framework Behavior
+
+Strengthen or add contract-focused tests where needed so extraction can be
+verified without relying on package placement.
+
+The completed Step 3 gate records the accepted implementation scope and
+intended completion state.
+
+Preserve coverage of:
+
+- `Prepare` and `Run` behavior;
+- prompt, profile, execution-default, and request-override precedence;
+- presence-aware numeric overrides;
+- built-in profile fallback and custom-profile overlays;
+- strict YAML and JSON decoding;
+- prompt, profile, schema, and artifact source behavior;
+- structured-output requests and output validation;
+- validation failures versus validation runtime errors;
+- secret handling and redaction;
+- public error classification;
+- HTTP artifact restrictions and transport mappings.
+
+**Gate:** Current framework and adapter contracts are represented by passing
+tests sufficient to detect behavioral regressions during the split.
+
+**Gate status:** Complete as of 2026-07-27. The framework contract corpus,
+public `Engine` characterization, ownership audit, full test and vet suites,
+temporary executable build, and maintained offline examples passed. Step 4 is
+next.
+
+### Step 4: Make Scriptorium Adapters Consume The Public Facade
+
+Within the current repository, refactor the CLI and HTTP adapters to use the
+public framework facade rather than constructing or importing internal runner
+components directly.
+
+Add only the minimum public capabilities needed to support this boundary. These
+may include:
+
+- a small `Run`/`Prepare` consumer interface;
+- injectable artifact-reading behavior for Scriptorium's restricted HTTP
+  policy;
+- source options currently available only through internal constructors;
+- prepared-run formatting based on public types;
+- stable public error classification required by CLI and HTTP mappings.
+
+Do not broadly export internal repositories, domain types, or use-case
+implementations.
+
+**Gate:** The CLI and HTTP adapters use only the public framework API for
+framework behavior, and all tests and documented smoke commands pass.
+
+**Gate status:** Complete as of 2026-07-28. CLI `run`, `render`, and `serve`,
+the HTTP handler, and prepared-run formatting use the public facade; the
+restricted HTTP reader is injected through the public extension point. The
+post-implementation public-error, deterministic MIME, and recursive
+dependency-guard corrections passed full tests, vet, build, race checks,
+maintained examples, and configuration smoke checks. Step 5 repository
+creation is next.
+
+### Step 5: Create The Promptkit Repository
+
+Create the Promptkit repository and Go module as an explicit out-of-band
+operation.
+
+Establish:
+
+- repository access, ownership, and branch protections;
+- the module path selected by the ADR;
+- baseline development, architecture, documentation, and release policies;
+- CI for build, test, vet, and other agreed checks;
+- an initial package layout centered on a small public facade with internal
+  implementation packages;
+- a local development workflow for coordinated Promptkit and Scriptorium
+  changes, using a workspace or temporary uncommitted module replacement where
+  appropriate.
+
+Do not commit local filesystem `replace` directives to release branches.
+
+**Gate:** The Promptkit repository exists, is accessible to maintainers, has
+working CI and policy scaffolding, and can receive the extracted framework.
+Do not begin cross-repository extraction until this out-of-band work is
+confirmed complete.
+
+### Step 6: Extract And Stabilize Promptkit
+
+Move the application-neutral framework and built-in profile assets into
+Promptkit. Preserve implementation packages as internal where practical.
+
+The initial public API should remain focused on the established engine workflow
+and the source and client extension points required by real consumers. Avoid
+combining the extraction with unrelated API redesign.
+
+Move or recreate the relevant:
+
+- framework implementation;
+- public package tests and framework contract tests;
+- built-in profile assets and registry tests;
+- Go consumer examples;
+- framework, consumer, configuration-format, and integration documentation.
+
+Verify that Promptkit can be built, tested, and consumed independently of the
+Scriptorium repository.
+
+**Gate:** Promptkit independently provides the agreed framework contract,
+passes its CI checks, and has a tagged version that Scriptorium and other
+consumers can import.
+
+### Step 7: Slim Scriptorium And Adopt Promptkit
+
+Update Scriptorium to import the tagged Promptkit module and remove the
+framework implementation and public Go facade that Promptkit replaces.
+
+Retain only Scriptorium-owned executable and transport behavior. In particular:
+
+- wire CLI and HTTP requests through Promptkit's public API;
+- keep application config and transport defaults in Scriptorium;
+- keep restricted HTTP artifact policy in Scriptorium while injecting it
+  through Promptkit's supported boundary;
+- remove obsolete framework packages, tests, and documentation;
+- update Scriptorium examples and docs to describe the CLI and HTTP application;
+- direct Go framework consumers to Promptkit without providing compatibility
+  aliases or forwarding APIs.
+
+**Gate:** Scriptorium builds and passes all tests using a tagged Promptkit
+dependency, contains no duplicate framework implementation, and its current
+documentation describes only the slimmed application.
+
+### Step 8: Migrate Downstream Consumers To Promptkit
+
+Inventory downstream Go consumers and migrate each from the Scriptorium package
+to Promptkit. This work may occur in external repositories and must be tracked
+explicitly.
+
+For each consumer:
+
+- update module imports and dependencies;
+- adapt to any intentionally changed public API;
+- run its tests and relevant integration or smoke checks;
+- confirm configuration, source, validation, and error behavior;
+- release or deploy the migrated consumer through its normal process.
+
+Consumers that cannot migrate immediately may remain pinned to the last
+framework-bearing Scriptorium tag. No compatibility work is required in the new
+Scriptorium project for those consumers.
+
+**Gate:** All in-scope downstream consumers are either migrated and verified or
+explicitly recorded as remaining on the previous Scriptorium version with an
+owner and follow-up plan. Do not declare the ecosystem migration complete until
+the required out-of-band consumer changes are confirmed.
+
+### Step 9: Complete Release And Documentation Cutover
+
+Complete the coordinated project transition:
+
+- publish Promptkit before dependent Scriptorium releases;
+- release the breaking Scriptorium version against the tagged Promptkit
+  dependency;
+- publish migration guidance that maps the former Scriptorium Go API to
+  Promptkit;
+- update cross-project links, examples, package documentation, and release
+  notes;
+- verify that no release artifact depends on local workspaces or replacements;
+- archive completed roadmap material according to the documentation policy in
+  effect at that time.
+
+**Gate:** Promptkit and Scriptorium are independently releasable, their
+documentation has distinct and accurate ownership, and the migration status of
+all identified downstream consumers is recorded.
+
+## Cross-Cutting Constraints
+
+- Preserve the invariant that execution orchestration remains narrow and
+  application-neutral.
+- Keep adapter-specific decisions out of Promptkit.
+- Keep Scriptorium dependent only on Promptkit's supported public API.
+- Preserve strict external decoding, error classification, validation
+  semantics, and secret redaction throughout the migration.
+- Keep each repository buildable and testable at merged phase boundaries.
+- Coordinate cross-repository changes through tagged dependencies and explicit
+  gates rather than assuming atomic commits across repositories.
+- Document only implemented behavior outside roadmap files.
+
+## Completion Criteria
+
+The migration is complete when:
+
+- Promptkit is the independent owner of the reusable framework and built-in
+  profiles;
+- Scriptorium is a slim CLI and HTTP consumer of Promptkit;
+- Scriptorium no longer exposes or maintains the former public Go framework;
+- all required downstream migrations and external repository work have been
+  completed or explicitly dispositioned;
+- both repositories build, test, document, version, and release independently.

docs/roadmap/params.md

@@ -1,96 +0,0 @@
-# Runtime Parameter Feature Roadmap
-
-This roadmap defines the target behavior for runtime model parameters.
-
-Current behavior has two limitations:
-
-- `reasoning_effort` and `extra_params` are parsed into effective execution settings but are not serialized into outbound OpenAI-compatible chat-completions requests.
-- Per-request numeric execution overrides use zero-value merge semantics, so callers cannot reliably override a profile value with an explicit zero such as `temperature: 0`.
-
-The implementation plan for this feature lives in `docs/roadmap/implementation.md`.
-
-## Target State
-
-Scriptorium should preserve the existing separation between prompt definitions, execution profiles, and per-request execution overrides while making runtime parameter behavior explicit and predictable.
-
-Expected end state:
-
-- Effective execution settings remain visible in prepared-run output, run metadata, and HTTP metadata without exposing raw secret values.
-- `reasoning_effort` is treated as a first-class effective execution setting and is serialized to the outbound OpenAI-compatible request when set.
-- `extra_params` supports provider-specific OpenAI-compatible request fields.
-- `extra_params` is serialized as additional top-level outbound JSON fields.
-- `extra_params` values support JSON-compatible scalar, object, and array values.
-- `extra_params` cannot override first-class outbound request fields.
-- Per-request numeric overrides preserve caller intent, including explicit zero values.
-- Omitted per-request numeric overrides continue to inherit the selected profile and built-in defaults.
-- External decoding remains strict for config, prompt, profile, and HTTP request payloads.
-
-## Policy Decisions
-
-### `extra_params`
-
-`extra_params` should serialize as additional top-level outbound JSON fields in the OpenAI-compatible chat-completions request.
-
-Reasoning:
-
-Most OpenAI-compatible providers expose vendor-specific chat-completions parameters as top-level fields. This keeps Scriptorium's adapter compatible with that ecosystem without adding first-class fields for every provider option.
-
-`extra_params` must not silently override Scriptorium-owned fields. Reserved outbound fields include at least:
-
-- `model`
-- `session_id`
-- `messages`
-- `temperature`
-- `max_tokens`
-- `top_p`
-- `service_tier`
-- `reasoning_effort`
-- `response_format`
-
-If a caller supplies a reserved key through `extra_params`, Scriptorium should fail before making the outbound HTTP request.
-
-`extra_params` should use JSON-compatible values rather than only strings.
-
-Reasoning:
-
-Provider-specific parameters commonly need booleans, numbers, objects, or arrays. String-only values would force awkward encoding and would likely require a later compatibility break.
-
-### Presence-Aware Overrides
-
-Per-request execution overrides should use a presence-aware type with pointer fields for optional numeric values.
-
-Reasoning:
-
-The resolved execution target should remain a concrete value used by prepared runs, generated requests, and metadata. Optionality matters at the request boundary, not after the runner has resolved the effective target.
-
-This keeps adapter and merge logic precise while avoiding nil checks in formatter, metadata, and LLM serialization paths.
-
-## Scope
-
-In scope:
-
-- Runtime merge behavior for per-request execution overrides.
-- HTTP model override decoding for explicit zero numeric values.
-- CLI execution override handling for explicit zero numeric flags.
-- Outbound serialization of `reasoning_effort`.
-- Outbound serialization of JSON-compatible `extra_params`.
-- Tests and documentation for the changed implemented behavior.
-
-Out of scope:
-
-- Expanding the HTTP API beyond `POST /v1/runs`.
-- Adding built-in HTTP authentication or authorization.
-- Adding durable run state, run history, or multi-step orchestration.
-- Adding broad provider-specific adapter packages.
-- Adding new CLI flags for every provider-specific parameter.
-
-## Acceptance Criteria
-
-- A profile containing `reasoning_effort: medium` produces an outbound request with `reasoning_effort`.
-- HTTP callers can pass `reasoning_effort` through the existing `model` override object and have it appear outbound.
-- A profile or HTTP request containing JSON-compatible `extra_params` produces outbound top-level JSON fields according to the reserved-field policy.
-- Reserved `extra_params` collisions fail before the outbound provider call.
-- CLI callers can pass `--temperature 0` and observe `temperature: 0` in rendered/effective settings and outbound requests.
-- HTTP callers can send `"temperature": 0` and observe the same behavior.
-- Omitting `temperature` continues to preserve the selected profile/default value.
-- Raw API key values remain unsupported in config, profiles, CLI flags, HTTP payloads, logs, and rendered output.

docs/roadmap/step4.md

@@ -0,0 +1,386 @@
+# Migration Step 4: Public-Facade Adapter Boundary
+
+## Status
+
+Complete as of 2026-07-28. The public-facade adapter boundary and its
+post-implementation error-classification, MIME-test, and dependency-guard
+corrections are validated. The [implementation plan](implementation.md)
+records the completed work, and the [main migration roadmap](migration.md)
+identifies repository creation as the next gate.
+
+## Purpose
+
+Make Scriptorium's CLI and HTTP adapters genuine consumers of the public
+framework facade before that facade moves to Promptkit. This establishes and
+tests the dependency boundary inside the current repository, where it can be
+changed atomically, before the framework and application are separated across
+repositories.
+
+The [accepted split decision](../adr/0002-split-promptkit-from-scriptorium.md)
+owns the long-term project boundary. The
+[main migration roadmap](migration.md) owns the overall sequence. This feature
+roadmap defines the desired Step 4 state, not an implementation sequence.
+
+## Achieved Boundary
+
+The CLI, HTTP handler, and prepared-run formatter now consume public engine
+values and errors. `serve` injects Scriptorium's HTTP-owned restricted artifact
+reader through the public extension point, while the root facade continues to
+compose the framework implementation inside this repository. A repository-level
+dependency test recursively protects production adapter and formatter packages
+from framework-owned imports.
+
+## Target State
+
+Scriptorium's executable path is an ordinary consumer of the same public
+framework boundary used by other Go applications:
+
+```text
+cmd/scriptorium
+       |
+       v
+Scriptorium CLI and HTTP adapters
+       |
+       v
+public Engine, requests, results, errors, and extension interfaces
+       |
+       v
+framework implementation packages
+```
+
+The CLI and HTTP production packages do not import framework-owned internal
+packages. They translate application configuration, flags, and HTTP DTOs into
+public engine configuration and request values; call `Prepare` or `Run`; and
+translate public results and errors back into their owned interfaces.
+
+The root facade may continue to use the existing internal implementation during
+Step 4. That implementation moves in later migration steps. The important
+result here is that no Scriptorium-owned adapter or presentation component
+depends on it directly.
+
+## Public Facade Requirements
+
+### Engine Consumption
+
+The current public `Engine`, `Config`, `RunRequest`, `PreparedRun`,
+`RunResult`, request helpers, result values, and existing broad error sentinels
+remain the primary boundary. Step 4 must not introduce a second facade,
+adapter-specific engine, exported internal runner, or public repository
+constructor.
+
+Scriptorium-local interfaces may abstract the methods an adapter needs for test
+substitution. They must:
+
+- be declared on the consuming side;
+- use only public facade types;
+- contain only `Prepare`, `Run`, or the narrower subset required by that
+  consumer; and
+- be satisfied directly by `*Engine`.
+
+Promptkit must not acquire CLI, HTTP, status-code, or response-format concepts
+to satisfy these interfaces.
+
+### Artifact Reader Extension
+
+The public facade will expose the demonstrated artifact-loading extension point:
+
+```go
+type ArtifactReader interface {
+    Read(context.Context, ArtifactRef) (*Artifact, error)
+}
+
+func WithArtifactReader(ArtifactReader) Option
+```
+
+This option replaces the engine's ordinary composite artifact reader for all
+input references. The default remains the framework's ordinary inline and
+caller-selected file behavior.
+
+The boundary must have the same defensive behavior as other public injection
+points:
+
+- a nil reader is rejected as `ErrInvalidConfig`;
+- a reader response of `(nil, nil)` becomes `ErrArtifactLoad` rather than
+  causing a panic;
+- reader failures are wrapped as `ErrArtifactLoad` while retaining the
+  original error identity for `errors.Is`;
+- conversion between public and internal values does not expose internal domain
+  types; and
+- mutable artifact content is copied across the boundary where needed to avoid
+  unintended aliasing.
+
+This is the only new framework extension interface required by Step 4. No
+public prompt repository, profile repository, renderer, validator, or internal
+runner interface is needed for the current adapters.
+
+### Public Error Detail
+
+The facade's existing broad errors remain authoritative for general consumers.
+To preserve Scriptorium's current HTTP contract without inspecting Promptkit
+internals, the public error chain must additionally retain stable identities
+for:
+
+- profile selection being required because neither the request nor the prompt
+  supplies a profile; and
+- a selected credential environment variable being unset or empty.
+
+These identities will be exposed as `ErrProfileRequired` and
+`ErrAPIKeyEnvMissing`. Each remains nested under `ErrInvalidRequest`, so callers
+that need only the broad category continue to match it. Scriptorium uses the
+more specific identities only to preserve its existing HTTP error codes.
+
+No error-string parsing is permitted. Prompt, profile, artifact, render,
+generation, and validation failures continue to use the existing public
+sentinels. Scriptorium-owned HTTP artifact-policy errors remain in Scriptorium
+and survive wrapping through the public artifact-reader boundary.
+
+## CLI Boundary
+
+The `run` and `render` commands will construct the public engine from resolved
+application settings:
+
+- `prompt_dir`, `profile_dir`, and `schema_dir` map to public engine
+  configuration;
+- the public engine supplies the built-in profile registry, renderer,
+  validator, ordinary artifact reader, and default OpenAI-compatible client;
+- CLI input paths map to public file artifact references;
+- CLI runtime flags map to the public request override while preserving
+  numeric presence, including explicit zero; and
+- omitted application values remain omitted so framework defaults are not
+  duplicated in Scriptorium.
+
+`run` consumes the public result for artifact output, validation exit status,
+and the stderr summary. `render` consumes the public prepared value. The
+Scriptorium-owned prepared-run formatter will accept public prepared values
+instead of internal domain values without changing its text or JSON contract.
+
+The `serve` command will construct the same public engine with Scriptorium's
+restricted artifact reader injected through `WithArtifactReader`. It will pass
+that engine to the HTTP handler through a Scriptorium-local run interface.
+
+CLI construction must handle public engine-construction errors explicitly.
+The executable must not construct an internal LLM client, repository, renderer,
+validator, artifact reader, or runner.
+
+## HTTP Boundary
+
+The HTTP handler's consumer interface will accept public `RunRequest` values
+and return public `RunResult` values. DTO mapping will preserve the existing
+HTTP contract:
+
+- strict JSON decoding and request-size enforcement remain in Scriptorium;
+- prompt, profile, input, variable, and execution-override fields map to their
+  corresponding public values;
+- pointer-valued numeric overrides retain omitted-versus-explicit-zero
+  semantics;
+- raw API keys remain absent from the HTTP request shape;
+- public run results map to the current response DTOs;
+- raw model output remains opt-in; and
+- response-size enforcement remains an HTTP concern.
+
+HTTP error mapping will inspect only:
+
+- public framework errors;
+- Scriptorium's HTTP artifact-policy errors; and
+- standard-library transport errors owned by the handler.
+
+It will not inspect internal prompt, profile, artifact, domain, or use-case
+errors. Existing HTTP statuses, error codes, and sanitized messages remain
+unchanged.
+
+## HTTP Artifact Policy
+
+The restricted artifact reader remains Scriptorium-owned and becomes an
+implementation of the public `ArtifactReader` interface. It belongs with the
+HTTP adapter rather than the Promptkit-destined general artifact package.
+
+The reader will continue to:
+
+- resolve inline references without permitting empty inline bodies;
+- deny file references when no artifact root is configured;
+- enforce the configured maximum artifact size;
+- enforce the documented lexical root-containment rule without resolving
+  symlinks;
+- return complete public artifact metadata; and
+- preserve distinct Scriptorium errors for a denied or out-of-root file and an
+  oversized file.
+
+The public engine treats those errors as artifact-load failures while preserving
+their identities. The HTTP mapper checks the Scriptorium-specific identity
+before the broad public `ErrArtifactLoad` identity, retaining the current
+`artifact_not_allowed`, `artifact_too_large`, and general artifact-read
+outcomes.
+
+General inline and unrestricted file reading remains framework-owned. Step 4
+separates the HTTP policy from that implementation far enough that each side
+can later move to its target repository without redesigning the interface.
+
+## Package And Dependency Boundaries
+
+The completed dependency state is:
+
+| Component | Permitted framework dependency |
+| --- | --- |
+| `internal/adapter/cli` | Public facade types, constructors, options, errors, and methods only |
+| `internal/adapter/http` | Public facade types and errors only; Scriptorium-owned HTTP artifact policy remains local |
+| `internal/format` | Public prepared-run and rendered-message values only |
+| `internal/config` | Scriptorium application settings and Scriptorium-owned defaults; no framework orchestration |
+| `cmd/scriptorium` | CLI adapter only |
+| Root facade | Existing internal framework implementation until extraction |
+
+In particular, Scriptorium-owned adapter, formatter, and HTTP artifact-policy
+production files must not import:
+
+- `internal/domain`;
+- `internal/usecase`;
+- `internal/promptdef` or `internal/prompt`;
+- `internal/profile` or `internal/profile/builtin`;
+- `internal/validate`;
+- `internal/llm`; or
+- the Promptkit-destined general artifact implementation.
+
+Tests for Scriptorium-owned components should follow the same public boundary
+except when directly testing a Scriptorium-owned package.
+
+## Observable Behavior
+
+Step 4 is an architectural refactor plus the minimum additive public extension
+surface required to support it. It is not a redesign of the executable
+interfaces.
+
+The following behavior must remain unchanged:
+
+- CLI commands, flags, aliases, precedence, output routing, summaries, and exit
+  codes;
+- application configuration discovery, strict decoding, fields, and defaults;
+- HTTP routes, strict decoding, DTOs, statuses, codes, messages, and limits;
+- HTTP artifact containment and size enforcement;
+- prompt/profile selection and override precedence;
+- explicit numeric-zero behavior;
+- built-in profile fallback and custom-profile overlays;
+- structured-output and validation behavior;
+- timeout layering;
+- secret handling and redaction; and
+- maintained executable examples.
+
+The intended public additions are limited to artifact-reader injection and the
+specific error identities required by the HTTP mapper. No compatibility shim is
+needed because this repository still owns the facade during Step 4 and the
+overall migration is intentionally breaking.
+
+## Test Ownership And Verification
+
+Tests will protect the boundary at the layer that owns each risk:
+
+- public engine tests own artifact-reader option validation, conversion,
+  invocation, nil-response handling, error wrapping, and error identity;
+- CLI tests own flag and configuration mapping into public requests, public
+  engine wiring, presentation, output, and exit behavior;
+- HTTP tests own strict DTO mapping to public requests, public result mapping,
+  error/status mapping, limits, and raw-output opt-in;
+- HTTP artifact-reader tests own denied, contained, escaped, oversized, inline,
+  cancellation, and metadata behavior;
+- formatter tests own stable text and JSON presentation of public prepared
+  values; and
+- existing framework tests continue to own orchestration, source, validation,
+  provider, and broad public error behavior.
+
+Adapter tests that currently construct internal runners or assert internal
+sentinels will be rewritten against the public engine or small public-typed
+fakes. Duplicate framework-semantic assertions should be removed when the
+public contract suite already owns the risk.
+
+The final suite must include an enforceable dependency check showing that
+Scriptorium-owned adapter and presentation production packages do not import
+Promptkit-destined internal packages. This may be a focused architecture test
+or an equivalent deterministic repository check; it must diagnose the
+forbidden import clearly.
+
+## Documentation Outcome
+
+When the boundary is implemented, current-behavior documentation will be
+reconciled in the same change:
+
+- the public Go package contract will define `ArtifactReader`,
+  `WithArtifactReader`, and the new error identities;
+- adapter internals will describe public-engine composition and public-value
+  mapping;
+- source internals will distinguish the public reader extension, general
+  framework readers, and Scriptorium's HTTP reader;
+- the internal overview and architecture policy will reflect that executable
+  adapters consume the public facade; and
+- CLI, configuration, HTTP, integration, and operations contracts will change
+  only if verification finds an observable correction is necessary.
+
+Documents will keep exact external contracts in their existing canonical
+owners and link rather than duplicate them.
+
+## Required Validation Outcome
+
+The completed boundary must pass:
+
+- the full Go test suite;
+- `go vet` across all packages;
+- a temporary-output executable build;
+- repeated public artifact-reader and adapter boundary tests;
+- both maintained application configurations;
+- maintained render, HTTP-request, and Go-package examples;
+- CLI and HTTP smoke checks that exercise the public engine path;
+- the forbidden-import dependency check;
+- local Markdown-link validation; and
+- whitespace validation.
+
+All default validation remains offline, deterministic, and independent of real
+credentials.
+
+## Out Of Scope
+
+Step 4 does not:
+
+- create the Promptkit repository or module;
+- change the module or root package name;
+- move framework implementation packages or built-in profiles out of this
+  repository;
+- remove the current root facade;
+- add compatibility aliases or forwarding packages;
+- make Scriptorium depend on an external Promptkit revision;
+- broadly export framework repositories, domain values, validators, renderers,
+  or runner constructors;
+- redesign prompt, profile, schema, request, response, CLI, or configuration
+  formats;
+- change HTTP containment from lexical path checking to symlink resolution;
+- add new execution or repair behavior; or
+- perform unrelated facade cleanup.
+
+Those changes belong to later migration steps or a separately accepted feature.
+
+## Completion Criteria
+
+Step 4 is complete when:
+
+- CLI `run` and `render` execute through the public engine;
+- CLI `serve` injects the Scriptorium-owned restricted reader into the public
+  engine and passes that engine to the HTTP handler;
+- HTTP and CLI map only public framework request, result, and error values;
+- prepared-run formatting consumes the public prepared value;
+- the public artifact-reader extension has the specified validation,
+  conversion, nil-response, and error-preservation behavior;
+- public error identities preserve every distinction required by the current
+  HTTP contract;
+- Scriptorium-owned adapters, formatter, and HTTP artifact reader have no
+  Promptkit-destined internal imports;
+- HTTP containment, limits, error mapping, and all existing executable
+  behavior remain protected by passing tests;
+- current-behavior documentation reflects the implemented boundary;
+- every required validation check passes;
+- no out-of-scope extraction or compatibility work is included; and
+- the main migration roadmap records Step 4 as complete and identifies
+  repository creation in Step 5 as the next gate.
+
+Migration Step 5 must not begin until these criteria are satisfied.
+
+## Lifecycle
+
+This feature roadmap is a temporary migration artifact. It may be removed after
+Step 4 is complete and no longer needs to guide active work; repository history
+will retain the decision and completion record.

docs/troubleshooting.md

@@ -1,367 +0,0 @@
-# Troubleshooting
-
-This guide lists recurring implemented failure modes and safe fixes.
-
-For command syntax, see [CLI reference](cli.md). For configuration and file formats, see [Configuration reference](config.md). For operational behavior, see [Operations guide](operations.md).
-
-## Missing Or Invalid Config File
-
-Symptom:
-
-- CLI errors such as `application config error: config file not found` or `invalid config YAML`.
-
-Likely cause:
-
-- `--config` points to a missing file.
-- Config YAML has syntax errors or unknown fields.
-
-Diagnostic step:
-
-```bash
-go run ./cmd/scriptorium render --config /path/to/config.yml --prompt generic.markdown_summary --input transcript=./examples/fixtures/transcript.md --input glossary=./examples/fixtures/glossary.yml
-```
-
-Safe fix:
-
-- Correct file path.
-- Remove unknown fields.
-- Fix YAML syntax.
-- Keep secrets out of config.
-
-Relevant links:
-
-- [Configuration reference](config.md)
-- [CLI reference](cli.md)
-
-## Missing Prompt/Profile Directory Settings
-
-Symptom:
-
-- CLI parse errors saying prompt directory or profile directory is required.
-
-Likely cause:
-
-- Neither CLI flags nor config provide effective `prompt_dir` / `profile_dir`.
-
-Diagnostic step:
-
-- Run the failing command with explicit `--prompt-dir` and `--profile-dir` once to verify.
-
-Safe fix:
-
-- Set `prompt_dir` and `profile_dir` in config, or always pass both flags.
-
-Relevant links:
-
-- [Configuration reference](config.md)
-- [CLI reference](cli.md)
-
-## Unknown Or Unsupported Flags
-
-Symptom:
-
-- CLI parse error for an unknown flag.
-
-Likely cause:
-
-- Typo or command mismatch (for example, `serve` with runtime model override flags).
-
-Diagnostic step:
-
-- Compare command against the command-specific flag list.
-
-Safe fix:
-
-- Remove unsupported flags.
-- Use `run`/`render` for runtime model overrides.
-
-Relevant links:
-
-- [CLI reference](cli.md)
-
-## Prompt Definition Load Failures
-
-Symptom:
-
-- CLI run/render error from prompt loading.
-- HTTP `404 prompt_not_found` or `400 prompt_load_failed`.
-
-Likely cause:
-
-- Prompt ID not found.
-- Invalid prompt YAML.
-- Invalid prompt contract (for example bad validation mode, message content/content_file rule violation, missing schema path for `json_schema`).
-
-Diagnostic step:
-
-```bash
-go run ./cmd/scriptorium render --config ./examples/config.yml --prompt <prompt-id> --input transcript=./examples/fixtures/transcript.md --input glossary=./examples/fixtures/glossary.yml --format json
-```
-
-Safe fix:
-
-- Correct prompt ID.
-- Fix prompt YAML and contract fields.
-- Ensure referenced `content_file` paths exist.
-
-Relevant links:
-
-- [Configuration reference](config.md)
-- [CLI reference](cli.md)
-
-## Profile Definition Load Failures
-
-Symptom:
-
-- CLI run/render error from profile loading.
-- HTTP `404 profile_not_found` or `400 profile_load_failed`.
-
-Likely cause:
-
-- Profile ID missing/not found.
-- Invalid profile YAML.
-- Invalid profile values.
-- Raw `api_key` field present (rejected).
-
-Diagnostic step:
-
-```bash
-go run ./cmd/scriptorium render --config ./examples/config.yml --prompt generic.markdown_summary --profile <profile-id> --input transcript=./examples/fixtures/transcript.md --input glossary=./examples/fixtures/glossary.yml
-```
-
-Safe fix:
-
-- Correct profile ID.
-- Fix profile YAML and value ranges.
-- Replace `api_key` with `api_key_env`.
-
-Relevant links:
-
-- [Configuration reference](config.md)
-- [CLI reference](cli.md)
-
-## Input Artifact Read Failures
-
-Symptom:
-
-- CLI run/render error reading input artifacts.
-- HTTP `400 artifact_read_failed`.
-
-Likely cause:
-
-- File path in input mapping does not exist or is unreadable.
-- Unsupported artifact reference type in HTTP request.
-
-Diagnostic step:
-
-- Verify every mapped file path exists and is readable by the process.
-- For HTTP, verify each input uses supported `type` values.
-
-Safe fix:
-
-- Correct file paths and permissions.
-- Use supported input types (`file`, `inline`).
-
-Relevant links:
-
-- [CLI reference](cli.md)
-- [Configuration reference](config.md)
-
-## Prompt Template Render Failures
-
-Symptom:
-
-- CLI run/render error from prompt rendering.
-- HTTP `400 prompt_render_failed`.
-
-Likely cause:
-
-- Template references missing input names.
-- Template syntax or data reference issues.
-
-Diagnostic step:
-
-- Run `render --format json` with the same prompt, inputs, vars, and profile selection.
-
-Safe fix:
-
-- Align template `{{input "name"}}` references with actual input mappings.
-- Fix template syntax and variable names.
-
-Relevant links:
-
-- [CLI reference](cli.md)
-- [Configuration reference](config.md)
-
-## Missing API-Key Environment Variable
-
-Symptom:
-
-- CLI run/render invalid request error about missing API-key environment variable.
-- HTTP `400 api_key_env_missing`.
-
-Likely cause:
-
-- Selected profile or override sets `api_key_env`, but that environment variable is unset/empty.
-
-Diagnostic step:
-
-```bash
-printenv SCRIPTORIUM_API_KEY
-```
-
-Safe fix:
-
-- Set the required environment variable before invoking CLI/service.
-- Or use a profile that does not require API key auth for the target endpoint.
-
-Relevant links:
-
-- [Configuration reference](config.md)
-- [Operations guide](operations.md)
-
-## LLM Request Failures
-
-Symptom:
-
-- CLI `run` fails with LLM generation errors.
-- HTTP returns `502 llm_failed`.
-
-Likely cause:
-
-- Endpoint unreachable.
-- Non-2xx response from provider.
-- Timeout.
-- Malformed provider response.
-
-Diagnostic step:
-
-- Confirm endpoint URL and model in selected profile/overrides.
-- Retry with `render` first to confirm pre-LLM preparation works.
-- Check provider/network logs for non-2xx responses and timeouts.
-
-Safe fix:
-
-- Correct endpoint/model settings.
-- Adjust timeout if needed.
-- Resolve provider-side or network issues.
-
-Relevant links:
-
-- [CLI reference](cli.md)
-- [Configuration reference](config.md)
-- [Operations guide](operations.md)
-
-## Prompt Cache Misses Or No Cache Usage
-
-Symptom:
-
-- CLI run summary omits `cached_tokens` / `cache_write_tokens`.
-- HTTP `metadata.usage.cached_tokens` and `metadata.usage.cache_write_tokens` are both `0`.
-- Provider cost or latency does not improve after repeated similar runs.
-
-Likely cause:
-
-- The selected prompt has no `messages[].cache_control`.
-- Dynamic per-run input appears before the cache-controlled message and changes the provider cache key.
-- The provider does not support the serialized cache-control shape for the selected model.
-- The provider imposes minimum token thresholds or cache-breakpoint limits.
-
-Diagnostic step:
-
-- Run `render --format json` and verify the intended rendered message includes `cache_control`.
-- Confirm stable reusable context appears before the cache-controlled message, with dynamic input after it.
-- Check provider docs/logs for model support, minimum token thresholds, and breakpoint limits.
-
-Safe fix:
-
-- Move stable reusable context before the cache-controlled message.
-- Move highly dynamic input after the cache breakpoint.
-- Keep `cache_control.type: ephemeral` and, when using `ttl`, set `ttl: 1h`.
-- Use CLI cache counters or HTTP cache usage fields to verify cache reads/writes after rerunning.
-
-Relevant links:
-
-- [Configuration reference](config.md)
-- [OpenAI-compatible chat integration](integrations/openai-compatible-chat.md)
-
-## Validation Status Failed (`run` Exit 2 Or HTTP 200 With Failed Status)
-
-Symptom:
-
-- CLI exits with code `2`.
-- HTTP returns `200`, but `validation.status` is `failed`.
-
-Likely cause:
-
-- Generated output failed `basic`, `json`, or `json_schema` content validation.
-
-Diagnostic step:
-
-- Inspect validation mode and validation errors in CLI summary/HTTP response.
-
-Safe fix:
-
-- Refine prompt constraints.
-- Tighten schema or adjust model/profile settings.
-- Rerun after correction.
-
-Relevant links:
-
-- [Configuration reference](config.md)
-- [Operations guide](operations.md)
-
-## Validation Runtime Failure
-
-Symptom:
-
-- CLI `run` fails with validation runtime error.
-- HTTP returns `500 validation_runtime_failed`.
-
-Likely cause:
-
-- `json_schema` schema file missing/inaccessible.
-- Invalid schema JSON document.
-
-Diagnostic step:
-
-- Verify `schema_dir` and `output.schema_path` resolution.
-- Check schema file readability and valid JSON syntax.
-
-Safe fix:
-
-- Correct schema path.
-- Fix schema JSON content.
-- Rerun.
-
-Relevant links:
-
-- [Configuration reference](config.md)
-- [Operations guide](operations.md)
-
-## HTTP Request Parsing/Contract Errors
-
-Symptom:
-
-- HTTP `400 invalid_json` or `400 invalid_request`.
-
-Likely cause:
-
-- Malformed JSON body.
-- Unknown JSON fields.
-- Missing required `prompt_id` or `inputs`.
-
-Diagnostic step:
-
-- Revalidate request JSON.
-- Confirm required request fields are present.
-
-Safe fix:
-
-- Send valid JSON with only supported fields.
-- Ensure `prompt_id` and at least one input mapping are included.
-
-Relevant links:
-
-- [Operations guide](operations.md)
-- [CLI reference](cli.md)

engine.go

@@ -0,0 +1,343 @@
+package scriptorium
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io/fs"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	artifactadapter "gitea.maximumdirect.net/eric/scriptorium/internal/artifact"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/llm"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/profile/builtin"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/prompt"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/promptdef"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/usecase"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/validate"
+)
+
+// ErrInvalidConfig indicates invalid public engine configuration.
+var ErrInvalidConfig = errors.New("invalid engine configuration")
+
+var (
+	ErrInvalidRequest   = errors.New("invalid run request")
+	ErrPromptNotFound   = errors.New("prompt not found")
+	ErrProfileNotFound  = errors.New("profile not found")
+	ErrProfileRequired  = errors.New("profile selection is required")
+	ErrPromptLoad       = errors.New("failed to load prompt definition")
+	ErrProfileLoad      = errors.New("failed to load execution profile")
+	ErrAPIKeyEnvMissing = errors.New("api_key_env points to an unset environment variable")
+	ErrArtifactLoad     = errors.New("failed to load artifact")
+	ErrPromptRender     = errors.New("failed to render prompt")
+	ErrLLMGenerate      = errors.New("failed to generate output")
+	ErrValidation       = errors.New("failed to validate output")
+)
+
+// Engine prepares and runs Scriptorium prompt requests.
+type Engine struct {
+	runner *usecase.Runner
+}
+
+// Config configures a public Scriptorium engine.
+type Config struct {
+	PromptDir  string
+	ProfileDir string
+	SchemaDir  string
+	// Timeout is the transport-wide safety cap for the built-in LLM client
+	// when HTTPClient is absent or has a non-positive timeout.
+	Timeout time.Duration
+	// HTTPClient is cloned for the built-in LLM client. Its positive Timeout
+	// takes precedence over Config.Timeout as the transport-wide safety cap.
+	HTTPClient *http.Client
+}
+
+// Option customizes engine construction.
+type Option interface {
+	apply(*engineOptions) error
+}
+
+type optionFunc func(*engineOptions) error
+
+func (f optionFunc) apply(options *engineOptions) error {
+	return f(options)
+}
+
+type engineOptions struct {
+	llmClient       llm.Client
+	artifactReader  artifactadapter.Reader
+	promptDefs      promptdef.Repository
+	profiles        profile.Repository
+	memoryProfiles  profile.Repository
+	validator       validate.Validator
+	promptSource    bool
+	profileSource   bool
+	memorySource    bool
+	validatorSource bool
+	artifactSource  bool
+}
+
+// WithLLMClient injects a custom LLM client for execution.
+func WithLLMClient(client LLMClient) Option {
+	return optionFunc(func(options *engineOptions) error {
+		if client == nil {
+			return ErrInvalidConfig
+		}
+		options.llmClient = publicLLMClientAdapter{client: client}
+		return nil
+	})
+}
+
+// WithArtifactReader injects a reader for every input artifact reference.
+func WithArtifactReader(reader ArtifactReader) Option {
+	return optionFunc(func(options *engineOptions) error {
+		if reader == nil {
+			return ErrInvalidConfig
+		}
+		options.artifactReader = publicArtifactReaderAdapter{reader: reader}
+		options.artifactSource = true
+		return nil
+	})
+}
+
+// WithPromptFS loads prompt definitions from fsys under root.
+//
+// The source uses the same strict prompt YAML rules as configured prompt
+// directories, and prompt content_file paths resolve within this source.
+func WithPromptFS(fsys fs.FS, root string) Option {
+	return optionFunc(func(options *engineOptions) error {
+		if fsys == nil {
+			return ErrInvalidConfig
+		}
+		if strings.TrimSpace(root) == "" {
+			return ErrInvalidConfig
+		}
+		options.promptDefs = promptdef.NewFSRepository(fsys, root)
+		options.promptSource = true
+		return nil
+	})
+}
+
+// WithPromptFile loads prompt definitions from the single prompt file at path.
+//
+// Relative prompt content_file paths resolve from the file's directory.
+func WithPromptFile(path string) Option {
+	return optionFunc(func(options *engineOptions) error {
+		fsys, root, err := fileSource(path)
+		if err != nil {
+			return err
+		}
+		options.promptDefs = promptdef.NewFSRepository(fsys, root)
+		options.promptSource = true
+		return nil
+	})
+}
+
+// WithProfileFS loads execution profiles from fsys under root.
+//
+// Profiles from this source overlay built-in profiles. Profile YAML must use
+// api_key_env for environment-based credentials; raw API keys are rejected.
+func WithProfileFS(fsys fs.FS, root string) Option {
+	return optionFunc(func(options *engineOptions) error {
+		if fsys == nil {
+			return ErrInvalidConfig
+		}
+		if strings.TrimSpace(root) == "" {
+			return ErrInvalidConfig
+		}
+		options.profiles = profile.NewFSRepository(fsys, root)
+		options.profileSource = true
+		return nil
+	})
+}
+
+// WithProfileFile loads execution profiles from the single profile file at path.
+//
+// The profile overlays built-in profiles. Profile YAML must use api_key_env for
+// environment-based credentials; raw API keys are rejected.
+func WithProfileFile(path string) Option {
+	return optionFunc(func(options *engineOptions) error {
+		fsys, root, err := fileSource(path)
+		if err != nil {
+			return err
+		}
+		options.profiles = profile.NewFSRepository(fsys, root)
+		options.profileSource = true
+		return nil
+	})
+}
+
+// WithProfiles configures in-memory profiles that take precedence over
+// configured profile files and built-in profiles.
+func WithProfiles(profiles ...Profile) Option {
+	return optionFunc(func(options *engineOptions) error {
+		repo, err := newMemoryProfileRepository(profiles)
+		if err != nil {
+			return err
+		}
+		options.memoryProfiles = repo
+		options.memorySource = true
+		return nil
+	})
+}
+
+// WithSchemaFS loads JSON Schema documents from fsys under root.
+//
+// Prompt schema_path values resolve within this source when schema validation
+// or structured output is requested.
+func WithSchemaFS(fsys fs.FS, root string) Option {
+	return optionFunc(func(options *engineOptions) error {
+		if fsys == nil {
+			return ErrInvalidConfig
+		}
+		if strings.TrimSpace(root) == "" {
+			return ErrInvalidConfig
+		}
+		options.validator = validate.NewFSValidator(fsys, root)
+		options.validatorSource = true
+		return nil
+	})
+}
+
+// WithSchemaFile loads JSON Schema documents from the single schema file at path.
+//
+// Prompt schema_path values refer to the file's base name.
+func WithSchemaFile(path string) Option {
+	return optionFunc(func(options *engineOptions) error {
+		fsys, root, err := fileSource(path)
+		if err != nil {
+			return err
+		}
+		options.validator = validate.NewFSValidator(fsys, root)
+		options.validatorSource = true
+		return nil
+	})
+}
+
+// NewEngine constructs an Engine using the same default internal components as
+// the CLI and HTTP adapters.
+func NewEngine(cfg Config, opts ...Option) (*Engine, error) {
+	var options engineOptions
+	for _, opt := range opts {
+		if opt == nil {
+			continue
+		}
+		if err := opt.apply(&options); err != nil {
+			return nil, fmt.Errorf("%w: %v", ErrInvalidConfig, err)
+		}
+	}
+
+	promptDefs := options.promptDefs
+	if !options.promptSource {
+		if strings.TrimSpace(cfg.PromptDir) == "" {
+			return nil, fmt.Errorf("%w: prompt directory is required", ErrInvalidConfig)
+		}
+		promptDefs = promptdef.NewFilesystemRepository(cfg.PromptDir)
+	}
+
+	profiles := builtin.NewRepositoryWithDirectory(cfg.ProfileDir)
+	if options.profileSource {
+		profiles = builtin.NewRepositoryWithPrimary(options.profiles)
+	}
+	if options.memorySource {
+		profiles = profile.NewOverlayRepository(options.memoryProfiles, profiles)
+	}
+
+	validator := options.validator
+	if !options.validatorSource {
+		schemaDir := cfg.SchemaDir
+		if strings.TrimSpace(schemaDir) == "" {
+			schemaDir = defaults.SchemaDirDefault
+		}
+		validator = validate.NewStandardValidator(schemaDir)
+	}
+
+	llmClient := options.llmClient
+	if llmClient == nil {
+		var err error
+		llmClient, err = llm.NewOpenAICompatibleClient(llm.OpenAICompatibleConfig{
+			Timeout:    cfg.Timeout,
+			HTTPClient: cfg.HTTPClient,
+		})
+		if err != nil {
+			return nil, fmt.Errorf("%w: %v", ErrInvalidConfig, err)
+		}
+	}
+
+	artifacts := options.artifactReader
+	if !options.artifactSource {
+		artifacts = artifactadapter.NewCompositeReader()
+	}
+
+	return &Engine{
+		runner: usecase.NewRunner(
+			promptDefs,
+			profiles,
+			artifacts,
+			prompt.NewGoRenderer(),
+			llmClient,
+			validator,
+		),
+	}, nil
+}
+
+func fileSource(name string) (fs.FS, string, error) {
+	cleanName := strings.TrimSpace(name)
+	if cleanName == "" {
+		return nil, "", ErrInvalidConfig
+	}
+	dir := filepath.Dir(cleanName)
+	base := filepath.Base(cleanName)
+	if base == "." || base == string(filepath.Separator) || strings.TrimSpace(base) == "" {
+		return nil, "", ErrInvalidConfig
+	}
+	info, err := os.Stat(cleanName)
+	if err != nil {
+		return nil, "", fmt.Errorf("%w: failed to access source file %q: %v", ErrInvalidConfig, cleanName, err)
+	}
+	if info.IsDir() {
+		return nil, "", fmt.Errorf("%w: source path %q must be a file", ErrInvalidConfig, cleanName)
+	}
+	return os.DirFS(dir), filepath.ToSlash(base), nil
+}
+
+// Prepare resolves a prompt request without calling an LLM.
+func (e *Engine) Prepare(ctx context.Context, req RunRequest) (*PreparedRun, error) {
+	if e == nil || e.runner == nil {
+		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
+	}
+
+	domainReq, err := toDomainRunRequest(req)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidRequest, err)
+	}
+
+	prepared, err := e.runner.Prepare(ctx, domainReq)
+	if err != nil {
+		return nil, mapPublicError(err)
+	}
+	return fromDomainPreparedRun(prepared), nil
+}
+
+// Run executes a prompt request and returns the generated artifact and metadata.
+func (e *Engine) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
+	if e == nil || e.runner == nil {
+		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
+	}
+
+	domainReq, err := toDomainRunRequest(req)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidRequest, err)
+	}
+
+	result, err := e.runner.Run(ctx, domainReq)
+	if err != nil {
+		return nil, mapPublicError(err)
+	}
+	return fromDomainRunResult(result), nil
+}

errors.go

@@ -0,0 +1,60 @@
+package scriptorium
+
+import (
+	"errors"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/promptdef"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/usecase"
+)
+
+func mapPublicError(err error) error {
+	if err == nil {
+		return nil
+	}
+	publicErr := publicErrorFor(err)
+	if publicErr == nil {
+		return err
+	}
+	return fmt.Errorf("%w: %w", publicErr, err)
+}
+
+func publicErrorFor(err error) error {
+	switch {
+	case errors.Is(err, promptdef.ErrPromptDefinitionNotFound):
+		return ErrPromptNotFound
+	case errors.Is(err, profile.ErrProfileNotFound):
+		return ErrProfileNotFound
+	case errors.Is(err, usecase.ErrProfileRequired):
+		return errors.Join(ErrInvalidRequest, ErrProfileRequired)
+	case errors.Is(err, usecase.ErrPromptLoad):
+		return ErrPromptLoad
+	case errors.Is(err, usecase.ErrProfileLoad):
+		return ErrProfileLoad
+	case errors.Is(err, promptdef.ErrInvalidYAML), errors.Is(err, promptdef.ErrInvalidPromptDefinition):
+		return ErrPromptLoad
+	case isProfileLoadCause(err):
+		return ErrProfileLoad
+	case errors.Is(err, usecase.ErrAPIKeyEnvMissing):
+		return errors.Join(ErrInvalidRequest, ErrAPIKeyEnvMissing)
+	case errors.Is(err, usecase.ErrArtifactLoad):
+		return ErrArtifactLoad
+	case errors.Is(err, usecase.ErrPromptRender):
+		return ErrPromptRender
+	case errors.Is(err, usecase.ErrLLMGenerate):
+		return ErrLLMGenerate
+	case errors.Is(err, usecase.ErrValidation):
+		return ErrValidation
+	case errors.Is(err, usecase.ErrInvalidRequest):
+		return ErrInvalidRequest
+	default:
+		return nil
+	}
+}
+
+func isProfileLoadCause(err error) bool {
+	return errors.Is(err, profile.ErrInvalidYAML) ||
+		errors.Is(err, profile.ErrInvalidProfile) ||
+		errors.Is(err, profile.ErrRawAPIKeyNotAllowed)
+}

examples/config.full.yml

@@ -0,0 +1,13 @@
+prompt_dir: ./examples/prompts
+profile_dir: ./examples/profiles
+schema_dir: ./examples/schemas
+
+server:
+  addr: 127.0.0.1:8080
+  artifact_root: .
+  max_request_bytes: 16777216
+  max_artifact_bytes: 16777216
+  max_response_bytes: 16777216
+
+defaults:
+  render_format: text

examples/config.yml

@@ -4,6 +4,7 @@ schema_dir: ./examples/schemas
 
 server:
   addr: :8080
+  artifact_root: .
 
 defaults:
   render_format: text

examples/go-library/prepare/main.go

@@ -0,0 +1,50 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"os"
+
+	"gitea.maximumdirect.net/eric/scriptorium"
+)
+
+func main() {
+	engine, err := scriptorium.NewEngine(scriptorium.Config{
+		PromptDir:  "./examples/prompts",
+		ProfileDir: "./examples/profiles",
+		SchemaDir:  "./examples/schemas",
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	prepared, err := engine.Prepare(context.Background(), scriptorium.RunRequest{
+		PromptID: "generic.markdown_summary",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
+			"glossary":   scriptorium.File("./examples/fixtures/glossary.yml"),
+		},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	summary := struct {
+		PromptID          string            `json:"prompt_id"`
+		SelectedProfileID string            `json:"selected_profile_id"`
+		Model             string            `json:"model"`
+		MessageCount      int               `json:"message_count"`
+		InputHashes       map[string]string `json:"input_hashes"`
+	}{
+		PromptID:          prepared.PromptID,
+		SelectedProfileID: prepared.SelectedProfileID,
+		Model:             prepared.EffectiveModelParams.Model,
+		MessageCount:      len(prepared.Messages),
+		InputHashes:       prepared.InputHashes,
+	}
+
+	if err := json.NewEncoder(os.Stdout).Encode(summary); err != nil {
+		log.Fatal(err)
+	}
+}

formatting.go

@@ -0,0 +1,51 @@
+package scriptorium
+
+import "fmt"
+
+// String returns a concise request summary without exposing direct API keys.
+func (r RunRequest) String() string {
+	return r.redactedString()
+}
+
+// GoString returns a concise request summary without exposing direct API keys.
+func (r RunRequest) GoString() string {
+	return r.redactedString()
+}
+
+func (r RunRequest) redactedString() string {
+	return fmt.Sprintf(
+		"scriptorium.RunRequest{PromptID:%q PromptVersion:%q ProfileID:%q APIKeySet:%t Inputs:%d Vars:%d ExecutionSet:%t ValidationSet:%t Metadata:%d}",
+		r.PromptID,
+		r.PromptVersion,
+		r.ProfileID,
+		r.APIKey != "",
+		len(r.Inputs),
+		len(r.Vars),
+		r.Execution != nil,
+		r.Validation != nil,
+		len(r.Metadata),
+	)
+}
+
+// String returns a concise request summary without exposing direct API keys or
+// rendered prompt content.
+func (r GenerateRequest) String() string {
+	return r.redactedString()
+}
+
+// GoString returns a concise request summary without exposing direct API keys or
+// rendered prompt content.
+func (r GenerateRequest) GoString() string {
+	return r.redactedString()
+}
+
+func (r GenerateRequest) redactedString() string {
+	return fmt.Sprintf(
+		"scriptorium.GenerateRequest{Messages:%d Model:%q APIKeySet:%t StructuredOutputSet:%t ExtraParams:%d}",
+		len(r.Prompt.Messages),
+		r.Target.Model,
+		r.APIKey != "",
+		r.StructuredOutput != nil,
+		len(r.Target.ExtraParams),
+	)
+}

internal/adapter/cli/run.go

@@ -12,18 +12,11 @@ import (
 	"strings"
 	"time"
 
+	"gitea.maximumdirect.net/eric/scriptorium"
 	httpadapter "gitea.maximumdirect.net/eric/scriptorium/internal/adapter/http"
-	artifactadapter "gitea.maximumdirect.net/eric/scriptorium/internal/artifact"
 	appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
 	"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
 	renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/llm"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/prompt"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/promptdef"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/usecase"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/validate"
 )
 
 const (
@@ -33,8 +26,7 @@ const (
 )
 
 const (
-	errPromptDirRequired  = "prompt directory is required; provide --prompt-dir or config.yml prompt_dir"
-	errProfileDirRequired = "profile directory is required; provide --profile-dir or config.yml profile_dir"
+	errPromptDirRequired = "prompt directory is required; provide --prompt-dir or config.yml prompt_dir"
 )
 
 type runConfig struct {
@@ -75,10 +67,14 @@ type renderConfig struct {
 type serveConfig struct {
 	configPath string
 
-	addr       string
-	promptDir  string
-	profileDir string
-	schemaDir  string
+	addr             string
+	promptDir        string
+	profileDir       string
+	schemaDir        string
+	artifactRoot     string
+	maxRequestBytes  int64
+	maxArtifactBytes int64
+	maxResponseBytes int64
 }
 
 type commonCommandSettings struct {
@@ -86,6 +82,10 @@ type commonCommandSettings struct {
 	profileDir          string
 	schemaDir           string
 	serverAddr          string
+	artifactRoot        string
+	maxRequestBytes     int64
+	maxArtifactBytes    int64
+	maxResponseBytes    int64
 	defaultRenderFormat renderformat.PreparedRunOutputFormat
 }
 
@@ -133,15 +133,13 @@ func runCommand(args []string, stdout, stderr io.Writer) int {
 		return ExitRuntimeError
 	}
 
-	llmClient, err := newOpenAIClient()
+	engine, err := newEngine(cfg)
 	if err != nil {
-		fmt.Fprintf(stderr, "llm client error: %v\n", err)
+		fmt.Fprintf(stderr, "engine error: %v\n", err)
 		return ExitRuntimeError
 	}
 
-	runner := newRunner(cfg.promptDir, cfg.profileDir, cfg.schemaDir, llmClient)
-
-	res, runErr := runner.Run(context.Background(), req)
+	res, runErr := engine.Run(context.Background(), req)
 	if runErr != nil {
 		fmt.Fprintf(stderr, "run error: %v\n", runErr)
 		return ExitRuntimeError
@@ -169,9 +167,13 @@ func renderCommand(args []string, stdout, stderr io.Writer) int {
 		return ExitRuntimeError
 	}
 
-	runner := newRunner(cfg.promptDir, cfg.profileDir, cfg.schemaDir, nil)
+	engine, err := newEngine(&cfg.runConfig)
+	if err != nil {
+		fmt.Fprintf(stderr, "engine error: %v\n", err)
+		return ExitRuntimeError
+	}
 
-	prepared, prepErr := runner.Prepare(context.Background(), req)
+	prepared, prepErr := engine.Prepare(context.Background(), req)
 	if prepErr != nil {
 		fmt.Fprintf(stderr, "render error: %v\n", prepErr)
 		return ExitRuntimeError
@@ -197,15 +199,26 @@ func serveCommand(args []string, stderr io.Writer) int {
 		return ExitRuntimeError
 	}
 
-	llmClient, err := newOpenAIClient()
+	artifactReader, err := httpadapter.NewRestrictedArtifactReader(cfg.artifactRoot, cfg.maxArtifactBytes)
 	if err != nil {
-		fmt.Fprintf(stderr, "llm client error: %v\n", err)
+		fmt.Fprintf(stderr, "artifact root error: %v\n", err)
 		return ExitRuntimeError
 	}
 
-	runner := newRunner(cfg.promptDir, cfg.profileDir, cfg.schemaDir, llmClient)
+	engine, err := newEngine(&runConfig{
+		promptDir:  cfg.promptDir,
+		profileDir: cfg.profileDir,
+		schemaDir:  cfg.schemaDir,
+	}, scriptorium.WithArtifactReader(artifactReader))
+	if err != nil {
+		fmt.Fprintf(stderr, "engine error: %v\n", err)
+		return ExitRuntimeError
+	}
 
-	h := httpadapter.NewHandler(runner)
+	h := httpadapter.NewHandlerWithOptions(engine, httpadapter.HandlerOptions{
+		MaxRequestBytes:  cfg.maxRequestBytes,
+		MaxResponseBytes: cfg.maxResponseBytes,
+	})
 	srv := &http.Server{
 		Addr:              cfg.addr,
 		Handler:           h,
@@ -282,6 +295,10 @@ func parseServeArgs(args []string) (*serveConfig, error) {
 	fs.StringVar(&cfg.promptDir, "prompt-dir", "", "directory containing prompt definition YAML files")
 	fs.StringVar(&cfg.profileDir, "profile-dir", "", "directory containing execution profile YAML files")
 	fs.StringVar(&cfg.schemaDir, "schema-dir", "", "base directory for validation schemas")
+	fs.StringVar(&cfg.artifactRoot, "artifact-root", "", "base directory for HTTP file input artifacts")
+	fs.Int64Var(&cfg.maxRequestBytes, "max-request-bytes", 0, "maximum HTTP request body bytes; 0 disables the limit")
+	fs.Int64Var(&cfg.maxArtifactBytes, "max-artifact-bytes", 0, "maximum HTTP file artifact bytes; 0 disables the limit")
+	fs.Int64Var(&cfg.maxResponseBytes, "max-response-bytes", 0, "maximum HTTP response body bytes; 0 disables the limit")
 
 	if err := fs.Parse(args); err != nil {
 		return nil, err
@@ -291,10 +308,14 @@ func parseServeArgs(args []string) (*serveConfig, error) {
 	}
 
 	settings, err := resolveCommonSettings(fs, cfg.configPath, appconfig.CLIOverrides{
-		PromptDir:  cfg.promptDirIfSet(fs),
-		ProfileDir: cfg.profileDirIfSet(fs),
-		SchemaDir:  cfg.schemaDirIfSet(fs),
-		ServerAddr: cfg.addrIfSet(fs),
+		PromptDir:        cfg.promptDirIfSet(fs),
+		ProfileDir:       cfg.profileDirIfSet(fs),
+		SchemaDir:        cfg.schemaDirIfSet(fs),
+		ServerAddr:       cfg.addrIfSet(fs),
+		ArtifactRoot:     cfg.artifactRootIfSet(fs),
+		MaxRequestBytes:  cfg.maxRequestBytesIfSet(fs),
+		MaxArtifactBytes: cfg.maxArtifactBytesIfSet(fs),
+		MaxResponseBytes: cfg.maxResponseBytesIfSet(fs),
 	})
 	if err != nil {
 		return nil, err
@@ -304,14 +325,23 @@ func parseServeArgs(args []string) (*serveConfig, error) {
 	cfg.profileDir = settings.profileDir
 	cfg.schemaDir = settings.schemaDir
 	cfg.addr = settings.serverAddr
+	cfg.artifactRoot = settings.artifactRoot
+	cfg.maxRequestBytes = settings.maxRequestBytes
+	cfg.maxArtifactBytes = settings.maxArtifactBytes
+	cfg.maxResponseBytes = settings.maxResponseBytes
 
-	if err := validateRequiredLibraryDirs(cfg.promptDir, cfg.profileDir); err != nil {
+	if err := validateRequiredLibraryDirs(cfg.promptDir); err != nil {
 		return nil, err
 	}
 
 	cfg.promptDir = filepath.Clean(cfg.promptDir)
-	cfg.profileDir = filepath.Clean(cfg.profileDir)
+	if strings.TrimSpace(cfg.profileDir) != "" {
+		cfg.profileDir = filepath.Clean(cfg.profileDir)
+	}
 	cfg.schemaDir = filepath.Clean(cfg.schemaDir)
+	if strings.TrimSpace(cfg.artifactRoot) != "" {
+		cfg.artifactRoot = filepath.Clean(cfg.artifactRoot)
+	}
 	return cfg, nil
 }
 
@@ -353,7 +383,7 @@ func finalizeExecutionRequestConfig(fs *flag.FlagSet, cfg *runConfig) error {
 	cfg.schemaDir = settings.schemaDir
 	cfg.defaultRenderFormat = settings.defaultRenderFormat
 
-	if err := validateRequiredLibraryDirs(cfg.promptDir, cfg.profileDir); err != nil {
+	if err := validateRequiredLibraryDirs(cfg.promptDir); err != nil {
 		return err
 	}
 	if strings.TrimSpace(cfg.promptID) == "" {
@@ -363,7 +393,9 @@ func finalizeExecutionRequestConfig(fs *flag.FlagSet, cfg *runConfig) error {
 		return errors.New("at least one --input is required")
 	}
 	cfg.promptDir = filepath.Clean(cfg.promptDir)
-	cfg.profileDir = filepath.Clean(cfg.profileDir)
+	if strings.TrimSpace(cfg.profileDir) != "" {
+		cfg.profileDir = filepath.Clean(cfg.profileDir)
+	}
 	if cfg.outputPath != "" {
 		cfg.outputPath = filepath.Clean(cfg.outputPath)
 	}
@@ -426,6 +458,34 @@ func (c *serveConfig) addrIfSet(fs *flag.FlagSet) string {
 	return ""
 }
 
+func (c *serveConfig) artifactRootIfSet(fs *flag.FlagSet) string {
+	if flagWasSet(fs, "artifact-root") {
+		return c.artifactRoot
+	}
+	return ""
+}
+
+func (c *serveConfig) maxRequestBytesIfSet(fs *flag.FlagSet) *int64 {
+	if flagWasSet(fs, "max-request-bytes") {
+		return &c.maxRequestBytes
+	}
+	return nil
+}
+
+func (c *serveConfig) maxArtifactBytesIfSet(fs *flag.FlagSet) *int64 {
+	if flagWasSet(fs, "max-artifact-bytes") {
+		return &c.maxArtifactBytes
+	}
+	return nil
+}
+
+func (c *serveConfig) maxResponseBytesIfSet(fs *flag.FlagSet) *int64 {
+	if flagWasSet(fs, "max-response-bytes") {
+		return &c.maxResponseBytes
+	}
+	return nil
+}
+
 func registerConfigPathFlag(fs *flag.FlagSet, target *string) {
 	fs.StringVar(
 		target,
@@ -463,59 +523,51 @@ func resolveCommonSettings(fs *flag.FlagSet, configPath string, overrides appcon
 		profileDir:          settings.ProfileDir,
 		schemaDir:           settings.SchemaDir,
 		serverAddr:          settings.ServerAddr,
+		artifactRoot:        settings.ArtifactRoot,
+		maxRequestBytes:     settings.MaxRequestBytes,
+		maxArtifactBytes:    settings.MaxArtifactBytes,
+		maxResponseBytes:    settings.MaxResponseBytes,
 		defaultRenderFormat: settings.DefaultRenderFormat,
 	}, nil
 }
 
-func validateRequiredLibraryDirs(promptDir, profileDir string) error {
+func validateRequiredLibraryDirs(promptDir string) error {
 	if strings.TrimSpace(promptDir) == "" {
 		return errors.New(errPromptDirRequired)
 	}
-	if strings.TrimSpace(profileDir) == "" {
-		return errors.New(errProfileDirRequired)
-	}
 	return nil
 }
 
-func newRunner(promptDir, profileDir, schemaDir string, llmClient llm.Client) *usecase.Runner {
-	return usecase.NewRunner(
-		promptdef.NewFilesystemRepository(promptDir),
-		profile.NewFilesystemRepository(profileDir),
-		artifactadapter.NewCompositeReader(),
-		prompt.NewGoRenderer(),
-		llmClient,
-		validate.NewStandardValidator(schemaDir),
-	)
+func newEngine(cfg *runConfig, options ...scriptorium.Option) (*scriptorium.Engine, error) {
+	return scriptorium.NewEngine(scriptorium.Config{
+		PromptDir:  cfg.promptDir,
+		ProfileDir: cfg.profileDir,
+		SchemaDir:  cfg.schemaDir,
+	}, options...)
 }
 
-func newOpenAIClient() (*llm.OpenAICompatibleClient, error) {
-	return llm.NewOpenAICompatibleClient(llm.OpenAICompatibleConfig{
-		Timeout: defaults.LLMRequestTimeoutDefault,
-	})
-}
-
-func buildRunRequestFromConfig(cfg *runConfig) (domain.RunRequest, error) {
+func buildRunRequestFromConfig(cfg *runConfig) (scriptorium.RunRequest, error) {
 	inputMappings, err := parseMappings(cfg.inputRaw, false)
 	if err != nil {
-		return domain.RunRequest{}, fmt.Errorf("input parse error: %w", err)
+		return scriptorium.RunRequest{}, fmt.Errorf("input parse error: %w", err)
 	}
 
 	varMappings := map[string]string{}
 	if len(cfg.varRaw) > 0 {
 		varMappings, err = parseMappings(cfg.varRaw, false)
 		if err != nil {
-			return domain.RunRequest{}, fmt.Errorf("var parse error: %w", err)
+			return scriptorium.RunRequest{}, fmt.Errorf("var parse error: %w", err)
 		}
 	}
 
-	inputs := make(map[string]domain.ArtifactRef, len(inputMappings))
+	inputs := make(map[string]scriptorium.ArtifactRef, len(inputMappings))
 	for name, path := range inputMappings {
-		inputs[name] = domain.ArtifactRef{Type: domain.ArtifactRefFile, URI: path}
+		inputs[name] = scriptorium.File(path)
 	}
 
-	var modelOverride *domain.ExecutionTargetOverride
+	var modelOverride *scriptorium.ExecutionTargetOverride
 	if cfg.llmBaseURLSet || cfg.modelSet || cfg.temperatureSet || cfg.maxTokensSet || cfg.topPSet || cfg.apiKeyEnvSet || cfg.timeoutSet {
-		modelOverride = &domain.ExecutionTargetOverride{
+		modelOverride = &scriptorium.ExecutionTargetOverride{
 			Endpoint:  cfg.llmBaseURL,
 			Model:     cfg.model,
 			APIKeyEnv: cfg.apiKeyEnv,
@@ -535,7 +587,7 @@ func buildRunRequestFromConfig(cfg *runConfig) (domain.RunRequest, error) {
 		}
 	}
 
-	return domain.RunRequest{
+	return scriptorium.RunRequest{
 		PromptID:  cfg.promptID,
 		ProfileID: cfg.profileID,
 		Inputs:    inputs,
@@ -599,17 +651,17 @@ func writeOutput(stdout io.Writer, outputPath string, body []byte) error {
 	return os.WriteFile(outputPath, body, 0644)
 }
 
-func determineExitCode(runErr error, result *domain.RunResult) int {
+func determineExitCode(runErr error, result *scriptorium.RunResult) int {
 	if runErr != nil {
 		return ExitRuntimeError
 	}
-	if result != nil && result.Validation.Status == domain.ValidationFailed {
+	if result != nil && result.Validation.Status == scriptorium.ValidationFailed {
 		return ExitValidationFailed
 	}
 	return ExitOK
 }
 
-func printSummary(stderr io.Writer, res *domain.RunResult) {
+func printSummary(stderr io.Writer, res *scriptorium.RunResult) {
 	if res == nil {
 		return
 	}
@@ -637,5 +689,5 @@ func printUsage(w io.Writer) {
 	fmt.Fprintln(w, "usage: scriptorium <run|render|serve> ...")
 	fmt.Fprintln(w, "  run:   scriptorium run [--config PATH] [--prompt-dir DIR] [--profile-dir DIR] --prompt ID --input name=path [--input ...] [--profile ID] [--llm-base-url URL] [--model NAME] [--api-key-env ENV] [--temperature N] [--max-tokens N] [--top-p N] [--var k=v] [--out path] [--timeout 10m]")
 	fmt.Fprintln(w, "  render: scriptorium render [--config PATH] [--prompt-dir DIR] [--profile-dir DIR] --prompt ID --input name=path [--input ...] [--profile ID] [--llm-base-url URL] [--model NAME] [--api-key-env ENV] [--temperature N] [--max-tokens N] [--top-p N] [--var k=v] [--format text|json] [--out path] [--timeout 10m]")
-	fmt.Fprintf(w, "  serve: scriptorium serve [--config PATH] [--addr %s] [--prompt-dir DIR] [--profile-dir DIR] [--schema-dir DIR]\n", defaults.HTTPAddrDefault)
+	fmt.Fprintf(w, "  serve: scriptorium serve [--config PATH] [--addr %s] [--prompt-dir DIR] [--profile-dir DIR] [--schema-dir DIR] [--artifact-root DIR] [--max-request-bytes N] [--max-artifact-bytes N] [--max-response-bytes N]\n", defaults.HTTPAddrDefault)
 }

internal/adapter/cli/run_test.go

@@ -17,9 +17,9 @@ import (
 	"testing"
 	"time"
 
+	"gitea.maximumdirect.net/eric/scriptorium"
 	appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
 	"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
 	renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
 )
 
@@ -74,12 +74,12 @@ func TestParseRunArgsRequiredFlags(t *testing.T) {
 		t.Fatalf("expected clear prompt-dir guidance, got %v", err)
 	}
 
-	_, err = parseRunArgs([]string{"--config", configPath, "--prompt-dir", "./prompts", "--prompt", "p", "--input", "a=b"})
-	if err == nil {
-		t.Fatal("expected missing --profile-dir error")
+	cfg, err := parseRunArgs([]string{"--config", configPath, "--prompt-dir", "./prompts", "--prompt", "p", "--input", "a=b"})
+	if err != nil {
+		t.Fatalf("expected missing --profile-dir to be accepted, got %v", err)
 	}
-	if !strings.Contains(err.Error(), "profile directory is required") {
-		t.Fatalf("expected clear profile-dir guidance, got %v", err)
+	if cfg.profileDir != "" {
+		t.Fatalf("expected empty profile dir for built-ins, got %q", cfg.profileDir)
 	}
 
 	_, err = parseRunArgs([]string{"--config", configPath, "--prompt-dir", "./prompts", "--profile-dir", "./profiles", "--input", "a=b"})
@@ -161,17 +161,12 @@ func TestParseServeArgsRequiredFlags(t *testing.T) {
 		t.Fatalf("expected clear prompt-dir guidance, got %v", err)
 	}
 
-	_, err = parseServeArgs([]string{"--config", configPath, "--prompt-dir", "./prompts"})
-	if err == nil {
-		t.Fatal("expected missing --profile-dir error")
-	}
-	if !strings.Contains(err.Error(), "profile directory is required") {
-		t.Fatalf("expected clear profile-dir guidance, got %v", err)
-	}
-
-	cfg, err := parseServeArgs([]string{"--config", configPath, "--prompt-dir", "./prompts", "--profile-dir", "./profiles"})
+	cfg, err := parseServeArgs([]string{"--config", configPath, "--prompt-dir", "./prompts"})
 	if err != nil {
-		t.Fatalf("expected valid serve args, got %v", err)
+		t.Fatalf("expected missing --profile-dir to be accepted, got %v", err)
+	}
+	if cfg.profileDir != "" {
+		t.Fatalf("expected empty profile dir for built-ins, got %q", cfg.profileDir)
 	}
 	if cfg.addr != defaults.HTTPAddrDefault {
 		t.Fatalf("expected default addr %s, got %q", defaults.HTTPAddrDefault, cfg.addr)
@@ -197,6 +192,26 @@ func TestParseServeArgsRejectsRuntimeOverrideFlags(t *testing.T) {
 	}
 }
 
+func TestUsageIncludesServeFileAndSizeLimitFlags(t *testing.T) {
+	var stderr bytes.Buffer
+	code := Run(nil, io.Discard, &stderr)
+	if code != ExitRuntimeError {
+		t.Fatalf("expected usage path to return runtime error, got %d", code)
+	}
+
+	usage := stderr.String()
+	for _, want := range []string{
+		"--artifact-root",
+		"--max-request-bytes",
+		"--max-artifact-bytes",
+		"--max-response-bytes",
+	} {
+		if !strings.Contains(usage, want) {
+			t.Fatalf("expected usage to include %q, got %q", want, usage)
+		}
+	}
+}
+
 func TestParseRunArgsTimeout(t *testing.T) {
 	cfg, err := parseRunArgs([]string{
 		"--prompt-dir", "./prompts",
@@ -440,11 +455,19 @@ profile_dir: ./from-config/profiles
 schema_dir: ./from-config/schemas
 server:
   addr: 127.0.0.1:9000
+  artifact_root: ./from-config/artifacts
+  max_request_bytes: 1024
+  max_artifact_bytes: 2048
+  max_response_bytes: 4096
 `)
 
 	cfg, err := parseServeArgs([]string{
 		"--config", configPath,
 		"--addr", ":7777",
+		"--artifact-root", "./from-cli/artifacts",
+		"--max-request-bytes", "0",
+		"--max-artifact-bytes", "8192",
+		"--max-response-bytes", "16384",
 	})
 	if err != nil {
 		t.Fatalf("expected valid args, got %v", err)
@@ -462,6 +485,18 @@ server:
 	if cfg.addr != ":7777" {
 		t.Fatalf("expected CLI addr override, got %q", cfg.addr)
 	}
+	if cfg.artifactRoot != filepath.Clean("./from-cli/artifacts") {
+		t.Fatalf("expected CLI artifact root override, got %q", cfg.artifactRoot)
+	}
+	if cfg.maxRequestBytes != 0 {
+		t.Fatalf("expected CLI max request bytes override, got %d", cfg.maxRequestBytes)
+	}
+	if cfg.maxArtifactBytes != 8192 {
+		t.Fatalf("expected CLI max artifact bytes override, got %d", cfg.maxArtifactBytes)
+	}
+	if cfg.maxResponseBytes != 16384 {
+		t.Fatalf("expected CLI max response bytes override, got %d", cfg.maxResponseBytes)
+	}
 }
 
 func TestParseServeArgsWithConfigProvidesRequiredDirectoriesAndAddr(t *testing.T) {
@@ -471,6 +506,10 @@ profile_dir: ./from-config/profiles
 schema_dir: ./from-config/schemas
 server:
   addr: 127.0.0.1:9000
+  artifact_root: ./from-config/artifacts
+  max_request_bytes: 1024
+  max_artifact_bytes: 2048
+  max_response_bytes: 4096
 `)
 
 	cfg, err := parseServeArgs([]string{
@@ -492,6 +531,75 @@ server:
 	if cfg.addr != "127.0.0.1:9000" {
 		t.Fatalf("expected addr from config, got %q", cfg.addr)
 	}
+	if cfg.artifactRoot != filepath.Clean("./from-config/artifacts") {
+		t.Fatalf("expected artifact root from config, got %q", cfg.artifactRoot)
+	}
+	if cfg.maxRequestBytes != 1024 {
+		t.Fatalf("expected max request bytes from config, got %d", cfg.maxRequestBytes)
+	}
+	if cfg.maxArtifactBytes != 2048 {
+		t.Fatalf("expected max artifact bytes from config, got %d", cfg.maxArtifactBytes)
+	}
+	if cfg.maxResponseBytes != 4096 {
+		t.Fatalf("expected max response bytes from config, got %d", cfg.maxResponseBytes)
+	}
+}
+
+func TestParseServeArgsRejectsNegativeSizeLimits(t *testing.T) {
+	tests := []struct {
+		name string
+		flag string
+	}{
+		{name: "request", flag: "--max-request-bytes"},
+		{name: "artifact", flag: "--max-artifact-bytes"},
+		{name: "response", flag: "--max-response-bytes"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := parseServeArgs([]string{
+				"--prompt-dir", "./prompts",
+				tc.flag, "-1",
+			})
+			if err == nil {
+				t.Fatal("expected negative size limit error")
+			}
+		})
+	}
+}
+
+func TestRunAndRenderRejectServeSizeLimitFlags(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		parse func([]string) error
+	}{
+		{
+			name: "run",
+			parse: func(args []string) error {
+				_, err := parseRunArgs(args)
+				return err
+			},
+		},
+		{
+			name: "render",
+			parse: func(args []string) error {
+				_, err := parseRenderArgs(args)
+				return err
+			},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			err := tc.parse([]string{
+				"--prompt-dir", "./prompts",
+				"--prompt", "p",
+				"--input", "a=b",
+				"--max-request-bytes", "1024",
+			})
+			if err == nil {
+				t.Fatal("expected unsupported flag error")
+			}
+		})
+	}
 }
 
 func TestRunAndRenderBuildEquivalentRuntimeOverrideRequestsForSharedFlags(t *testing.T) {
@@ -547,6 +655,40 @@ func TestRunAndRenderBuildEquivalentRuntimeOverrideRequestsForSharedFlags(t *tes
 	}
 }
 
+func TestBuildRunRequestPreservesNumericOverridePresence(t *testing.T) {
+	omitted, err := buildRunRequestFromConfig(&runConfig{
+		promptID: "prompt-1",
+		inputRaw: []string{"transcript=./transcript.md"},
+	})
+	if err != nil {
+		t.Fatalf("expected omitted override request to build, got %v", err)
+	}
+	if omitted.Execution != nil {
+		t.Fatalf("expected omitted numeric flags to leave execution override nil, got %#v", omitted.Execution)
+	}
+
+	explicitZeros, err := buildRunRequestFromConfig(&runConfig{
+		promptID:       "prompt-1",
+		inputRaw:       []string{"transcript=./transcript.md"},
+		temperatureSet: true,
+		maxTokensSet:   true,
+		topPSet:        true,
+		timeoutSet:     true,
+	})
+	if err != nil {
+		t.Fatalf("expected explicit zero override request to build, got %v", err)
+	}
+	if explicitZeros.Execution == nil {
+		t.Fatal("expected explicit numeric flags to create execution override")
+	}
+	if explicitZeros.Execution.Temperature == nil || explicitZeros.Execution.MaxTokens == nil || explicitZeros.Execution.TopP == nil || explicitZeros.Execution.TimeoutSeconds == nil {
+		t.Fatalf("expected explicit zero numeric overrides to remain non-nil, got %#v", explicitZeros.Execution)
+	}
+	if *explicitZeros.Execution.Temperature != 0 || *explicitZeros.Execution.MaxTokens != 0 || *explicitZeros.Execution.TopP != 0 || *explicitZeros.Execution.TimeoutSeconds != 0 {
+		t.Fatalf("expected explicit numeric overrides to retain zero values, got %#v", explicitZeros.Execution)
+	}
+}
+
 func TestParseRunArgsFailsClearlyWhenNoEffectivePromptDir(t *testing.T) {
 	configPath := writeAppConfigFile(t, `
 profile_dir: ./profiles
@@ -565,21 +707,21 @@ profile_dir: ./profiles
 	}
 }
 
-func TestParseRunArgsFailsClearlyWhenNoEffectiveProfileDir(t *testing.T) {
+func TestParseRunArgsAcceptsMissingEffectiveProfileDir(t *testing.T) {
 	configPath := writeAppConfigFile(t, `
 prompt_dir: ./prompts
 `)
 
-	_, err := parseRunArgs([]string{
+	cfg, err := parseRunArgs([]string{
 		"--config", configPath,
 		"--prompt", "p",
 		"--input", "a=b",
 	})
-	if err == nil {
-		t.Fatal("expected missing profile_dir error")
+	if err != nil {
+		t.Fatalf("expected missing profile_dir to be accepted, got %v", err)
 	}
-	if !strings.Contains(err.Error(), "profile directory is required") || !strings.Contains(err.Error(), "config.yml profile_dir") {
-		t.Fatalf("expected clear profile_dir guidance, got %v", err)
+	if cfg.profileDir != "" {
+		t.Fatalf("expected empty profile dir for built-ins, got %q", cfg.profileDir)
 	}
 }
 
@@ -601,21 +743,21 @@ profile_dir: ./profiles
 	}
 }
 
-func TestParseRenderArgsFailsClearlyWhenNoEffectiveProfileDir(t *testing.T) {
+func TestParseRenderArgsAcceptsMissingEffectiveProfileDir(t *testing.T) {
 	configPath := writeAppConfigFile(t, `
 prompt_dir: ./prompts
 `)
 
-	_, err := parseRenderArgs([]string{
+	cfg, err := parseRenderArgs([]string{
 		"--config", configPath,
 		"--prompt", "p",
 		"--input", "a=b",
 	})
-	if err == nil {
-		t.Fatal("expected missing profile_dir error")
+	if err != nil {
+		t.Fatalf("expected missing profile_dir to be accepted, got %v", err)
 	}
-	if !strings.Contains(err.Error(), "profile directory is required") || !strings.Contains(err.Error(), "config.yml profile_dir") {
-		t.Fatalf("expected clear profile_dir guidance, got %v", err)
+	if cfg.profileDir != "" {
+		t.Fatalf("expected empty profile dir for built-ins, got %q", cfg.profileDir)
 	}
 }
 
@@ -623,13 +765,13 @@ func TestDetermineExitCode(t *testing.T) {
 	if got := determineExitCode(errors.New("boom"), nil); got != ExitRuntimeError {
 		t.Fatalf("expected runtime exit code, got %d", got)
 	}
-	if got := determineExitCode(nil, &domain.RunResult{Validation: domain.ValidationResult{Status: domain.ValidationFailed}}); got != ExitValidationFailed {
+	if got := determineExitCode(nil, &scriptorium.RunResult{Validation: scriptorium.ValidationResult{Status: scriptorium.ValidationFailed}}); got != ExitValidationFailed {
 		t.Fatalf("expected validation exit code, got %d", got)
 	}
-	if got := determineExitCode(nil, &domain.RunResult{Validation: domain.ValidationResult{Status: domain.ValidationPassed}}); got != ExitOK {
+	if got := determineExitCode(nil, &scriptorium.RunResult{Validation: scriptorium.ValidationResult{Status: scriptorium.ValidationPassed}}); got != ExitOK {
 		t.Fatalf("expected success exit code for passed validation, got %d", got)
 	}
-	if got := determineExitCode(nil, &domain.RunResult{Validation: domain.ValidationResult{Status: domain.ValidationSkipped}}); got != ExitOK {
+	if got := determineExitCode(nil, &scriptorium.RunResult{Validation: scriptorium.ValidationResult{Status: scriptorium.ValidationSkipped}}); got != ExitOK {
 		t.Fatalf("expected success exit code for skipped validation, got %d", got)
 	}
 }
@@ -929,6 +1071,29 @@ func TestRenderCommandPromptDefaultProfileWorksThroughCLIPath(t *testing.T) {
 	}
 }
 
+func TestRenderCommandUsesBuiltInProfileWithoutProfileDir(t *testing.T) {
+	t.Setenv("OPENROUTER_API_KEY", "test-key")
+	lib := newCLITestLibrary(t)
+	inputPath := lib.writeInputFile(t, "transcript.md", "hello")
+
+	writePromptFile(t, lib.promptDir, "prompt.builtin", "mistral-small-3")
+
+	code, stdout, stderr := runCLICommand(t, renderCommand, []string{
+		"--prompt-dir", lib.promptDir,
+		"--prompt", "prompt.builtin",
+		"--input", "transcript=" + inputPath,
+	})
+	if code != ExitOK {
+		t.Fatalf("expected ExitOK, got %d stderr=%q", code, stderr)
+	}
+	if !strings.Contains(stdout, "selected_profile_id: mistral-small-3") {
+		t.Fatalf("expected built-in selected profile, got %q", stdout)
+	}
+	if !strings.Contains(stdout, "model: mistralai/mistral-small-3.2-24b-instruct") {
+		t.Fatalf("expected built-in model, got %q", stdout)
+	}
+}
+
 func TestRenderCommandExplicitProfileOverridesPromptDefault(t *testing.T) {
 	lib := newCLITestLibrary(t)
 	inputPath := lib.writeInputFile(t, "transcript.md", "hello")
@@ -1077,12 +1242,12 @@ func TestWriteOutputAndSummaryUseSeparateWriters(t *testing.T) {
 	if err := writeOutput(&stdout, "", []byte("artifact-body")); err != nil {
 		t.Fatalf("unexpected writeOutput error: %v", err)
 	}
-	printSummary(&stderr, &domain.RunResult{
+	printSummary(&stderr, &scriptorium.RunResult{
 		PromptID:           "p",
 		PromptVersion:      "1",
 		SelectedProfileID:  "exec",
 		ModelName:          "m",
-		Validation:         domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic},
+		Validation:         scriptorium.ValidationResult{Status: scriptorium.ValidationPassed, Mode: scriptorium.ValidationBasic},
 		RenderedPromptHash: "h",
 		InputHashes:        map[string]string{"in": "x"},
 	})
@@ -1101,15 +1266,15 @@ func TestWriteOutputAndSummaryUseSeparateWriters(t *testing.T) {
 func TestPrintSummaryIncludesCacheUsageWhenPresent(t *testing.T) {
 	var stderr bytes.Buffer
 
-	printSummary(&stderr, &domain.RunResult{
+	printSummary(&stderr, &scriptorium.RunResult{
 		PromptID:           "p",
 		PromptVersion:      "1",
 		SelectedProfileID:  "exec",
 		ModelName:          "m",
-		Validation:         domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic},
+		Validation:         scriptorium.ValidationResult{Status: scriptorium.ValidationPassed, Mode: scriptorium.ValidationBasic},
 		RenderedPromptHash: "h",
 		InputHashes:        map[string]string{"in": "x"},
-		Usage: domain.TokenUsage{
+		Usage: scriptorium.TokenUsage{
 			PromptTokens:     10,
 			CompletionTokens: 5,
 			TotalTokens:      15,

internal/adapter/dependency_test.go

@@ -0,0 +1,132 @@
+package adapter_test
+
+import (
+	"fmt"
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+const scriptoriumModulePath = "gitea.maximumdirect.net/eric/scriptorium"
+
+var forbiddenFrameworkPackageRoots = []string{
+	scriptoriumModulePath + "/internal/domain",
+	scriptoriumModulePath + "/internal/usecase",
+	scriptoriumModulePath + "/internal/promptdef",
+	scriptoriumModulePath + "/internal/prompt",
+	scriptoriumModulePath + "/internal/profile",
+	scriptoriumModulePath + "/internal/validate",
+	scriptoriumModulePath + "/internal/llm",
+	scriptoriumModulePath + "/internal/artifact",
+}
+
+type forbiddenFrameworkImport struct {
+	filePath   string
+	importPath string
+}
+
+func TestScriptoriumAdaptersUseOnlyPublicFrameworkBoundary(t *testing.T) {
+	_, testFile, _, ok := runtime.Caller(0)
+	if !ok {
+		t.Fatal("locate dependency guard source")
+	}
+
+	adapterDir := filepath.Dir(testFile)
+	violations, err := findForbiddenFrameworkImports([]string{
+		filepath.Join(adapterDir, "cli"),
+		filepath.Join(adapterDir, "http"),
+		filepath.Join(adapterDir, "..", "format"),
+	})
+	if err != nil {
+		t.Fatalf("scan framework imports: %v", err)
+	}
+	for _, violation := range violations {
+		t.Errorf("%s imports forbidden framework package %s", violation.filePath, violation.importPath)
+	}
+}
+
+func TestForbiddenFrameworkImportScannerDetectsNestedPackageFamilies(t *testing.T) {
+	root := t.TempDir()
+	nestedDir := filepath.Join(root, "nested", "adapter")
+	if err := os.MkdirAll(nestedDir, 0o755); err != nil {
+		t.Fatalf("create nested source directory: %v", err)
+	}
+
+	sourcePath := filepath.Join(nestedDir, "imports.go")
+	source := `package nested
+
+import (
+	_ "gitea.maximumdirect.net/eric/scriptorium"
+	_ "gitea.maximumdirect.net/eric/scriptorium/internal/profile/builtin"
+)
+`
+	if err := os.WriteFile(sourcePath, []byte(source), 0o644); err != nil {
+		t.Fatalf("write nested source fixture: %v", err)
+	}
+
+	violations, err := findForbiddenFrameworkImports([]string{root})
+	if err != nil {
+		t.Fatalf("scan nested source fixture: %v", err)
+	}
+	if len(violations) != 1 {
+		t.Fatalf("expected one forbidden import, got %#v", violations)
+	}
+	if violations[0].filePath != sourcePath {
+		t.Fatalf("unexpected importing file: %q", violations[0].filePath)
+	}
+	wantImport := scriptoriumModulePath + "/internal/profile/builtin"
+	if violations[0].importPath != wantImport {
+		t.Fatalf("unexpected forbidden import: %q", violations[0].importPath)
+	}
+}
+
+func findForbiddenFrameworkImports(roots []string) ([]forbiddenFrameworkImport, error) {
+	var violations []forbiddenFrameworkImport
+	for _, root := range roots {
+		err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, err error) error {
+			if err != nil {
+				return err
+			}
+			if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".go") || strings.HasSuffix(entry.Name(), "_test.go") {
+				return nil
+			}
+
+			file, err := parser.ParseFile(token.NewFileSet(), path, nil, parser.ImportsOnly)
+			if err != nil {
+				return fmt.Errorf("parse imports in %s: %w", path, err)
+			}
+			for _, imported := range file.Imports {
+				importPath, err := strconv.Unquote(imported.Path.Value)
+				if err != nil {
+					return fmt.Errorf("parse import path in %s: %w", path, err)
+				}
+				if isForbiddenFrameworkImport(importPath) {
+					violations = append(violations, forbiddenFrameworkImport{
+						filePath:   path,
+						importPath: importPath,
+					})
+				}
+			}
+			return nil
+		})
+		if err != nil {
+			return nil, fmt.Errorf("walk source root %s: %w", root, err)
+		}
+	}
+	return violations, nil
+}
+
+func isForbiddenFrameworkImport(importPath string) bool {
+	for _, root := range forbiddenFrameworkPackageRoots {
+		if importPath == root || strings.HasPrefix(importPath, root+"/") {
+			return true
+		}
+	}
+	return false
+}

internal/adapter/http/artifact_reader.go

@@ -0,0 +1,165 @@
+package httpadapter
+
+import (
+	"context"
+	"crypto/sha256"
+	"errors"
+	"fmt"
+	"io"
+	"mime"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/scriptorium"
+)
+
+var (
+	ErrFileNotAllowed  = errors.New("file artifact references are not allowed")
+	ErrFileOutsideRoot = errors.New("file artifact path is outside artifact root")
+	ErrFileTooLarge    = errors.New("file artifact exceeds size limit")
+)
+
+const fallbackArtifactContentType = "text/plain"
+
+// NewRestrictedArtifactReader creates the HTTP artifact reader for a rooted
+// filesystem and optional byte limit. An empty root permits inline artifacts
+// but denies file references; a zero limit permits artifacts of any size.
+func NewRestrictedArtifactReader(root string, maxBytes int64) (scriptorium.ArtifactReader, error) {
+	if maxBytes < 0 {
+		return nil, fmt.Errorf("artifact size limit must be greater than or equal to 0")
+	}
+
+	cleanRoot := strings.TrimSpace(root)
+	if cleanRoot == "" {
+		return &restrictedArtifactReader{maxBytes: maxBytes}, nil
+	}
+	absRoot, err := filepath.Abs(filepath.Clean(cleanRoot))
+	if err != nil {
+		return nil, fmt.Errorf("resolve artifact root: %w", err)
+	}
+	return &restrictedArtifactReader{root: absRoot, maxBytes: maxBytes}, nil
+}
+
+type restrictedArtifactReader struct {
+	root     string
+	maxBytes int64
+}
+
+var _ scriptorium.ArtifactReader = (*restrictedArtifactReader)(nil)
+
+func (r *restrictedArtifactReader) Read(ctx context.Context, ref scriptorium.ArtifactRef) (*scriptorium.Artifact, error) {
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	default:
+	}
+
+	switch ref.Type {
+	case scriptorium.ArtifactRefInline:
+		return readInlineArtifact(ref)
+	case scriptorium.ArtifactRefFile:
+		return r.readFileArtifact(ref)
+	default:
+		return nil, fmt.Errorf("unsupported artifact reference type %q", ref.Type)
+	}
+}
+
+func readInlineArtifact(ref scriptorium.ArtifactRef) (*scriptorium.Artifact, error) {
+	if ref.Body == "" {
+		return nil, errors.New("inline artifact body is required")
+	}
+
+	body := []byte(ref.Body)
+	return &scriptorium.Artifact{
+		ContentType: fallbackArtifactContentType,
+		Body:        body,
+		Size:        int64(len(body)),
+		Hash:        artifactHash(body),
+		URI:         ref.URI,
+	}, nil
+}
+
+func (r *restrictedArtifactReader) readFileArtifact(ref scriptorium.ArtifactRef) (*scriptorium.Artifact, error) {
+	if ref.URI == "" {
+		return nil, errors.New("file artifact path is required")
+	}
+	if r.root == "" {
+		return nil, ErrFileNotAllowed
+	}
+
+	path, err := r.resolveLexicalPath(ref.URI)
+	if err != nil {
+		return nil, err
+	}
+	return readArtifactFile(path, r.maxBytes)
+}
+
+// resolveLexicalPath checks cleaned path containment without resolving symlinks.
+func (r *restrictedArtifactReader) resolveLexicalPath(rawPath string) (string, error) {
+	cleanPath := filepath.Clean(strings.TrimSpace(rawPath))
+	candidate := cleanPath
+	if !filepath.IsAbs(cleanPath) {
+		candidate = filepath.Join(r.root, cleanPath)
+	}
+
+	absCandidate, err := filepath.Abs(candidate)
+	if err != nil {
+		return "", fmt.Errorf("resolve artifact path: %w", err)
+	}
+	absCandidate = filepath.Clean(absCandidate)
+
+	rel, err := filepath.Rel(r.root, absCandidate)
+	if err != nil {
+		return "", fmt.Errorf("compare artifact path to root: %w", err)
+	}
+	if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) || filepath.IsAbs(rel) {
+		return "", ErrFileOutsideRoot
+	}
+	return absCandidate, nil
+}
+
+func readArtifactFile(path string, maxBytes int64) (*scriptorium.Artifact, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read file %s: %w", path, err)
+	}
+	defer file.Close()
+
+	info, err := file.Stat()
+	if err != nil {
+		return nil, fmt.Errorf("failed to stat file %s: %w", path, err)
+	}
+	if maxBytes > 0 && info.Size() > maxBytes {
+		return nil, ErrFileTooLarge
+	}
+
+	var reader io.Reader = file
+	if maxBytes > 0 {
+		reader = io.LimitReader(file, maxBytes+1)
+	}
+	body, err := io.ReadAll(reader)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read file %s: %w", path, err)
+	}
+	if maxBytes > 0 && int64(len(body)) > maxBytes {
+		return nil, ErrFileTooLarge
+	}
+
+	contentType := mime.TypeByExtension(filepath.Ext(path))
+	if contentType == "" {
+		contentType = fallbackArtifactContentType
+	}
+	return &scriptorium.Artifact{
+		Name:        filepath.Base(path),
+		ContentType: contentType,
+		Body:        body,
+		URI:         path,
+		Size:        int64(len(body)),
+		Hash:        artifactHash(body),
+	}, nil
+}
+
+func artifactHash(body []byte) string {
+	return fmt.Sprintf("%x", sha256.Sum256(body))
+}

internal/adapter/http/artifact_reader_test.go

@@ -0,0 +1,180 @@
+package httpadapter
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/scriptorium"
+)
+
+func TestRestrictedArtifactReaderReadsContainedFiles(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	inputPath := filepath.Join(root, "input.html")
+	if err := os.WriteFile(inputPath, []byte("allowed"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "input.unknown"), []byte("unknown type"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Mkdir(filepath.Join(root, "nested"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(outside, "secret.txt"), []byte("denied"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	reader, err := NewRestrictedArtifactReader(root, 0)
+	if err != nil {
+		t.Fatalf("construct restricted reader: %v", err)
+	}
+
+	for _, ref := range []scriptorium.ArtifactRef{
+		{Type: scriptorium.ArtifactRefFile, URI: "nested/../input.html"},
+		{Type: scriptorium.ArtifactRefFile, URI: inputPath},
+	} {
+		artifact, err := reader.Read(context.Background(), ref)
+		if err != nil {
+			t.Fatalf("read contained path %q: %v", ref.URI, err)
+		}
+		if artifact.Name != "input.html" || artifact.URI != inputPath || artifact.Size != int64(len("allowed")) || string(artifact.Body) != "allowed" {
+			t.Fatalf("unexpected artifact metadata: %#v", artifact)
+		}
+		if artifact.ContentType != "text/html; charset=utf-8" {
+			t.Fatalf("unexpected artifact content type: %q", artifact.ContentType)
+		}
+		if artifact.Hash != artifactHash([]byte("allowed")) {
+			t.Fatalf("unexpected artifact hash: %q", artifact.Hash)
+		}
+	}
+
+	artifact, err := reader.Read(context.Background(), scriptorium.File("input.unknown"))
+	if err != nil {
+		t.Fatalf("read unknown-extension path: %v", err)
+	}
+	if artifact.ContentType != fallbackArtifactContentType {
+		t.Fatalf("unexpected fallback content type: %q", artifact.ContentType)
+	}
+
+	for _, ref := range []scriptorium.ArtifactRef{
+		{Type: scriptorium.ArtifactRefFile, URI: filepath.Join("..", filepath.Base(outside), "secret.txt")},
+		{Type: scriptorium.ArtifactRefFile, URI: filepath.Join(outside, "secret.txt")},
+	} {
+		_, err := reader.Read(context.Background(), ref)
+		if !errors.Is(err, ErrFileOutsideRoot) {
+			t.Fatalf("expected ErrFileOutsideRoot for %q, got %v", ref.URI, err)
+		}
+	}
+}
+
+func TestRestrictedArtifactReaderFollowsSymlinkAfterLexicalCheck(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	target := filepath.Join(outside, "linked.txt")
+	if err := os.WriteFile(target, []byte("linked outside root"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(target, filepath.Join(root, "linked.txt")); err != nil {
+		t.Skipf("symlink creation unavailable: %v", err)
+	}
+
+	reader, err := NewRestrictedArtifactReader(root, 0)
+	if err != nil {
+		t.Fatalf("construct restricted reader: %v", err)
+	}
+	artifact, err := reader.Read(context.Background(), scriptorium.File("linked.txt"))
+	if err != nil {
+		t.Fatalf("read symlink inside root: %v", err)
+	}
+	if string(artifact.Body) != "linked outside root" {
+		t.Fatalf("unexpected symlink artifact body: %q", artifact.Body)
+	}
+}
+
+func TestRestrictedArtifactReaderWithoutRootDeniesFiles(t *testing.T) {
+	reader, err := NewRestrictedArtifactReader("", 0)
+	if err != nil {
+		t.Fatalf("construct rootless reader: %v", err)
+	}
+
+	artifact, err := reader.Read(context.Background(), scriptorium.Inline("inline"))
+	if err != nil {
+		t.Fatalf("read inline artifact: %v", err)
+	}
+	if artifact.ContentType != fallbackArtifactContentType || string(artifact.Body) != "inline" || artifact.Hash != artifactHash([]byte("inline")) {
+		t.Fatalf("unexpected inline artifact: %#v", artifact)
+	}
+
+	_, err = reader.Read(context.Background(), scriptorium.File("input.txt"))
+	if !errors.Is(err, ErrFileNotAllowed) {
+		t.Fatalf("expected ErrFileNotAllowed, got %v", err)
+	}
+}
+
+func TestRestrictedArtifactReaderEnforcesLimits(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "exact.txt"), []byte("12345"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "large.txt"), []byte("123456"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	reader, err := NewRestrictedArtifactReader(root, 5)
+	if err != nil {
+		t.Fatalf("construct limited reader: %v", err)
+	}
+	artifact, err := reader.Read(context.Background(), scriptorium.File("exact.txt"))
+	if err != nil || string(artifact.Body) != "12345" {
+		t.Fatalf("expected exact-limit artifact, got %#v and %v", artifact, err)
+	}
+	_, err = reader.Read(context.Background(), scriptorium.File("large.txt"))
+	if !errors.Is(err, ErrFileTooLarge) {
+		t.Fatalf("expected ErrFileTooLarge, got %v", err)
+	}
+
+	unlimited, err := NewRestrictedArtifactReader(root, 0)
+	if err != nil {
+		t.Fatalf("construct unlimited reader: %v", err)
+	}
+	artifact, err = unlimited.Read(context.Background(), scriptorium.File("large.txt"))
+	if err != nil || string(artifact.Body) != "123456" {
+		t.Fatalf("expected unlimited artifact, got %#v and %v", artifact, err)
+	}
+
+	if _, err := NewRestrictedArtifactReader(root, -1); err == nil {
+		t.Fatal("expected negative limit to fail")
+	}
+}
+
+func TestRestrictedArtifactReaderRejectsCanceledAndMalformedReferences(t *testing.T) {
+	reader, err := NewRestrictedArtifactReader(t.TempDir(), 0)
+	if err != nil {
+		t.Fatalf("construct reader: %v", err)
+	}
+
+	canceledCtx, cancel := context.WithCancel(context.Background())
+	cancel()
+	for _, ref := range []scriptorium.ArtifactRef{
+		scriptorium.Inline("input"),
+		scriptorium.File("input.txt"),
+	} {
+		_, err := reader.Read(canceledCtx, ref)
+		if !errors.Is(err, context.Canceled) {
+			t.Fatalf("expected cancellation for %#v, got %v", ref, err)
+		}
+	}
+
+	for _, ref := range []scriptorium.ArtifactRef{
+		{Type: scriptorium.ArtifactRefType("unsupported")},
+		{Type: scriptorium.ArtifactRefInline},
+		{Type: scriptorium.ArtifactRefFile},
+	} {
+		if _, err := reader.Read(context.Background(), ref); err == nil {
+			t.Fatalf("expected malformed reference %#v to fail", ref)
+		}
+	}
+}

internal/adapter/http/handler.go

@@ -4,25 +4,37 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"io"
 	"net/http"
 	"strings"
 
-	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/promptdef"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/usecase"
+	"gitea.maximumdirect.net/eric/scriptorium"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
 )
 
 type Runner interface {
-	Run(ctx context.Context, req domain.RunRequest) (*domain.RunResult, error)
+	Run(ctx context.Context, req scriptorium.RunRequest) (*scriptorium.RunResult, error)
 }
 
 type Handler struct {
-	runner Runner
+	runner  Runner
+	options HandlerOptions
+}
+
+type HandlerOptions struct {
+	MaxRequestBytes  int64
+	MaxResponseBytes int64
 }
 
 func NewHandler(runner Runner) *Handler {
-	return &Handler{runner: runner}
+	return NewHandlerWithOptions(runner, HandlerOptions{
+		MaxRequestBytes:  defaults.HTTPMaxRequestBytesDefault,
+		MaxResponseBytes: defaults.HTTPMaxResponseBytesDefault,
+	})
+}
+
+func NewHandlerWithOptions(runner Runner, options HandlerOptions) *Handler {
+	return &Handler{runner: runner, options: options}
 }
 
 func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
@@ -36,9 +48,26 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	}
 
 	var req runRequestDTO
-	dec := json.NewDecoder(r.Body)
+	body := r.Body
+	if h.options.MaxRequestBytes > 0 {
+		body = http.MaxBytesReader(w, r.Body, h.options.MaxRequestBytes)
+	}
+	dec := json.NewDecoder(body)
 	dec.DisallowUnknownFields()
 	if err := dec.Decode(&req); err != nil {
+		if isRequestTooLarge(err) {
+			writeError(w, http.StatusRequestEntityTooLarge, "request_too_large", "request body is too large")
+			return
+		}
+		writeError(w, http.StatusBadRequest, "invalid_json", "invalid JSON request body")
+		return
+	}
+	var trailing any
+	if err := dec.Decode(&trailing); err != io.EOF {
+		if isRequestTooLarge(err) {
+			writeError(w, http.StatusRequestEntityTooLarge, "request_too_large", "request body is too large")
+			return
+		}
 		writeError(w, http.StatusBadRequest, "invalid_json", "invalid JSON request body")
 		return
 	}
@@ -52,21 +81,21 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	mappedInputs := make(map[string]domain.ArtifactRef, len(req.Inputs))
+	mappedInputs := make(map[string]scriptorium.ArtifactRef, len(req.Inputs))
 	for name, in := range req.Inputs {
-		mappedInputs[name] = domain.ArtifactRef{
-			Type: domain.ArtifactRefType(in.Type),
+		mappedInputs[name] = scriptorium.ArtifactRef{
+			Type: scriptorium.ArtifactRefType(in.Type),
 			URI:  in.URI,
 			Body: in.Body,
 		}
 	}
 
-	var model *domain.ExecutionTargetOverride
+	var model *scriptorium.ExecutionTargetOverride
 	if req.Model != nil {
 		model = executionTargetOverrideFromModelOverrideDTO(req.Model)
 	}
 
-	res, err := h.runner.Run(r.Context(), domain.RunRequest{
+	res, err := h.runner.Run(r.Context(), scriptorium.RunRequest{
 		PromptID:      req.PromptID,
 		PromptVersion: req.PromptVersion,
 		ProfileID:     req.ProfileID,
@@ -120,14 +149,14 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		raw := res.RawOutput
 		resp.RawModelOutput = &raw
 	}
-	writeJSON(w, http.StatusOK, resp)
+	writeLimitedJSON(w, http.StatusOK, resp, h.options.MaxResponseBytes)
 }
 
-func executionTargetOverrideFromModelOverrideDTO(dto *modelOverrideRequestDTO) *domain.ExecutionTargetOverride {
+func executionTargetOverrideFromModelOverrideDTO(dto *modelOverrideRequestDTO) *scriptorium.ExecutionTargetOverride {
 	if dto == nil {
 		return nil
 	}
-	return &domain.ExecutionTargetOverride{
+	return &scriptorium.ExecutionTargetOverride{
 		Endpoint:        dto.Endpoint,
 		Model:           dto.Model,
 		Temperature:     dto.Temperature,
@@ -141,7 +170,7 @@ func executionTargetOverrideFromModelOverrideDTO(dto *modelOverrideRequestDTO) *
 	}
 }
 
-func modelParamsDTOFromExecutionTarget(target domain.ExecutionTarget) modelParamsDTO {
+func modelParamsDTOFromExecutionTarget(target scriptorium.ExecutionTarget) modelParamsDTO {
 	return modelParamsDTO{
 		Endpoint:        target.Endpoint,
 		Model:           target.Model,
@@ -156,7 +185,7 @@ func modelParamsDTOFromExecutionTarget(target domain.ExecutionTarget) modelParam
 	}
 }
 
-func mapValidation(v domain.ValidationResult) validationDTO {
+func mapValidation(v scriptorium.ValidationResult) validationDTO {
 	return validationDTO{
 		Status:         string(v.Status),
 		Mode:           string(v.Mode),
@@ -169,29 +198,31 @@ func mapValidation(v domain.ValidationResult) validationDTO {
 
 func mapRunError(err error) (int, string, string) {
 	switch {
-	case errors.Is(err, promptdef.ErrPromptDefinitionNotFound):
+	case errors.Is(err, scriptorium.ErrPromptNotFound):
 		return http.StatusNotFound, "prompt_not_found", "prompt definition not found"
-	case errors.Is(err, profile.ErrProfileNotFound):
+	case errors.Is(err, scriptorium.ErrProfileNotFound):
 		return http.StatusNotFound, "profile_not_found", "execution profile not found"
-	case errors.Is(err, promptdef.ErrInvalidYAML), errors.Is(err, promptdef.ErrInvalidPromptDefinition):
-		return http.StatusBadRequest, "prompt_load_failed", "failed to load prompt definition"
-	case errors.Is(err, profile.ErrInvalidYAML), errors.Is(err, profile.ErrInvalidProfile):
-		return http.StatusBadRequest, "profile_load_failed", "failed to load execution profile"
-	case errors.Is(err, usecase.ErrProfileRequired):
+	case errors.Is(err, scriptorium.ErrProfileRequired):
 		return http.StatusBadRequest, "profile_required", "profile_id is required when prompt default_profile is not set"
-	case errors.Is(err, usecase.ErrAPIKeyEnvMissing):
+	case errors.Is(err, scriptorium.ErrAPIKeyEnvMissing):
 		return http.StatusBadRequest, "api_key_env_missing", "api_key_env is set but the environment variable is missing"
-	case errors.Is(err, usecase.ErrInvalidRequest):
-		return http.StatusBadRequest, "invalid_request", "invalid run request"
-	case errors.Is(err, usecase.ErrProfileLoad):
+	case errors.Is(err, scriptorium.ErrPromptLoad):
 		return http.StatusBadRequest, "prompt_load_failed", "failed to load prompt definition"
-	case errors.Is(err, usecase.ErrArtifactLoad):
+	case errors.Is(err, scriptorium.ErrProfileLoad):
+		return http.StatusBadRequest, "profile_load_failed", "failed to load execution profile"
+	case errors.Is(err, scriptorium.ErrInvalidRequest):
+		return http.StatusBadRequest, "invalid_request", "invalid run request"
+	case errors.Is(err, ErrFileNotAllowed), errors.Is(err, ErrFileOutsideRoot):
+		return http.StatusBadRequest, "artifact_not_allowed", "file input artifact is not allowed"
+	case errors.Is(err, ErrFileTooLarge):
+		return http.StatusRequestEntityTooLarge, "artifact_too_large", "file input artifact is too large"
+	case errors.Is(err, scriptorium.ErrArtifactLoad):
 		return http.StatusBadRequest, "artifact_read_failed", "failed to read input artifact"
-	case errors.Is(err, usecase.ErrPromptRender):
+	case errors.Is(err, scriptorium.ErrPromptRender):
 		return http.StatusBadRequest, "prompt_render_failed", "failed to render prompt"
-	case errors.Is(err, usecase.ErrLLMGenerate):
+	case errors.Is(err, scriptorium.ErrLLMGenerate):
 		return http.StatusBadGateway, "llm_failed", "model generation request failed"
-	case errors.Is(err, usecase.ErrValidation):
+	case errors.Is(err, scriptorium.ErrValidation):
 		return http.StatusInternalServerError, "validation_runtime_failed", "validation runtime failed"
 	default:
 		return http.StatusInternalServerError, "internal_error", "internal server error"
@@ -199,9 +230,23 @@ func mapRunError(err error) (int, string, string) {
 }
 
 func writeJSON(w http.ResponseWriter, status int, v any) {
+	writeLimitedJSON(w, status, v, 0)
+}
+
+func writeLimitedJSON(w http.ResponseWriter, status int, v any, maxBytes int64) {
+	data, err := json.Marshal(v)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "internal_error", "internal server error")
+		return
+	}
+	data = append(data, '\n')
+	if maxBytes > 0 && int64(len(data)) > maxBytes {
+		writeError(w, http.StatusRequestEntityTooLarge, "response_too_large", "response body is too large")
+		return
+	}
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(v)
+	_, _ = w.Write(data)
 }
 
 func writeError(w http.ResponseWriter, status int, code, message string) {
@@ -212,3 +257,8 @@ func writeError(w http.ResponseWriter, status int, code, message string) {
 		},
 	})
 }
+
+func isRequestTooLarge(err error) bool {
+	var maxBytesErr *http.MaxBytesError
+	return errors.As(err, &maxBytesErr)
+}

internal/adapter/http/handler_test.go

@@ -7,25 +7,23 @@ import (
 	"fmt"
 	"net/http"
 	"net/http/httptest"
+	"os"
+	"path/filepath"
 	"reflect"
 	"strings"
 	"testing"
 	"time"
 
-	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/llm"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/promptdef"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/usecase"
+	"gitea.maximumdirect.net/eric/scriptorium"
 )
 
 type fakeRunner struct {
-	result *domain.RunResult
+	result *scriptorium.RunResult
 	err    error
-	last   domain.RunRequest
+	last   scriptorium.RunRequest
 }
 
-func (f *fakeRunner) Run(ctx context.Context, req domain.RunRequest) (*domain.RunResult, error) {
+func (f *fakeRunner) Run(ctx context.Context, req scriptorium.RunRequest) (*scriptorium.RunResult, error) {
 	f.last = req
 	if f.err != nil {
 		return nil, f.err
@@ -33,32 +31,42 @@ func (f *fakeRunner) Run(ctx context.Context, req domain.RunRequest) (*domain.Ru
 	return f.result, nil
 }
 
-type handlerPromptRepo struct {
-	def *domain.PromptDefinition
+func TestMaintainedHTTPRunExampleMatchesRequestContract(t *testing.T) {
+	body, err := os.ReadFile(filepath.Join("..", "..", "..", "examples", "http-run.json"))
+	if err != nil {
+		t.Fatalf("read maintained HTTP request example: %v", err)
+	}
+
+	runner := &fakeRunner{result: &scriptorium.RunResult{}}
+	h := NewHandler(runner)
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewReader(body))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected maintained HTTP request example to be accepted, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var invalidExample map[string]json.RawMessage
+	if err := json.Unmarshal(body, &invalidExample); err != nil {
+		t.Fatalf("decode maintained HTTP request example: %v", err)
+	}
+	invalidExample["unexpected"] = json.RawMessage(`true`)
+	invalidBody, err := json.Marshal(invalidExample)
+	if err != nil {
+		t.Fatalf("encode structurally invalid request example: %v", err)
+	}
+	invalidReq := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewReader(invalidBody))
+	invalidW := httptest.NewRecorder()
+	h.ServeHTTP(invalidW, invalidReq)
+	assertHTTPErrorCode(t, invalidW, http.StatusBadRequest, "invalid_json")
 }
 
-func (r handlerPromptRepo) GetPromptDefinition(ctx context.Context, id string, version string) (*domain.PromptDefinition, error) {
-	return r.def, nil
-}
+type handlerLLMClient struct{}
 
-type handlerProfileRepo struct {
-	profile *domain.ExecutionProfile
-}
-
-func (r handlerProfileRepo) GetProfile(ctx context.Context, id string) (*domain.ExecutionProfile, error) {
-	return r.profile, nil
-}
-
-type handlerArtifactReader struct{}
-
-func (handlerArtifactReader) Read(ctx context.Context, ref domain.ArtifactRef) (*domain.Artifact, error) {
-	return &domain.Artifact{Name: "input", Body: []byte("input"), Hash: "hash"}, nil
-}
-
-type handlerRenderer struct{}
-
-func (handlerRenderer) Render(ctx context.Context, definition *domain.PromptDefinition, inputs map[string]*domain.Artifact, vars map[string]string) (*domain.RenderedPrompt, error) {
-	return &domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}}, nil
+func (handlerLLMClient) Generate(ctx context.Context, req scriptorium.GenerateRequest) (*scriptorium.GenerateResponse, error) {
+	return &scriptorium.GenerateResponse{Content: "ok"}, nil
 }
 
 func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
@@ -67,16 +75,16 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
 	const envName = "SCRIPTORIUM_API_KEY"
 	const secret = "never-include-me"
 
-	r := &fakeRunner{result: &domain.RunResult{
+	r := &fakeRunner{result: &scriptorium.RunResult{
 		RunID: "11111111-1111-4111-8111-111111111111",
-		Artifact: domain.Artifact{
+		Artifact: scriptorium.Artifact{
 			Name:        "output",
 			ContentType: "text/plain",
 			Body:        []byte("hello"),
 			Size:        5,
 			Hash:        "abc",
 		},
-		Validation:         domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic, IsValid: true},
+		Validation:         scriptorium.ValidationResult{Status: scriptorium.ValidationPassed, Mode: scriptorium.ValidationBasic, IsValid: true},
 		PromptID:           "prompt-1",
 		PromptVersion:      "1.0.0",
 		PromptHash:         "phash",
@@ -84,7 +92,7 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
 		SelectedProfileID:  "exec-default",
 		ModelName:          "m1",
 		Endpoint:           "http://llm/v1",
-		EffectiveModelParams: domain.ExecutionTarget{
+		EffectiveModelParams: scriptorium.ExecutionTarget{
 			Endpoint:       "http://llm/v1",
 			Model:          "m1",
 			Temperature:    0.2,
@@ -95,7 +103,7 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
 			APIKeyEnv:      envName,
 		},
 		InputHashes: map[string]string{"transcript": "h1"},
-		Usage: domain.TokenUsage{
+		Usage: scriptorium.TokenUsage{
 			PromptTokens:     1,
 			CompletionTokens: 2,
 			TotalTokens:      3,
@@ -184,14 +192,113 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
 	}
 }
 
+func TestHandlerInlineRefsWorkWithoutArtifactRoot(t *testing.T) {
+	h := newArtifactRootHandler(t, "")
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{
+		"prompt_id":"p",
+		"inputs":{"x":{"type":"inline","body":"inline body"}}
+	}`))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", w.Code, w.Body.String())
+	}
+}
+
+func TestHandlerFileRefsWithoutArtifactRootAreRejected(t *testing.T) {
+	h := newArtifactRootHandler(t, "")
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{
+		"prompt_id":"p",
+		"inputs":{"x":{"type":"file","uri":"input.txt"}}
+	}`))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	assertHTTPErrorCode(t, w, http.StatusBadRequest, "artifact_not_allowed")
+}
+
+func TestHandlerFileRefsUnderArtifactRootWork(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "input.txt"), []byte("allowed"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	h := newArtifactRootHandler(t, root)
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{
+		"prompt_id":"p",
+		"inputs":{"x":{"type":"file","uri":"input.txt"}}
+	}`))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", w.Code, w.Body.String())
+	}
+}
+
+func TestHandlerFileRefsAboveArtifactLimitAreRejected(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "large.txt"), []byte("123456"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	h := newArtifactRootHandlerWithLimit(t, root, 5)
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{
+		"prompt_id":"p",
+		"inputs":{"x":{"type":"file","uri":"large.txt"}}
+	}`))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	assertHTTPErrorCode(t, w, http.StatusRequestEntityTooLarge, "artifact_too_large")
+}
+
+func TestHandlerFileRefsOutsideArtifactRootAreRejected(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	if err := os.WriteFile(filepath.Join(outside, "secret.txt"), []byte("denied"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	h := newArtifactRootHandler(t, root)
+
+	tests := []struct {
+		name string
+		uri  string
+	}{
+		{name: "relative traversal", uri: filepath.Join("..", filepath.Base(outside), "secret.txt")},
+		{name: "absolute outside root", uri: filepath.Join(outside, "secret.txt")},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			body := fmt.Sprintf(`{
+				"prompt_id":"p",
+				"inputs":{"x":{"type":"file","uri":%q}}
+			}`, tc.uri)
+			req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(body))
+			w := httptest.NewRecorder()
+
+			h.ServeHTTP(w, req)
+
+			assertHTTPErrorCode(t, w, http.StatusBadRequest, "artifact_not_allowed")
+		})
+	}
+}
+
 func TestHandlerPostRunsSuccessUsingPromptDefaultProfile(t *testing.T) {
-	r := &fakeRunner{result: &domain.RunResult{
-		Artifact:             domain.Artifact{Body: []byte("ok")},
+	r := &fakeRunner{result: &scriptorium.RunResult{
+		Artifact:             scriptorium.Artifact{Body: []byte("ok")},
 		PromptID:             "prompt-1",
 		PromptVersion:        "1.0.0",
 		SelectedProfileID:    "prompt-default",
-		Validation:           domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic, IsValid: true},
-		EffectiveModelParams: domain.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
+		Validation:           scriptorium.ValidationResult{Status: scriptorium.ValidationPassed, Mode: scriptorium.ValidationBasic, IsValid: true},
+		EffectiveModelParams: scriptorium.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
 	}}
 	h := NewHandler(r)
 
@@ -220,10 +327,10 @@ func TestHandlerPostRunsSuccessUsingPromptDefaultProfile(t *testing.T) {
 }
 
 func TestHandlerModelOverrideMapsAllSupportedExecutionFields(t *testing.T) {
-	r := &fakeRunner{result: &domain.RunResult{
-		Artifact:             domain.Artifact{Body: []byte("ok")},
-		Validation:           domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic, IsValid: true},
-		EffectiveModelParams: domain.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
+	r := &fakeRunner{result: &scriptorium.RunResult{
+		Artifact:             scriptorium.Artifact{Body: []byte("ok")},
+		Validation:           scriptorium.ValidationResult{Status: scriptorium.ValidationPassed, Mode: scriptorium.ValidationBasic, IsValid: true},
+		EffectiveModelParams: scriptorium.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
 	}}
 	h := NewHandler(r)
 
@@ -280,10 +387,10 @@ func TestHandlerModelOverrideMapsAllSupportedExecutionFields(t *testing.T) {
 }
 
 func TestHandlerModelOverrideAcceptsJSONCompatibleExtraParams(t *testing.T) {
-	r := &fakeRunner{result: &domain.RunResult{
-		Artifact:             domain.Artifact{Body: []byte("ok")},
-		Validation:           domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic, IsValid: true},
-		EffectiveModelParams: domain.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
+	r := &fakeRunner{result: &scriptorium.RunResult{
+		Artifact:             scriptorium.Artifact{Body: []byte("ok")},
+		Validation:           scriptorium.ValidationResult{Status: scriptorium.ValidationPassed, Mode: scriptorium.ValidationBasic, IsValid: true},
+		EffectiveModelParams: scriptorium.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
 	}}
 	h := NewHandler(r)
 
@@ -324,10 +431,10 @@ func TestHandlerModelOverrideAcceptsJSONCompatibleExtraParams(t *testing.T) {
 }
 
 func TestHandlerModelOverrideExplicitZeroTemperatureMapsAsPresent(t *testing.T) {
-	r := &fakeRunner{result: &domain.RunResult{
-		Artifact:             domain.Artifact{Body: []byte("ok")},
-		Validation:           domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic, IsValid: true},
-		EffectiveModelParams: domain.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1", Temperature: 0},
+	r := &fakeRunner{result: &scriptorium.RunResult{
+		Artifact:             scriptorium.Artifact{Body: []byte("ok")},
+		Validation:           scriptorium.ValidationResult{Status: scriptorium.ValidationPassed, Mode: scriptorium.ValidationBasic, IsValid: true},
+		EffectiveModelParams: scriptorium.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1", Temperature: 0},
 	}}
 	h := NewHandler(r)
 
@@ -351,10 +458,10 @@ func TestHandlerModelOverrideExplicitZeroTemperatureMapsAsPresent(t *testing.T)
 }
 
 func TestHandlerModelOverrideOmittedTemperatureMapsAsAbsent(t *testing.T) {
-	r := &fakeRunner{result: &domain.RunResult{
-		Artifact:             domain.Artifact{Body: []byte("ok")},
-		Validation:           domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic, IsValid: true},
-		EffectiveModelParams: domain.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1", Temperature: 0.7},
+	r := &fakeRunner{result: &scriptorium.RunResult{
+		Artifact:             scriptorium.Artifact{Body: []byte("ok")},
+		Validation:           scriptorium.ValidationResult{Status: scriptorium.ValidationPassed, Mode: scriptorium.ValidationBasic, IsValid: true},
+		EffectiveModelParams: scriptorium.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1", Temperature: 0.7},
 	}}
 	h := NewHandler(r)
 
@@ -388,16 +495,16 @@ func TestHandlerModelOverrideOmittedTemperatureMapsAsAbsent(t *testing.T) {
 }
 
 func TestHandlerResponseMetadataModelParamsIncludesAllSupportedFields(t *testing.T) {
-	r := &fakeRunner{result: &domain.RunResult{
-		Artifact: domain.Artifact{
+	r := &fakeRunner{result: &scriptorium.RunResult{
+		Artifact: scriptorium.Artifact{
 			Name:        "output",
 			ContentType: "text/plain",
 			Body:        []byte("ok"),
 			Size:        2,
 			Hash:        "abc",
 		},
-		Validation: domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic, IsValid: true},
-		EffectiveModelParams: domain.ExecutionTarget{
+		Validation: scriptorium.ValidationResult{Status: scriptorium.ValidationPassed, Mode: scriptorium.ValidationBasic, IsValid: true},
+		EffectiveModelParams: scriptorium.ExecutionTarget{
 			Endpoint:        "http://llm/v1",
 			Model:           "gpt-test",
 			Temperature:     0.4,
@@ -486,6 +593,69 @@ func TestHandlerInvalidJSON(t *testing.T) {
 	}
 }
 
+func TestHandlerRejectsTrailingJSON(t *testing.T) {
+	h := NewHandler(&fakeRunner{})
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{"prompt_id":"p","inputs":{"x":{"type":"file","uri":"a"}}} {}`))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	assertHTTPErrorCode(t, w, http.StatusBadRequest, "invalid_json")
+}
+
+func TestHandlerRequestTooLarge(t *testing.T) {
+	h := NewHandlerWithOptions(&fakeRunner{}, HandlerOptions{MaxRequestBytes: 12})
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{"prompt_id":"p","inputs":{"x":{"type":"file","uri":"a"}}}`))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	assertHTTPErrorCode(t, w, http.StatusRequestEntityTooLarge, "request_too_large")
+}
+
+func TestHandlerMalformedJSONBelowLimitStillBadRequest(t *testing.T) {
+	h := NewHandlerWithOptions(&fakeRunner{}, HandlerOptions{MaxRequestBytes: 1024})
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString("{"))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	assertHTTPErrorCode(t, w, http.StatusBadRequest, "invalid_json")
+}
+
+func TestHandlerResponseTooLarge(t *testing.T) {
+	h := NewHandlerWithOptions(&fakeRunner{result: &scriptorium.RunResult{
+		Artifact:             scriptorium.Artifact{Body: []byte(strings.Repeat("x", 128))},
+		Validation:           scriptorium.ValidationResult{Status: scriptorium.ValidationPassed, Mode: scriptorium.ValidationBasic, IsValid: true},
+		EffectiveModelParams: scriptorium.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
+	}}, HandlerOptions{MaxRequestBytes: 1024, MaxResponseBytes: 64})
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{"prompt_id":"p","inputs":{"x":{"type":"file","uri":"a"}}}`))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	assertHTTPErrorCode(t, w, http.StatusRequestEntityTooLarge, "response_too_large")
+}
+
+func TestHandlerRawOutputDoesNotBypassResponseLimit(t *testing.T) {
+	h := NewHandlerWithOptions(&fakeRunner{result: &scriptorium.RunResult{
+		Artifact:             scriptorium.Artifact{Body: []byte("ok")},
+		RawOutput:            strings.Repeat("raw", 80),
+		Validation:           scriptorium.ValidationResult{Status: scriptorium.ValidationPassed, Mode: scriptorium.ValidationBasic, IsValid: true},
+		EffectiveModelParams: scriptorium.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
+	}}, HandlerOptions{MaxRequestBytes: 1024, MaxResponseBytes: 128})
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{
+		"prompt_id":"p",
+		"inputs":{"x":{"type":"file","uri":"a"}},
+		"include_raw_output":true
+	}`))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	assertHTTPErrorCode(t, w, http.StatusRequestEntityTooLarge, "response_too_large")
+}
+
 func TestHandlerMissingPromptID(t *testing.T) {
 	h := NewHandler(&fakeRunner{})
 	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{"inputs":{"x":{"type":"file","uri":"a"}}}`))
@@ -506,35 +676,12 @@ func TestHandlerMissingPromptID(t *testing.T) {
 	}
 }
 
-func TestHandlerReservedExtraParamsThroughRunnerMapsToInvalidRequest(t *testing.T) {
-	llmClient, err := llm.NewOpenAICompatibleClient(llm.OpenAICompatibleConfig{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	runner := usecase.NewRunner(
-		handlerPromptRepo{def: &domain.PromptDefinition{
-			ID:             "p",
-			Version:        "1",
-			DefaultProfile: "exec",
-			Templates:      []domain.PromptMessageTemplate{{Role: "user", Content: "hi"}},
-			OutputFormat:   domain.FormatText,
-			Validation:     domain.OutputContract{Format: domain.FormatText, ValidationMode: domain.ValidationNone},
-		}},
-		handlerProfileRepo{profile: &domain.ExecutionProfile{
-			ID:       "exec",
-			Endpoint: "http://example.invalid/v1",
-			Model:    "model",
-		}},
-		handlerArtifactReader{},
-		handlerRenderer{},
-		llmClient,
-		nil,
-	)
-	h := NewHandler(runner)
+func TestHandlerReservedExtraParamsThroughEngineMapsToInvalidRequest(t *testing.T) {
+	h := NewHandler(newHandlerEngineWithDefaultClient(t))
 
 	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{
 		"prompt_id":"p",
-		"inputs":{"x":{"type":"file","uri":"a"}},
+		"inputs":{"x":{"type":"inline","body":"input"}},
 		"model":{"extra_params":{"model":"collision"}}
 	}`))
 	w := httptest.NewRecorder()
@@ -554,7 +701,7 @@ func TestHandlerReservedExtraParamsThroughRunnerMapsToInvalidRequest(t *testing.
 	}
 }
 
-func TestHandlerUsecaseErrorMapping(t *testing.T) {
+func TestHandlerPublicErrorMapping(t *testing.T) {
 	tests := []struct {
 		name       string
 		err        error
@@ -563,16 +710,20 @@ func TestHandlerUsecaseErrorMapping(t *testing.T) {
 		message    string
 		avoidCause string
 	}{
-		{name: "prompt not found", err: wrap(usecase.ErrProfileLoad, promptdef.ErrPromptDefinitionNotFound), status: http.StatusNotFound, code: "prompt_not_found", message: "prompt definition not found"},
-		{name: "prompt load invalid", err: wrap(usecase.ErrProfileLoad, promptdef.ErrInvalidPromptDefinition), status: http.StatusBadRequest, code: "prompt_load_failed", message: "failed to load prompt definition"},
-		{name: "missing profile/default", err: wrap(usecase.ErrInvalidRequest, usecase.ErrProfileRequired), status: http.StatusBadRequest, code: "profile_required", message: "profile_id is required when prompt default_profile is not set"},
-		{name: "profile not found", err: wrap(usecase.ErrProfileLoad, profile.ErrProfileNotFound), status: http.StatusNotFound, code: "profile_not_found", message: "execution profile not found"},
-		{name: "profile invalid", err: wrap(usecase.ErrProfileLoad, profile.ErrInvalidProfile), status: http.StatusBadRequest, code: "profile_load_failed", message: "failed to load execution profile"},
-		{name: "api key env missing", err: wrap(usecase.ErrInvalidRequest, usecase.ErrAPIKeyEnvMissing), status: http.StatusBadRequest, code: "api_key_env_missing", message: "api_key_env is set but the environment variable is missing"},
-		{name: "artifact", err: wrap(usecase.ErrArtifactLoad, fmt.Errorf("read failed")), status: http.StatusBadRequest, code: "artifact_read_failed", message: "failed to read input artifact", avoidCause: "read failed"},
-		{name: "prompt render", err: wrap(usecase.ErrPromptRender, fmt.Errorf("render failed")), status: http.StatusBadRequest, code: "prompt_render_failed", message: "failed to render prompt", avoidCause: "render failed"},
-		{name: "llm", err: wrap(usecase.ErrLLMGenerate, fmt.Errorf("llm failed")), status: http.StatusBadGateway, code: "llm_failed", message: "model generation request failed", avoidCause: "llm failed"},
-		{name: "validation runtime", err: wrap(usecase.ErrValidation, fmt.Errorf("validator broke")), status: http.StatusInternalServerError, code: "validation_runtime_failed", message: "validation runtime failed", avoidCause: "validator broke"},
+		{name: "prompt not found", err: scriptorium.ErrPromptNotFound, status: http.StatusNotFound, code: "prompt_not_found", message: "prompt definition not found"},
+		{name: "prompt load", err: wrap(scriptorium.ErrPromptLoad, fmt.Errorf("read failed")), status: http.StatusBadRequest, code: "prompt_load_failed", message: "failed to load prompt definition", avoidCause: "read failed"},
+		{name: "missing profile/default", err: wrap(scriptorium.ErrProfileRequired, scriptorium.ErrInvalidRequest), status: http.StatusBadRequest, code: "profile_required", message: "profile_id is required when prompt default_profile is not set"},
+		{name: "profile not found", err: scriptorium.ErrProfileNotFound, status: http.StatusNotFound, code: "profile_not_found", message: "execution profile not found"},
+		{name: "profile load", err: wrap(scriptorium.ErrProfileLoad, fmt.Errorf("read failed")), status: http.StatusBadRequest, code: "profile_load_failed", message: "failed to load execution profile", avoidCause: "read failed"},
+		{name: "api key env missing", err: wrap(scriptorium.ErrAPIKeyEnvMissing, scriptorium.ErrInvalidRequest), status: http.StatusBadRequest, code: "api_key_env_missing", message: "api_key_env is set but the environment variable is missing"},
+		{name: "invalid request", err: scriptorium.ErrInvalidRequest, status: http.StatusBadRequest, code: "invalid_request", message: "invalid run request"},
+		{name: "file denied", err: ErrFileNotAllowed, status: http.StatusBadRequest, code: "artifact_not_allowed", message: "file input artifact is not allowed"},
+		{name: "file outside root", err: ErrFileOutsideRoot, status: http.StatusBadRequest, code: "artifact_not_allowed", message: "file input artifact is not allowed"},
+		{name: "file too large", err: ErrFileTooLarge, status: http.StatusRequestEntityTooLarge, code: "artifact_too_large", message: "file input artifact is too large"},
+		{name: "artifact", err: wrap(scriptorium.ErrArtifactLoad, fmt.Errorf("read failed")), status: http.StatusBadRequest, code: "artifact_read_failed", message: "failed to read input artifact", avoidCause: "read failed"},
+		{name: "prompt render", err: wrap(scriptorium.ErrPromptRender, fmt.Errorf("render failed")), status: http.StatusBadRequest, code: "prompt_render_failed", message: "failed to render prompt", avoidCause: "render failed"},
+		{name: "llm", err: wrap(scriptorium.ErrLLMGenerate, fmt.Errorf("llm failed")), status: http.StatusBadGateway, code: "llm_failed", message: "model generation request failed", avoidCause: "llm failed"},
+		{name: "validation runtime", err: wrap(scriptorium.ErrValidation, fmt.Errorf("validator broke")), status: http.StatusInternalServerError, code: "validation_runtime_failed", message: "validation runtime failed", avoidCause: "validator broke"},
 	}
 
 	for _, tc := range tests {
@@ -625,12 +776,12 @@ func TestHandlerRawAPIKeyRejectedByStrictJSON(t *testing.T) {
 }
 
 func TestHandlerValidationFailureStillSuccessAndRawOutputOptIn(t *testing.T) {
-	h := NewHandler(&fakeRunner{result: &domain.RunResult{
-		Artifact:  domain.Artifact{Body: []byte("bad json")},
+	h := NewHandler(&fakeRunner{result: &scriptorium.RunResult{
+		Artifact:  scriptorium.Artifact{Body: []byte("bad json")},
 		RawOutput: "bad json",
-		Validation: domain.ValidationResult{
-			Status: domain.ValidationFailed,
-			Mode:   domain.ValidationJSON,
+		Validation: scriptorium.ValidationResult{
+			Status: scriptorium.ValidationFailed,
+			Mode:   scriptorium.ValidationJSON,
 			Errors: []string{"invalid JSON"},
 		},
 	}})
@@ -674,3 +825,82 @@ func TestHandlerValidationFailureStillSuccessAndRawOutputOptIn(t *testing.T) {
 func wrap(stage error, cause error) error {
 	return fmt.Errorf("%w: %w", stage, cause)
 }
+
+func newArtifactRootHandler(t *testing.T, root string) *Handler {
+	t.Helper()
+
+	return newArtifactRootHandlerWithLimit(t, root, 0)
+}
+
+func newArtifactRootHandlerWithLimit(t *testing.T, root string, maxArtifactBytes int64) *Handler {
+	t.Helper()
+
+	reader, err := NewRestrictedArtifactReader(root, maxArtifactBytes)
+	if err != nil {
+		t.Fatalf("expected restricted artifact reader: %v", err)
+	}
+	return NewHandler(newHandlerEngine(t, scriptorium.WithArtifactReader(reader)))
+}
+
+func newHandlerEngine(t *testing.T, options ...scriptorium.Option) *scriptorium.Engine {
+	t.Helper()
+
+	return newHandlerEngineWithOptions(t, append(options, scriptorium.WithLLMClient(handlerLLMClient{}))...)
+}
+
+func newHandlerEngineWithDefaultClient(t *testing.T, options ...scriptorium.Option) *scriptorium.Engine {
+	t.Helper()
+
+	return newHandlerEngineWithOptions(t, options...)
+}
+
+func newHandlerEngineWithOptions(t *testing.T, options ...scriptorium.Option) *scriptorium.Engine {
+	t.Helper()
+
+	promptDir := t.TempDir()
+	profileDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(`id: p
+version: "1"
+default_profile: exec
+messages:
+  - role: user
+    content: "hi"
+output:
+  format: text
+  validation_mode: none
+  repair_attempts: 0
+`), 0o644); err != nil {
+		t.Fatalf("write prompt fixture: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`id: exec
+endpoint: http://example.invalid/v1
+model: model
+`), 0o644); err != nil {
+		t.Fatalf("write profile fixture: %v", err)
+	}
+
+	engine, err := scriptorium.NewEngine(scriptorium.Config{
+		PromptDir:  promptDir,
+		ProfileDir: profileDir,
+	}, options...)
+	if err != nil {
+		t.Fatalf("construct public engine: %v", err)
+	}
+	return engine
+}
+
+func assertHTTPErrorCode(t *testing.T, w *httptest.ResponseRecorder, status int, code string) {
+	t.Helper()
+
+	if w.Code != status {
+		t.Fatalf("expected %d, got %d body=%s", status, w.Code, w.Body.String())
+	}
+	var resp map[string]any
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("invalid JSON response: %v", err)
+	}
+	errBody := resp["error"].(map[string]any)
+	if errBody["code"] != code {
+		t.Fatalf("expected code %q, got %#v", code, errBody["code"])
+	}
+}

internal/artifact/reader.go

@@ -5,11 +5,13 @@ import (
 	"crypto/sha256"
 	"errors"
 	"fmt"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+	"io"
 	"mime"
 	"os"
 	"path/filepath"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
 )
 
 var (
@@ -26,7 +28,7 @@ type Reader interface {
 // CompositeReader routes artifact resolution based on the reference type.
 type CompositeReader struct {
 	inlineReader *inlineReader
-	fileReader   *fileReader
+	fileReader   Reader
 }
 
 func NewCompositeReader() Reader {
@@ -89,21 +91,31 @@ func (r *fileReader) Read(ctx context.Context, ref domain.ArtifactRef) (*domain.
 		return nil, ErrMissingFilePath
 	}
 
-	data, err := os.ReadFile(ref.URI)
+	return readFileArtifact(ref.URI)
+}
+
+func readFileArtifact(path string) (*domain.Artifact, error) {
+	file, err := os.Open(path)
 	if err != nil {
-		return nil, fmt.Errorf("failed to read file %s: %w", ref.URI, err)
+		return nil, fmt.Errorf("failed to read file %s: %w", path, err)
+	}
+	defer file.Close()
+
+	data, err := io.ReadAll(file)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read file %s: %w", path, err)
 	}
 
-	contentType := mime.TypeByExtension(filepath.Ext(ref.URI))
+	contentType := mime.TypeByExtension(filepath.Ext(path))
 	if contentType == "" {
 		contentType = defaults.ContentTypeTextPlain
 	}
 
 	return &domain.Artifact{
-		Name:        filepath.Base(ref.URI),
+		Name:        filepath.Base(path),
 		ContentType: contentType,
 		Body:        data,
-		URI:         ref.URI,
+		URI:         path,
 		Size:        int64(len(data)),
 		Hash:        fmt.Sprintf("%x", sha256.Sum256(data)),
 	}, nil

internal/config/config.go

@@ -40,7 +40,11 @@ type Config struct {
 }
 
 type ServerConfig struct {
-	Addr string `yaml:"addr"`
+	Addr             string `yaml:"addr"`
+	ArtifactRoot     string `yaml:"artifact_root"`
+	MaxRequestBytes  *int64 `yaml:"max_request_bytes"`
+	MaxArtifactBytes *int64 `yaml:"max_artifact_bytes"`
+	MaxResponseBytes *int64 `yaml:"max_response_bytes"`
 }
 
 type DefaultsConfig struct {
@@ -53,16 +57,24 @@ type AppSettings struct {
 	ProfileDir          string
 	SchemaDir           string
 	ServerAddr          string
+	ArtifactRoot        string
+	MaxRequestBytes     int64
+	MaxArtifactBytes    int64
+	MaxResponseBytes    int64
 	DefaultRenderFormat renderformat.PreparedRunOutputFormat
 }
 
 // CLIOverrides can be applied after config load to enforce precedence.
 type CLIOverrides struct {
-	PromptDir    string
-	ProfileDir   string
-	SchemaDir    string
-	ServerAddr   string
-	RenderFormat string
+	PromptDir        string
+	ProfileDir       string
+	SchemaDir        string
+	ServerAddr       string
+	ArtifactRoot     string
+	MaxRequestBytes  *int64
+	MaxArtifactBytes *int64
+	MaxResponseBytes *int64
+	RenderFormat     string
 }
 
 // BuiltInDefaults returns compile-time application defaults.
@@ -70,6 +82,9 @@ func BuiltInDefaults() AppSettings {
 	return AppSettings{
 		SchemaDir:           defaults.SchemaDirDefault,
 		ServerAddr:          defaults.HTTPAddrDefault,
+		MaxRequestBytes:     defaults.HTTPMaxRequestBytesDefault,
+		MaxArtifactBytes:    defaults.HTTPMaxArtifactBytesDefault,
+		MaxResponseBytes:    defaults.HTTPMaxResponseBytesDefault,
 		DefaultRenderFormat: renderformat.DefaultPreparedRunOutputFormat,
 	}
 }
@@ -142,6 +157,27 @@ func ApplyCLIOverrides(base AppSettings, overrides CLIOverrides) (AppSettings, e
 	if v := strings.TrimSpace(overrides.ServerAddr); v != "" {
 		out.ServerAddr = v
 	}
+	if v := strings.TrimSpace(overrides.ArtifactRoot); v != "" {
+		out.ArtifactRoot = filepath.Clean(v)
+	}
+	if overrides.MaxRequestBytes != nil {
+		if *overrides.MaxRequestBytes < 0 {
+			return AppSettings{}, fmt.Errorf("%w: server.max_request_bytes must be greater than or equal to 0", ErrInvalidConfig)
+		}
+		out.MaxRequestBytes = *overrides.MaxRequestBytes
+	}
+	if overrides.MaxArtifactBytes != nil {
+		if *overrides.MaxArtifactBytes < 0 {
+			return AppSettings{}, fmt.Errorf("%w: server.max_artifact_bytes must be greater than or equal to 0", ErrInvalidConfig)
+		}
+		out.MaxArtifactBytes = *overrides.MaxArtifactBytes
+	}
+	if overrides.MaxResponseBytes != nil {
+		if *overrides.MaxResponseBytes < 0 {
+			return AppSettings{}, fmt.Errorf("%w: server.max_response_bytes must be greater than or equal to 0", ErrInvalidConfig)
+		}
+		out.MaxResponseBytes = *overrides.MaxResponseBytes
+	}
 	if rawFormat := strings.TrimSpace(overrides.RenderFormat); rawFormat != "" {
 		parsed, err := renderformat.ParsePreparedRunOutputFormat(rawFormat)
 		if err != nil {
@@ -181,6 +217,27 @@ func applyConfig(base AppSettings, cfg Config) (AppSettings, error) {
 	if v := strings.TrimSpace(cfg.Server.Addr); v != "" {
 		out.ServerAddr = v
 	}
+	if v := strings.TrimSpace(cfg.Server.ArtifactRoot); v != "" {
+		out.ArtifactRoot = filepath.Clean(v)
+	}
+	if cfg.Server.MaxRequestBytes != nil {
+		if *cfg.Server.MaxRequestBytes < 0 {
+			return AppSettings{}, fmt.Errorf("%w: server.max_request_bytes must be greater than or equal to 0", ErrInvalidConfig)
+		}
+		out.MaxRequestBytes = *cfg.Server.MaxRequestBytes
+	}
+	if cfg.Server.MaxArtifactBytes != nil {
+		if *cfg.Server.MaxArtifactBytes < 0 {
+			return AppSettings{}, fmt.Errorf("%w: server.max_artifact_bytes must be greater than or equal to 0", ErrInvalidConfig)
+		}
+		out.MaxArtifactBytes = *cfg.Server.MaxArtifactBytes
+	}
+	if cfg.Server.MaxResponseBytes != nil {
+		if *cfg.Server.MaxResponseBytes < 0 {
+			return AppSettings{}, fmt.Errorf("%w: server.max_response_bytes must be greater than or equal to 0", ErrInvalidConfig)
+		}
+		out.MaxResponseBytes = *cfg.Server.MaxResponseBytes
+	}
 	if rawFormat := strings.TrimSpace(cfg.Defaults.RenderFormat); rawFormat != "" {
 		parsed, err := renderformat.ParsePreparedRunOutputFormat(rawFormat)
 		if err != nil {

internal/config/config_test.go

@@ -6,6 +6,7 @@ import (
 	"path/filepath"
 	"testing"
 
+	"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
 	renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
 )
 
@@ -24,6 +25,20 @@ func TestLoadConfigMissingImplicitPathUsesBuiltInDefaults(t *testing.T) {
 	}
 }
 
+func TestBuiltInDefaultsIncludeHTTPSizeLimits(t *testing.T) {
+	got := BuiltInDefaults()
+
+	if got.MaxRequestBytes != defaults.HTTPMaxRequestBytesDefault {
+		t.Fatalf("unexpected max request bytes: %d", got.MaxRequestBytes)
+	}
+	if got.MaxArtifactBytes != defaults.HTTPMaxArtifactBytesDefault {
+		t.Fatalf("unexpected max artifact bytes: %d", got.MaxArtifactBytes)
+	}
+	if got.MaxResponseBytes != defaults.HTTPMaxResponseBytesDefault {
+		t.Fatalf("unexpected max response bytes: %d", got.MaxResponseBytes)
+	}
+}
+
 func TestLoadConfigMissingExplicitPathReturnsError(t *testing.T) {
 	tmp := t.TempDir()
 	missing := filepath.Join(tmp, "missing.yml")
@@ -92,6 +107,10 @@ profile_dir: ./profiles
 schema_dir: ./schemas
 server:
   addr: 127.0.0.1:9090
+  artifact_root: ./artifacts
+  max_request_bytes: 1024
+  max_artifact_bytes: 2048
+  max_response_bytes: 4096
 defaults:
   render_format: json
 `)
@@ -113,11 +132,61 @@ defaults:
 	if got.ServerAddr != "127.0.0.1:9090" {
 		t.Fatalf("unexpected server.addr: %q", got.ServerAddr)
 	}
+	if got.ArtifactRoot != filepath.Clean("./artifacts") {
+		t.Fatalf("unexpected server.artifact_root: %q", got.ArtifactRoot)
+	}
+	if got.MaxRequestBytes != 1024 {
+		t.Fatalf("unexpected server.max_request_bytes: %d", got.MaxRequestBytes)
+	}
+	if got.MaxArtifactBytes != 2048 {
+		t.Fatalf("unexpected server.max_artifact_bytes: %d", got.MaxArtifactBytes)
+	}
+	if got.MaxResponseBytes != 4096 {
+		t.Fatalf("unexpected server.max_response_bytes: %d", got.MaxResponseBytes)
+	}
 	if got.DefaultRenderFormat != renderformat.PreparedRunFormatJSON {
 		t.Fatalf("unexpected defaults.render_format: %q", got.DefaultRenderFormat)
 	}
 }
 
+func TestLoadConfigAcceptsZeroHTTPSizeLimits(t *testing.T) {
+	path := writeConfigFile(t, "config.yml", `
+server:
+  max_request_bytes: 0
+  max_artifact_bytes: 0
+  max_response_bytes: 0
+`)
+
+	got, err := LoadConfig(path, true)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if got.MaxRequestBytes != 0 || got.MaxArtifactBytes != 0 || got.MaxResponseBytes != 0 {
+		t.Fatalf("expected zero limits to be preserved, got request=%d artifact=%d response=%d", got.MaxRequestBytes, got.MaxArtifactBytes, got.MaxResponseBytes)
+	}
+}
+
+func TestLoadConfigRejectsNegativeHTTPSizeLimits(t *testing.T) {
+	tests := []struct {
+		name string
+		body string
+	}{
+		{name: "request", body: "server:\n  max_request_bytes: -1\n"},
+		{name: "artifact", body: "server:\n  max_artifact_bytes: -1\n"},
+		{name: "response", body: "server:\n  max_response_bytes: -1\n"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			path := writeConfigFile(t, "config.yml", tc.body)
+			_, err := LoadConfig(path, true)
+			if !errors.Is(err, ErrInvalidConfig) {
+				t.Fatalf("expected ErrInvalidConfig, got %v", err)
+			}
+		})
+	}
+}
+
 func TestLoadConfigEmptyFileResolvesToBuiltInDefaults(t *testing.T) {
 	path := writeConfigFile(t, "config.yml", "")
 
@@ -185,15 +254,26 @@ func TestApplyCLIOverridesAppliesPrecedence(t *testing.T) {
 		ProfileDir:          "/from/config/profiles",
 		SchemaDir:           "/from/config/schemas",
 		ServerAddr:          ":1234",
+		ArtifactRoot:        "/from/config/artifacts",
+		MaxRequestBytes:     111,
+		MaxArtifactBytes:    222,
+		MaxResponseBytes:    333,
 		DefaultRenderFormat: renderformat.PreparedRunFormatJSON,
 	}
+	maxRequestBytes := int64(0)
+	maxArtifactBytes := int64(444)
+	maxResponseBytes := int64(555)
 
 	got, err := ApplyCLIOverrides(base, CLIOverrides{
-		PromptDir:    "./prompts-cli",
-		ProfileDir:   "./profiles-cli",
-		SchemaDir:    "./schemas-cli",
-		ServerAddr:   ":8081",
-		RenderFormat: "text",
+		PromptDir:        "./prompts-cli",
+		ProfileDir:       "./profiles-cli",
+		SchemaDir:        "./schemas-cli",
+		ServerAddr:       ":8081",
+		ArtifactRoot:     "./artifacts-cli",
+		MaxRequestBytes:  &maxRequestBytes,
+		MaxArtifactBytes: &maxArtifactBytes,
+		MaxResponseBytes: &maxResponseBytes,
+		RenderFormat:     "text",
 	})
 	if err != nil {
 		t.Fatalf("expected no error, got %v", err)
@@ -211,11 +291,45 @@ func TestApplyCLIOverridesAppliesPrecedence(t *testing.T) {
 	if got.ServerAddr != ":8081" {
 		t.Fatalf("unexpected server addr: %q", got.ServerAddr)
 	}
+	if got.ArtifactRoot != filepath.Clean("./artifacts-cli") {
+		t.Fatalf("unexpected artifact root: %q", got.ArtifactRoot)
+	}
+	if got.MaxRequestBytes != 0 {
+		t.Fatalf("unexpected max request bytes: %d", got.MaxRequestBytes)
+	}
+	if got.MaxArtifactBytes != 444 {
+		t.Fatalf("unexpected max artifact bytes: %d", got.MaxArtifactBytes)
+	}
+	if got.MaxResponseBytes != 555 {
+		t.Fatalf("unexpected max response bytes: %d", got.MaxResponseBytes)
+	}
 	if got.DefaultRenderFormat != renderformat.PreparedRunFormatText {
 		t.Fatalf("unexpected render format: %q", got.DefaultRenderFormat)
 	}
 }
 
+func TestApplyCLIOverridesRejectsNegativeHTTPSizeLimits(t *testing.T) {
+	negative := int64(-1)
+
+	tests := []struct {
+		name      string
+		overrides CLIOverrides
+	}{
+		{name: "request", overrides: CLIOverrides{MaxRequestBytes: &negative}},
+		{name: "artifact", overrides: CLIOverrides{MaxArtifactBytes: &negative}},
+		{name: "response", overrides: CLIOverrides{MaxResponseBytes: &negative}},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := ApplyCLIOverrides(BuiltInDefaults(), tc.overrides)
+			if !errors.Is(err, ErrInvalidConfig) {
+				t.Fatalf("expected ErrInvalidConfig, got %v", err)
+			}
+		})
+	}
+}
+
 func TestApplyCLIOverridesInvalidRenderFormatReturnsError(t *testing.T) {
 	_, err := ApplyCLIOverrides(BuiltInDefaults(), CLIOverrides{RenderFormat: "yaml"})
 	if err == nil {

internal/defaults/defaults.go

@@ -7,13 +7,16 @@ import (
 )
 
 const (
-	HTTPAddrDefault            = ":8080"
-	SchemaDirDefault           = "."
-	OutputArtifactName         = "output"
-	ContentTypeTextPlain       = "text/plain"
-	ContentTypeTextMarkdown    = "text/markdown"
-	ContentTypeApplicationJSON = "application/json"
-	OpenAIChatCompletionsPath  = "/chat/completions"
+	HTTPAddrDefault             = ":8080"
+	SchemaDirDefault            = "."
+	OutputArtifactName          = "output"
+	ContentTypeTextPlain        = "text/plain"
+	ContentTypeTextMarkdown     = "text/markdown"
+	ContentTypeApplicationJSON  = "application/json"
+	OpenAIChatCompletionsPath   = "/chat/completions"
+	HTTPMaxRequestBytesDefault  = 16 * 1024 * 1024
+	HTTPMaxArtifactBytesDefault = 16 * 1024 * 1024
+	HTTPMaxResponseBytesDefault = 16 * 1024 * 1024
 
 	ExecutionDefaultTemperature    = 0.0
 	ExecutionDefaultMaxTokens      = 0

internal/domain/domain.go

@@ -63,6 +63,7 @@ type RunRequest struct {
 	PromptID      string
 	PromptVersion string
 	ProfileID     string
+	APIKey        string `json:"-" yaml:"-"`
 	Inputs        map[string]ArtifactRef
 	Vars          map[string]string
 	Execution     *ExecutionTargetOverride
@@ -89,7 +90,6 @@ type RunResult struct {
 	StartTime            time.Time
 	EndTime              time.Time
 	Duration             time.Duration
-	Error                error
 }
 
 // PreparedRun contains pre-LLM execution state from the prepare/render phase.
@@ -170,6 +170,7 @@ type ExecutionProfile struct {
 	ServiceTier     string         `yaml:"service_tier"`
 	ReasoningEffort string         `yaml:"reasoning_effort"`
 	APIKeyEnv       string         `yaml:"api_key_env"`
+	APIKeyRequired  bool           `yaml:"-" json:"-"`
 	ExtraParams     map[string]any `yaml:"extra_params"`
 }
 
@@ -207,6 +208,8 @@ type ExecutionTarget struct {
 	ServiceTier     string         `yaml:"service_tier" json:"service_tier"`
 	ReasoningEffort string         `yaml:"reasoning_effort" json:"reasoning_effort"`
 	APIKeyEnv       string         `yaml:"api_key_env" json:"api_key_env"`
+	APIKey          string         `yaml:"-" json:"-"`
+	APIKeyRequired  bool           `yaml:"-" json:"-"`
 	ExtraParams     map[string]any `yaml:"extra_params" json:"extra_params"`
 }
 
@@ -283,23 +286,3 @@ type ValidationResult struct {
 	RepairAttempts int
 	IsValid        bool
 }
-
-// RunMetadata contains auditing information for a run.
-type RunMetadata struct {
-	RunID              string
-	PromptID           string
-	PromptVersion      string
-	PromptHash         string
-	RenderedPromptHash string
-	SelectedProfileID  string
-	InputHashes        map[string]string
-	ModelEndpoint      string
-	ModelName          string
-	Params             ExecutionTarget
-	Timestamp          time.Time
-	Duration           time.Duration
-	Usage              TokenUsage
-	ValidationMode     ValidationMode
-	ValidationStatus   ValidationStatus
-	RepairAttempts     int
-}

internal/domain/prepared_run_test.go

@@ -20,6 +20,7 @@ func TestPreparedRunJSONDoesNotIncludeSecretValues(t *testing.T) {
 			Endpoint:  "http://llm/v1",
 			Model:     "gpt-test",
 			APIKeyEnv: envName,
+			APIKey:    secret,
 		},
 		InputHashes:        map[string]string{"transcript": "hash-1"},
 		RenderedPromptHash: "rendered-hash",

internal/filecatalog/catalog.go

@@ -2,7 +2,10 @@ package filecatalog
 
 import (
 	"context"
+	"fmt"
+	"io/fs"
 	"os"
+	"path"
 	"path/filepath"
 	"sort"
 	"strings"
@@ -23,7 +26,7 @@ func FindYAMLFiles(ctx context.Context, root string) ([]string, error) {
 		if d.IsDir() {
 			return nil
 		}
-		if !isYAMLFile(d.Name()) {
+		if !IsYAMLFile(d.Name()) {
 			return nil
 		}
 		files = append(files, path)
@@ -33,15 +36,100 @@ func FindYAMLFiles(ctx context.Context, root string) ([]string, error) {
 	return files, err
 }
 
+// FindFSYAMLFiles returns sorted paths for .yaml and .yml files under root in fsys.
+func FindFSYAMLFiles(ctx context.Context, fsys fs.FS, root string) ([]string, error) {
+	cleanRoot := CleanFSRoot(root)
+	var files []string
+	err := fs.WalkDir(fsys, cleanRoot, func(name string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		default:
+		}
+		if d.IsDir() {
+			return nil
+		}
+		if !IsYAMLFile(d.Name()) {
+			return nil
+		}
+		files = append(files, name)
+		return nil
+	})
+	sort.Strings(files)
+	return files, err
+}
+
 // RelativePath computes a clean relative path from root to path.
-func RelativePath(root string, path string) string {
-	rel, err := filepath.Rel(root, path)
+func RelativePath(root string, filePath string) string {
+	rel, err := filepath.Rel(root, filePath)
 	if err != nil {
-		return filepath.Clean(path)
+		return filepath.Clean(filePath)
 	}
 	return filepath.Clean(rel)
 }
 
+// CleanFSRoot normalizes a root path for use with fs.FS.
+func CleanFSRoot(root string) string {
+	root = strings.TrimSpace(root)
+	if root == "" || root == "." {
+		return "."
+	}
+	return path.Clean(root)
+}
+
+// DisplayPath returns name relative to root for messages about fs.FS paths.
+func DisplayPath(root string, name string) string {
+	cleanRoot := CleanFSRoot(root)
+	cleanName := path.Clean(name)
+	if cleanRoot == "." {
+		return cleanName
+	}
+	prefix := strings.TrimSuffix(cleanRoot, "/") + "/"
+	if strings.HasPrefix(cleanName, prefix) {
+		return strings.TrimPrefix(cleanName, prefix)
+	}
+	return cleanName
+}
+
+// ResolveFSPath resolves userPath from baseDir and keeps it inside root.
+func ResolveFSPath(root string, baseDir string, userPath string) (string, string, error) {
+	cleanRoot := CleanFSRoot(root)
+	cleanBase := path.Clean(strings.TrimSpace(baseDir))
+	if cleanBase == "" {
+		cleanBase = cleanRoot
+	}
+	if !containsFSPath(cleanRoot, cleanBase) {
+		return "", "", fmt.Errorf("base path %q is outside source root %q", cleanBase, cleanRoot)
+	}
+
+	cleanUserPath := strings.TrimSpace(userPath)
+	if cleanUserPath == "" {
+		return "", "", fmt.Errorf("path is required")
+	}
+	cleanUserPath = path.Clean(cleanUserPath)
+	if path.IsAbs(cleanUserPath) {
+		return "", "", fmt.Errorf("path %q must be relative", userPath)
+	}
+
+	resolved := path.Clean(path.Join(cleanBase, cleanUserPath))
+	if !containsFSPath(cleanRoot, resolved) {
+		return "", "", fmt.Errorf("path %q escapes source root %q", userPath, cleanRoot)
+	}
+	return resolved, DisplayPath(cleanRoot, resolved), nil
+}
+
+func containsFSPath(root string, name string) bool {
+	root = CleanFSRoot(root)
+	name = path.Clean(name)
+	if root == "." {
+		return name == "." || (name != ".." && !strings.HasPrefix(name, "../"))
+	}
+	return name == root || strings.HasPrefix(name, strings.TrimSuffix(root, "/")+"/")
+}
+
 // Stem strips .yaml or .yml from a file name.
 func Stem(name string) string {
 	name = strings.TrimSuffix(name, ".yaml")
@@ -49,6 +137,6 @@ func Stem(name string) string {
 	return name
 }
 
-func isYAMLFile(name string) bool {
+func IsYAMLFile(name string) bool {
 	return strings.HasSuffix(name, ".yaml") || strings.HasSuffix(name, ".yml")
 }

internal/filecatalog/catalog_test.go

@@ -6,7 +6,9 @@ import (
 	"os"
 	"path/filepath"
 	"reflect"
+	"strings"
 	"testing"
+	"testing/fstest"
 )
 
 func TestFindYAMLFilesNestedSortedAndFiltered(t *testing.T) {
@@ -43,6 +45,42 @@ func TestFindYAMLFilesHonorsContextCancellation(t *testing.T) {
 	}
 }
 
+func TestFindFSYAMLFilesNestedSortedAndFiltered(t *testing.T) {
+	fsys := fstest.MapFS{
+		"prompts/z/prompt.yml":      &fstest.MapFile{Data: []byte("id: z")},
+		"prompts/a/profile.yaml":    &fstest.MapFile{Data: []byte("id: a")},
+		"prompts/a/ignore.txt":      &fstest.MapFile{Data: []byte("not yaml")},
+		"prompts/b/ignore.yaml.bak": &fstest.MapFile{Data: []byte("not yaml")},
+		"other/ignored.yaml":        &fstest.MapFile{Data: []byte("id: ignored")},
+	}
+
+	got, err := FindFSYAMLFiles(context.Background(), fsys, " prompts ")
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+
+	want := []string{
+		"prompts/a/profile.yaml",
+		"prompts/z/prompt.yml",
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("expected sorted YAML files %v, got %v", want, got)
+	}
+}
+
+func TestFindFSYAMLFilesHonorsContextCancellation(t *testing.T) {
+	fsys := fstest.MapFS{
+		"one.yaml": &fstest.MapFile{Data: []byte("id: one")},
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := FindFSYAMLFiles(ctx, fsys, ".")
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("expected context.Canceled, got %v", err)
+	}
+}
+
 func TestRelativePathNested(t *testing.T) {
 	root := t.TempDir()
 	path := filepath.Join(root, "nested", "profiles", "local.yaml")
@@ -53,6 +91,133 @@ func TestRelativePathNested(t *testing.T) {
 	}
 }
 
+func TestCleanFSRoot(t *testing.T) {
+	tests := []struct {
+		name string
+		root string
+		want string
+	}{
+		{name: "empty", root: "", want: "."},
+		{name: "dot", root: ".", want: "."},
+		{name: "trimmed", root: " prompts/../profiles ", want: "profiles"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := CleanFSRoot(tc.root); got != tc.want {
+				t.Fatalf("expected %q, got %q", tc.want, got)
+			}
+		})
+	}
+}
+
+func TestDisplayPath(t *testing.T) {
+	tests := []struct {
+		name string
+		root string
+		path string
+		want string
+	}{
+		{name: "root dot", root: ".", path: "profiles/local.yaml", want: "profiles/local.yaml"},
+		{name: "nested root", root: "profiles", path: "profiles/local.yaml", want: "local.yaml"},
+		{name: "outside root", root: "profiles", path: "other/local.yaml", want: "other/local.yaml"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := DisplayPath(tc.root, tc.path); got != tc.want {
+				t.Fatalf("expected %q, got %q", tc.want, got)
+			}
+		})
+	}
+}
+
+func TestResolveFSPath(t *testing.T) {
+	tests := []struct {
+		name        string
+		root        string
+		baseDir     string
+		userPath    string
+		wantPath    string
+		wantDisplay string
+		wantErr     string
+	}{
+		{
+			name:        "sibling inside root",
+			root:        "prompts",
+			baseDir:     "prompts/nested",
+			userPath:    "./messages/user.tmpl",
+			wantPath:    "prompts/nested/messages/user.tmpl",
+			wantDisplay: "nested/messages/user.tmpl",
+		},
+		{
+			name:        "parent inside root",
+			root:        "prompts",
+			baseDir:     "prompts/nested",
+			userPath:    "../shared/user.tmpl",
+			wantPath:    "prompts/shared/user.tmpl",
+			wantDisplay: "shared/user.tmpl",
+		},
+		{
+			name:     "escape rejected",
+			root:     "prompts",
+			baseDir:  "prompts/nested",
+			userPath: "../../outside.tmpl",
+			wantErr:  "escapes source root",
+		},
+		{
+			name:     "absolute path rejected",
+			root:     "prompts",
+			baseDir:  "prompts/nested",
+			userPath: "/outside.tmpl",
+			wantErr:  "must be relative",
+		},
+		{
+			name:     "empty path rejected",
+			root:     "prompts",
+			baseDir:  "prompts/nested",
+			userPath: " ",
+			wantErr:  "path is required",
+		},
+		{
+			name:        "dot root allows normal relative path",
+			root:        ".",
+			baseDir:     ".",
+			userPath:    "schemas/events.schema.json",
+			wantPath:    "schemas/events.schema.json",
+			wantDisplay: "schemas/events.schema.json",
+		},
+		{
+			name:     "dot root rejects parent escape",
+			root:     ".",
+			baseDir:  ".",
+			userPath: "../outside.tmpl",
+			wantErr:  "escapes source root",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			gotPath, gotDisplay, err := ResolveFSPath(tc.root, tc.baseDir, tc.userPath)
+			if tc.wantErr != "" {
+				if err == nil {
+					t.Fatalf("expected error containing %q", tc.wantErr)
+				}
+				if !strings.Contains(err.Error(), tc.wantErr) {
+					t.Fatalf("expected error to contain %q, got %v", tc.wantErr, err)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("expected no error, got %v", err)
+			}
+			if gotPath != tc.wantPath || gotDisplay != tc.wantDisplay {
+				t.Fatalf("expected path/display %q/%q, got %q/%q", tc.wantPath, tc.wantDisplay, gotPath, gotDisplay)
+			}
+		})
+	}
+}
+
 func TestStemStripsYAMLExtensions(t *testing.T) {
 	tests := []struct {
 		name string
@@ -73,6 +238,27 @@ func TestStemStripsYAMLExtensions(t *testing.T) {
 	}
 }
 
+func TestIsYAMLFile(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want bool
+	}{
+		{name: "yaml", in: "prompt.yaml", want: true},
+		{name: "yml", in: "profile.yml", want: true},
+		{name: "backup", in: "profile.yaml.bak", want: false},
+		{name: "uppercase", in: "profile.YAML", want: false},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := IsYAMLFile(tc.in); got != tc.want {
+				t.Fatalf("expected %v, got %v", tc.want, got)
+			}
+		})
+	}
+}
+
 func mustWriteFile(t *testing.T, path string, content string) {
 	t.Helper()
 	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {

internal/format/prepared_run.go

@@ -1,4 +1,4 @@
-// Package format formats already-prepared domain data for adapters.
+// Package format formats already-prepared public data for adapters.
 package format
 
 import (
@@ -9,7 +9,7 @@ import (
 	"sort"
 	"strings"
 
-	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+	"gitea.maximumdirect.net/eric/scriptorium"
 )
 
 var ErrUnknownPreparedRunFormat = errors.New("unknown prepared run format")
@@ -26,7 +26,7 @@ const (
 
 // PreparedRunFormatter serializes a prepared run without performing use case work.
 type PreparedRunFormatter interface {
-	Format(prepared *domain.PreparedRun) ([]byte, error)
+	Format(prepared *scriptorium.PreparedRun) ([]byte, error)
 }
 
 // ParsePreparedRunOutputFormat parses a format name.
@@ -56,7 +56,7 @@ func FormatterForPreparedRun(outputFormat PreparedRunOutputFormat) (PreparedRunF
 }
 
 // FormatPreparedRun formats a prepared run using the selected format.
-func FormatPreparedRun(prepared *domain.PreparedRun, outputFormat PreparedRunOutputFormat) ([]byte, error) {
+func FormatPreparedRun(prepared *scriptorium.PreparedRun, outputFormat PreparedRunOutputFormat) ([]byte, error) {
 	formatter, err := FormatterForPreparedRun(outputFormat)
 	if err != nil {
 		return nil, err
@@ -65,7 +65,7 @@ func FormatPreparedRun(prepared *domain.PreparedRun, outputFormat PreparedRunOut
 }
 
 // FormatPreparedRunByName parses a format name and formats a prepared run.
-func FormatPreparedRunByName(prepared *domain.PreparedRun, rawFormat string) ([]byte, error) {
+func FormatPreparedRunByName(prepared *scriptorium.PreparedRun, rawFormat string) ([]byte, error) {
 	outputFormat, err := ParsePreparedRunOutputFormat(rawFormat)
 	if err != nil {
 		return nil, err
@@ -75,7 +75,7 @@ func FormatPreparedRunByName(prepared *domain.PreparedRun, rawFormat string) ([]
 
 type jsonPreparedRunFormatter struct{}
 
-func (jsonPreparedRunFormatter) Format(prepared *domain.PreparedRun) ([]byte, error) {
+func (jsonPreparedRunFormatter) Format(prepared *scriptorium.PreparedRun) ([]byte, error) {
 	if prepared == nil {
 		return nil, errors.New("prepared run is nil")
 	}
@@ -84,7 +84,7 @@ func (jsonPreparedRunFormatter) Format(prepared *domain.PreparedRun) ([]byte, er
 
 type textPreparedRunFormatter struct{}
 
-func (textPreparedRunFormatter) Format(prepared *domain.PreparedRun) ([]byte, error) {
+func (textPreparedRunFormatter) Format(prepared *scriptorium.PreparedRun) ([]byte, error) {
 	if prepared == nil {
 		return nil, errors.New("prepared run is nil")
 	}
@@ -146,7 +146,7 @@ func (textPreparedRunFormatter) Format(prepared *domain.PreparedRun) ([]byte, er
 
 	fmt.Fprintln(&b, "messages:")
 	roleOrder := make([]string, 0)
-	byRole := make(map[string][]domain.RenderedMessage)
+	byRole := make(map[string][]scriptorium.RenderedMessage)
 	for _, msg := range prepared.Messages {
 		if _, exists := byRole[msg.Role]; !exists {
 			roleOrder = append(roleOrder, msg.Role)

internal/format/prepared_run_test.go

@@ -6,7 +6,7 @@ import (
 	"strings"
 	"testing"
 
-	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+	"gitea.maximumdirect.net/eric/scriptorium"
 )
 
 func TestTextFormatterIncludesPreparedRunDetails(t *testing.T) {
@@ -92,14 +92,27 @@ func TestTextFormatterDoesNotIncludeResolvedAPIKeyValue(t *testing.T) {
 	}
 }
 
+func TestTextFormatterDoesNotIncludeDirectAPIKeyValue(t *testing.T) {
+	const directKey = "direct-format-key"
+	// PreparedRun intentionally has no field for direct API keys.
+	prepared := samplePreparedRun()
+	out, err := FormatPreparedRun(prepared, PreparedRunFormatText)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if strings.Contains(string(out), directKey) {
+		t.Fatalf("text output should not include direct api key value: %s", out)
+	}
+}
+
 func TestTextFormatterIncludesMessageCacheControlBeforeContent(t *testing.T) {
 	prepared := samplePreparedRun()
-	prepared.Messages = []domain.RenderedMessage{
+	prepared.Messages = []scriptorium.RenderedMessage{
 		{
 			Role:    "system",
 			Content: "System guidance.",
-			CacheControl: &domain.CacheControl{
-				Type: domain.CacheControlEphemeral,
+			CacheControl: &scriptorium.CacheControl{
+				Type: scriptorium.CacheControlEphemeral,
 				TTL:  "1h",
 			},
 		},
@@ -134,12 +147,12 @@ func TestTextFormatterIncludesSessionIDWhenPresent(t *testing.T) {
 
 func TestTextFormatterOmitsEmptyCacheControlTTL(t *testing.T) {
 	prepared := samplePreparedRun()
-	prepared.Messages = []domain.RenderedMessage{
+	prepared.Messages = []scriptorium.RenderedMessage{
 		{
 			Role:    "system",
 			Content: "System guidance.",
-			CacheControl: &domain.CacheControl{
-				Type: domain.CacheControlEphemeral,
+			CacheControl: &scriptorium.CacheControl{
+				Type: scriptorium.CacheControlEphemeral,
 			},
 		},
 	}
@@ -217,12 +230,12 @@ func TestJSONFormatterEmitsValidJSONAndIncludesPreparedRunFields(t *testing.T) {
 
 func TestJSONFormatterIncludesMessageCacheControlOnlyWhenPresent(t *testing.T) {
 	prepared := samplePreparedRun()
-	prepared.Messages = []domain.RenderedMessage{
+	prepared.Messages = []scriptorium.RenderedMessage{
 		{
 			Role:    "system",
 			Content: "System guidance.",
-			CacheControl: &domain.CacheControl{
-				Type: domain.CacheControlEphemeral,
+			CacheControl: &scriptorium.CacheControl{
+				Type: scriptorium.CacheControlEphemeral,
 				TTL:  "1h",
 			},
 		},
@@ -248,7 +261,7 @@ func TestJSONFormatterIncludesMessageCacheControlOnlyWhenPresent(t *testing.T) {
 	if !ok {
 		t.Fatalf("expected first message cache_control, got %#v", decoded.Messages[0])
 	}
-	if cacheControl["type"] != string(domain.CacheControlEphemeral) || cacheControl["ttl"] != "1h" {
+	if cacheControl["type"] != string(scriptorium.CacheControlEphemeral) || cacheControl["ttl"] != "1h" {
 		t.Fatalf("unexpected cache_control payload: %#v", cacheControl)
 	}
 	if _, ok := decoded.Messages[1]["cache_control"]; ok {
@@ -269,6 +282,19 @@ func TestJSONFormatterDoesNotIncludeResolvedAPIKeyValue(t *testing.T) {
 	}
 }
 
+func TestJSONFormatterDoesNotIncludeDirectAPIKeyValue(t *testing.T) {
+	const directKey = "direct-format-key"
+	// PreparedRun intentionally has no field for direct API keys.
+	prepared := samplePreparedRun()
+	out, err := FormatPreparedRun(prepared, PreparedRunFormatJSON)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if strings.Contains(string(out), directKey) {
+		t.Fatalf("json output should not include direct api key value: %s", out)
+	}
+}
+
 func TestParsePreparedRunOutputFormatRecognizesSupportedNames(t *testing.T) {
 	tests := []struct {
 		name  string
@@ -314,13 +340,13 @@ func TestFormatPreparedRunByNameUnknownFailsClearly(t *testing.T) {
 	}
 }
 
-func samplePreparedRun() *domain.PreparedRun {
-	return &domain.PreparedRun{
+func samplePreparedRun() *scriptorium.PreparedRun {
+	return &scriptorium.PreparedRun{
 		PromptID:          "prompt.id",
 		PromptVersion:     "v1",
 		PromptHash:        "prompt-hash",
 		SelectedProfileID: "local-fast",
-		EffectiveModelParams: domain.ExecutionTarget{
+		EffectiveModelParams: scriptorium.ExecutionTarget{
 			Endpoint:        "http://llm/v1",
 			Model:           "gpt-test",
 			Temperature:     0.4,
@@ -336,7 +362,7 @@ func samplePreparedRun() *domain.PreparedRun {
 			"glossary":   "hash-glossary",
 		},
 		RenderedPromptHash: "rendered-hash",
-		Messages: []domain.RenderedMessage{
+		Messages: []scriptorium.RenderedMessage{
 			{Role: "system", Content: "System guidance."},
 			{Role: "user", Content: "Summarize the transcript.\nInclude key entities."},
 			{Role: "user", Content: "Second user message."},

internal/llm/openai_compatible_client.go

@@ -36,7 +36,6 @@ type OpenAICompatibleConfig struct {
 type OpenAICompatibleClient struct {
 	baseURL      string
 	defaultModel string
-	timeout      time.Duration
 	httpClient   *http.Client
 }
 
@@ -55,10 +54,11 @@ func NewOpenAICompatibleClient(cfg OpenAICompatibleConfig) (*OpenAICompatibleCli
 
 	var client *http.Client
 	if cfg.HTTPClient != nil {
-		client = cfg.HTTPClient
-		if client.Timeout == 0 {
-			client.Timeout = timeout
+		cloned := *cfg.HTTPClient
+		if cloned.Timeout <= 0 {
+			cloned.Timeout = timeout
 		}
+		client = &cloned
 	} else {
 		client = &http.Client{Timeout: timeout}
 	}
@@ -66,7 +66,6 @@ func NewOpenAICompatibleClient(cfg OpenAICompatibleConfig) (*OpenAICompatibleCli
 	return &OpenAICompatibleClient{
 		baseURL:      strings.TrimRight(baseURL, "/"),
 		defaultModel: cfg.Model,
-		timeout:      timeout,
 		httpClient:   client,
 	}, nil
 }
@@ -100,12 +99,24 @@ func (c *OpenAICompatibleClient) Generate(ctx context.Context, req domain.Genera
 		return nil, fmt.Errorf("%w: failed to encode request: %v", ErrRequestFailed, err)
 	}
 
-	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(payload))
+	requestContext := ctx
+	if req.Target.TimeoutSeconds > 0 {
+		var cancel context.CancelFunc
+		requestContext, cancel = context.WithTimeout(
+			ctx,
+			time.Duration(req.Target.TimeoutSeconds)*time.Second,
+		)
+		defer cancel()
+	}
+
+	httpReq, err := http.NewRequestWithContext(requestContext, http.MethodPost, endpoint, bytes.NewReader(payload))
 	if err != nil {
 		return nil, fmt.Errorf("%w: failed to create request: %v", ErrRequestFailed, err)
 	}
 	httpReq.Header.Set("Content-Type", "application/json")
-	if envName := strings.TrimSpace(req.Target.APIKeyEnv); envName != "" {
+	if apiKey := strings.TrimSpace(req.Target.APIKey); apiKey != "" {
+		httpReq.Header.Set("Authorization", "Bearer "+apiKey)
+	} else if envName := strings.TrimSpace(req.Target.APIKeyEnv); envName != "" {
 		apiKey := strings.TrimSpace(os.Getenv(envName))
 		if apiKey == "" {
 			return nil, fmt.Errorf("%w: api key environment variable %q is not set", ErrInvalidRequest, envName)
@@ -113,20 +124,9 @@ func (c *OpenAICompatibleClient) Generate(ctx context.Context, req domain.Genera
 		httpReq.Header.Set("Authorization", "Bearer "+apiKey)
 	}
 
-	effectiveTimeout := c.timeout
-	if req.Target.TimeoutSeconds > 0 {
-		effectiveTimeout = time.Duration(req.Target.TimeoutSeconds) * time.Second
-	} else if req.TargetPresence.TimeoutSeconds {
-		effectiveTimeout = 0
-	}
-
 	httpClient := c.httpClient
 	if httpClient == nil {
-		httpClient = &http.Client{Timeout: effectiveTimeout}
-	} else if httpClient.Timeout != effectiveTimeout {
-		cloned := *httpClient
-		cloned.Timeout = effectiveTimeout
-		httpClient = &cloned
+		httpClient = &http.Client{Timeout: defaults.LLMRequestTimeoutDefault}
 	}
 
 	httpResp, err := httpClient.Do(httpReq)
@@ -136,8 +136,8 @@ func (c *OpenAICompatibleClient) Generate(ctx context.Context, req domain.Genera
 	defer httpResp.Body.Close()
 
 	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
-		body, _ := io.ReadAll(io.LimitReader(httpResp.Body, 4096))
-		return nil, fmt.Errorf("%w: status=%d body=%q", ErrUnexpectedStatus, httpResp.StatusCode, strings.TrimSpace(string(body)))
+		_, _ = io.Copy(io.Discard, io.LimitReader(httpResp.Body, 4096))
+		return nil, fmt.Errorf("%w: status=%d", ErrUnexpectedStatus, httpResp.StatusCode)
 	}
 
 	var wireResp openAIChatResponse

internal/llm/openai_compatible_client_test.go

@@ -14,6 +14,91 @@ import (
 	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
 )
 
+func TestNewOpenAICompatibleClientDoesNotMutateSuppliedZeroTimeoutClient(t *testing.T) {
+	transport := http.DefaultTransport
+	supplied := &http.Client{Transport: transport}
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{
+		HTTPClient: supplied,
+	})
+	if err != nil {
+		t.Fatalf("unexpected constructor error: %v", err)
+	}
+
+	if supplied.Timeout != 0 {
+		t.Fatalf("expected supplied client timeout to remain zero, got %v", supplied.Timeout)
+	}
+	if client.httpClient == supplied {
+		t.Fatal("expected constructed client to use a cloned HTTP client")
+	}
+	if client.httpClient.Timeout <= 0 {
+		t.Fatalf("expected constructed client to use a positive default timeout, got %v", client.httpClient.Timeout)
+	}
+	if client.httpClient.Transport != transport {
+		t.Fatal("expected cloned client to preserve the supplied transport")
+	}
+}
+
+func TestNewOpenAICompatibleClientDoesNotMutateSuppliedNonzeroTimeoutClient(t *testing.T) {
+	transport := http.DefaultTransport
+	suppliedTimeout := 37 * time.Second
+	supplied := &http.Client{
+		Timeout:   suppliedTimeout,
+		Transport: transport,
+	}
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{
+		Timeout:    2 * time.Second,
+		HTTPClient: supplied,
+	})
+	if err != nil {
+		t.Fatalf("unexpected constructor error: %v", err)
+	}
+
+	if supplied.Timeout != suppliedTimeout {
+		t.Fatalf("expected supplied client timeout to remain %v, got %v", suppliedTimeout, supplied.Timeout)
+	}
+	if client.httpClient == supplied {
+		t.Fatal("expected constructed client to use a cloned HTTP client")
+	}
+	if client.httpClient.Timeout != suppliedTimeout {
+		t.Fatalf("expected cloned client timeout %v, got %v", suppliedTimeout, client.httpClient.Timeout)
+	}
+	if client.httpClient.Transport != transport {
+		t.Fatal("expected cloned client to preserve the supplied transport")
+	}
+}
+
+func TestNewOpenAICompatibleClientTreatsSuppliedNegativeTimeoutAsUnset(t *testing.T) {
+	transport := http.DefaultTransport
+	supplied := &http.Client{
+		Timeout:   -time.Second,
+		Transport: transport,
+	}
+	configuredTimeout := 23 * time.Second
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{
+		Timeout:    configuredTimeout,
+		HTTPClient: supplied,
+	})
+	if err != nil {
+		t.Fatalf("unexpected constructor error: %v", err)
+	}
+
+	if supplied.Timeout != -time.Second {
+		t.Fatalf("expected supplied client timeout to remain negative, got %v", supplied.Timeout)
+	}
+	if client.httpClient == supplied {
+		t.Fatal("expected constructed client to use a cloned HTTP client")
+	}
+	if client.httpClient.Timeout != configuredTimeout {
+		t.Fatalf("expected cloned client timeout %v, got %v", configuredTimeout, client.httpClient.Timeout)
+	}
+	if client.httpClient.Transport != transport {
+		t.Fatal("expected cloned client to preserve the supplied transport")
+	}
+}
+
 func TestOpenAICompatibleClientGenerateSuccess(t *testing.T) {
 	type observedRequest struct {
 		Authorization string
@@ -148,6 +233,38 @@ func TestOpenAICompatibleClientGenerateSuccess(t *testing.T) {
 	}
 }
 
+func TestOpenAICompatibleClientDirectAPIKeyPreferredOverEnv(t *testing.T) {
+	const directKey = "direct-llm-key"
+	t.Setenv("SCRIPTORIUM_TEST_API_KEY", "env-key")
+
+	var gotAuth string
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth = r.Header.Get("Authorization")
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer ts.Close()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{BaseURL: ts.URL + "/v1"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt: domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}},
+		Target: domain.ExecutionTarget{
+			Model:     "model",
+			APIKeyEnv: "SCRIPTORIUM_TEST_API_KEY",
+			APIKey:    directKey,
+		},
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if gotAuth != "Bearer "+directKey {
+		t.Fatalf("unexpected Authorization header: %q", gotAuth)
+	}
+}
+
 func TestOpenAICompatibleClientSerializesCacheControlledMessageAsContentBlock(t *testing.T) {
 	var observedBody map[string]any
 	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -576,31 +693,6 @@ func TestOpenAICompatibleClientOmitsImplicitZeroNumericFields(t *testing.T) {
 	}
 }
 
-func TestOpenAICompatibleClientExplicitZeroTimeoutDisablesClientTimeout(t *testing.T) {
-	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		time.Sleep(20 * time.Millisecond)
-		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
-	}))
-	defer ts.Close()
-
-	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{
-		BaseURL: ts.URL + "/v1",
-		Timeout: time.Nanosecond,
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	_, err = client.Generate(context.Background(), domain.GenerateRequest{
-		Prompt:         domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}},
-		Target:         domain.ExecutionTarget{Model: "model", TimeoutSeconds: 0},
-		TargetPresence: domain.ExecutionTargetPresence{TimeoutSeconds: true},
-	})
-	if err != nil {
-		t.Fatalf("expected explicit zero timeout to disable client timeout, got %v", err)
-	}
-}
-
 func TestOpenAICompatibleClientOmittedTimeoutUsesClientTimeout(t *testing.T) {
 	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		time.Sleep(20 * time.Millisecond)
@@ -813,9 +905,10 @@ func TestOpenAICompatibleClientEndpointOverride(t *testing.T) {
 }
 
 func TestOpenAICompatibleClientNon2xxError(t *testing.T) {
+	const sensitiveBody = `provider-secret-fragment request_payload_details`
 	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusBadRequest)
-		_, _ = w.Write([]byte(`{"error":"bad request payload"}`))
+		_, _ = w.Write([]byte(`{"error":"` + sensitiveBody + `"}`))
 	}))
 	defer ts.Close()
 
@@ -833,8 +926,11 @@ func TestOpenAICompatibleClientNon2xxError(t *testing.T) {
 	if !errors.Is(err, ErrUnexpectedStatus) {
 		t.Fatalf("expected ErrUnexpectedStatus, got %v", err)
 	}
-	if !strings.Contains(err.Error(), "400") || !strings.Contains(err.Error(), "bad request payload") {
-		t.Fatalf("expected status/body details, got %v", err)
+	if !strings.Contains(err.Error(), "status=400") {
+		t.Fatalf("expected status detail, got %v", err)
+	}
+	if strings.Contains(err.Error(), sensitiveBody) {
+		t.Fatalf("expected provider response body to be redacted, got %v", err)
 	}
 }
 
@@ -909,34 +1005,6 @@ func TestOpenAICompatibleClientTimeout(t *testing.T) {
 	}
 }
 
-func TestOpenAICompatibleClientRequestTimeoutOverride(t *testing.T) {
-	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		time.Sleep(100 * time.Millisecond)
-		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
-	}))
-	defer ts.Close()
-
-	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{
-		BaseURL: ts.URL + "/v1",
-		Model:   "m",
-		Timeout: 50 * time.Millisecond,
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	resp, err := client.Generate(context.Background(), domain.GenerateRequest{
-		Prompt: domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}},
-		Target: domain.ExecutionTarget{TimeoutSeconds: 1},
-	})
-	if err != nil {
-		t.Fatalf("expected request-level timeout override to succeed, got %v", err)
-	}
-	if resp.Content != "ok" {
-		t.Fatalf("expected response content ok, got %q", resp.Content)
-	}
-}
-
 func TestOpenAICompatibleClientNegativeTimeoutRejected(t *testing.T) {
 	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{
 		BaseURL: "http://example.com/v1",

internal/profile/builtin/assets/aion-labs/aion-2.yml

@@ -0,0 +1,9 @@
+id: aion-2
+endpoint: https://openrouter.ai/api/v1
+model: aion-labs/aion-2.0
+temperature: 0.72
+reasoning_effort: high
+top_p: 0.95
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/anthropic/claude-fable-latest.yml

@@ -0,0 +1,7 @@
+id: claude-fable-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~anthropic/claude-fable-latest"
+reasoning_effort: high
+timeout_seconds: 600
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/anthropic/claude-haiku-latest.yml

@@ -0,0 +1,7 @@
+id: claude-haiku-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~anthropic/claude-haiku-latest"
+reasoning_effort: medium
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/anthropic/claude-opus-latest.yml

@@ -0,0 +1,7 @@
+id: claude-opus-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~anthropic/claude-opus-latest"
+reasoning_effort: high
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/anthropic/claude-sonnet-latest.yml

@@ -0,0 +1,7 @@
+id: claude-sonnet-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~anthropic/claude-sonnet-latest"
+reasoning_effort: high
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/deepseek/deepseek-3-2.yml

@@ -0,0 +1,7 @@
+id: deepseek-3-2
+endpoint: https://openrouter.ai/api/v1
+model: deepseek/deepseek-v3.2
+reasoning_effort: high
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/deepseek/deepseek-4-flash.yml

@@ -0,0 +1,7 @@
+id: deepseek-4-flash
+endpoint: https://openrouter.ai/api/v1
+model: deepseek/deepseek-v4-flash
+#reasoning_effort: medium
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/deepseek/deepseek-4-pro.yml

@@ -0,0 +1,7 @@
+id: deepseek-4-pro
+endpoint: https://openrouter.ai/api/v1
+model: deepseek/deepseek-v4-pro
+reasoning_effort: high
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/google/gemini-2-flash-lite.yml

@@ -0,0 +1,9 @@
+id: gemini-2-flash-lite
+endpoint: https://openrouter.ai/api/v1
+model: "google/gemini-2.5-flash-lite"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/google/gemini-2-flash.yml

@@ -0,0 +1,9 @@
+id: gemini-2-flash
+endpoint: https://openrouter.ai/api/v1
+model: "google/gemini-2.5-flash"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/google/gemini-2-pro.yml

@@ -0,0 +1,9 @@
+id: gemini-2-pro
+endpoint: https://openrouter.ai/api/v1
+model: "google/gemini-2.5-pro"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/google/gemini-3-flash-lite.yml

@@ -0,0 +1,9 @@
+id: gemini-3-flash-lite
+endpoint: https://openrouter.ai/api/v1
+model: "google/gemini-3.1-flash-lite"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/google/gemini-flash-latest.yml

@@ -0,0 +1,9 @@
+id: gemini-flash-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~google/gemini-flash-latest"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/google/gemini-pro-latest.yml

@@ -0,0 +1,9 @@
+id: gemini-pro-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~google/gemini-pro-latest"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/google/gemma-4-31b.yml

@@ -0,0 +1,9 @@
+id: gemma-4-31b
+endpoint: https://openrouter.ai/api/v1
+model: google/gemma-4-31b-it:exacto
+temperature: 0.15
+reasoning_effort: high
+top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/minimax/minimax-m2.yml

@@ -0,0 +1,9 @@
+id: minimax-m2
+endpoint: https://openrouter.ai/api/v1
+model: minimax/minimax-m2.5
+temperature: 0.5
+reasoning_effort: high
+top_p: 0.95
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/minimax/minimax-m3.yml

@@ -0,0 +1,9 @@
+id: minimax-m3
+endpoint: https://openrouter.ai/api/v1
+model: minimax/minimax-m3
+#temperature: 0.5
+reasoning_effort: high
+#top_p: 0.95
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/mistral/mistral-large-2512.yml

@@ -0,0 +1,7 @@
+id: mistral-large-2512
+endpoint: https://openrouter.ai/api/v1
+model: mistralai/mistral-large-2512
+temperature: 0.15
+top_p: 0.98
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY

internal/profile/builtin/assets/mistral/mistral-medium-3-5.yml

@@ -0,0 +1,8 @@
+id: mistral-medium-3-5
+endpoint: https://openrouter.ai/api/v1
+model: mistralai/mistral-medium-3-5
+temperature: 0.15
+reasoning_effort: high
+top_p: 0.98
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY

internal/profile/builtin/assets/mistral/mistral-small-3.yml

@@ -0,0 +1,7 @@
+id: mistral-small-3
+endpoint: https://openrouter.ai/api/v1
+model: mistralai/mistral-small-3.2-24b-instruct
+temperature: 0.05
+top_p: 1.0
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY

internal/profile/builtin/assets/mistral/mistral-small-4.yml

@@ -0,0 +1,8 @@
+id: mistral-small-4
+endpoint: https://openrouter.ai/api/v1
+model: mistralai/mistral-small-2603
+temperature: 0.1
+reasoning_effort: high
+top_p: 0.98
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY

internal/profile/builtin/assets/nvidia/nemotron-3-ultra.yml

@@ -0,0 +1,7 @@
+id: nemotron-3-ultra
+endpoint: https://openrouter.ai/api/v1
+model: nvidia/nemotron-3-ultra-550b-a55b
+reasoning_effort: high
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/openai/gpt-5-mini.yml

@@ -0,0 +1,7 @@
+id: gpt-5-mini
+endpoint: https://openrouter.ai/api/v1
+model: "openai/gpt-5.4-mini"
+reasoning_effort: high
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/assets/openai/gpt-5-nano.yml

@@ -0,0 +1,7 @@
+id: gpt-5-nano
+endpoint: https://openrouter.ai/api/v1
+model: "openai/gpt-5.4-nano"
+reasoning_effort: high
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

internal/profile/builtin/repository.go

@@ -0,0 +1,31 @@
+package builtin
+
+import (
+	"embed"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
+)
+
+const assetRoot = "assets"
+
+//go:embed assets/**/*.yml
+var assets embed.FS
+
+func NewRepository() profile.Repository {
+	return profile.NewFSRepository(assets, assetRoot)
+}
+
+func NewRepositoryWithPrimary(primary profile.Repository) profile.Repository {
+	if primary == nil {
+		return NewRepository()
+	}
+	return profile.NewOverlayRepository(primary, NewRepository())
+}
+
+func NewRepositoryWithDirectory(dir string) profile.Repository {
+	if strings.TrimSpace(dir) == "" {
+		return NewRepository()
+	}
+	return NewRepositoryWithPrimary(profile.NewFilesystemRepository(dir))
+}

internal/profile/builtin/repository_test.go

@@ -0,0 +1,127 @@
+package builtin
+
+import (
+	"context"
+	"errors"
+	"io/fs"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
+	"gopkg.in/yaml.v3"
+)
+
+func TestBuiltInProfilesValidateThroughRepository(t *testing.T) {
+	repo := NewRepository()
+	ids := loadBuiltInProfileIDs(t)
+	if len(ids) == 0 {
+		t.Fatal("expected built-in profiles")
+	}
+
+	for id := range ids {
+		t.Run(id, func(t *testing.T) {
+			p, err := repo.GetProfile(context.Background(), id)
+			if err != nil {
+				t.Fatalf("expected built-in profile %q to load, got %v", id, err)
+			}
+			if p.ID != id {
+				t.Fatalf("expected profile id %q, got %q", id, p.ID)
+			}
+		})
+	}
+}
+
+func TestBuiltInProfilesDoNotContainDuplicateIDsOrRawAPIKeys(t *testing.T) {
+	loadBuiltInProfileIDs(t)
+}
+
+func loadBuiltInProfileIDs(t *testing.T) map[string]string {
+	t.Helper()
+
+	ids := map[string]string{}
+	err := fs.WalkDir(assets, assetRoot, func(name string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() || !strings.HasSuffix(name, ".yml") {
+			return nil
+		}
+
+		data, err := assets.ReadFile(name)
+		if err != nil {
+			t.Fatalf("failed to read built-in profile %s: %v", name, err)
+		}
+
+		var raw map[string]any
+		if err := yaml.Unmarshal(data, &raw); err != nil {
+			t.Fatalf("failed to decode built-in profile %s: %v", name, err)
+		}
+		if _, ok := raw["api_key"]; ok {
+			t.Fatalf("built-in profile %s contains raw api_key", name)
+		}
+		id, ok := raw["id"].(string)
+		if !ok || strings.TrimSpace(id) == "" {
+			t.Fatalf("built-in profile %s has missing id", name)
+		}
+		if previous, ok := ids[id]; ok {
+			t.Fatalf("duplicate built-in profile id %q in %s and %s", id, previous, name)
+		}
+		ids[id] = name
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("failed to walk built-in profiles: %v", err)
+	}
+	return ids
+}
+
+func TestRepositoryWithPrimaryUsesPrimaryBeforeBuiltIns(t *testing.T) {
+	repo := NewRepositoryWithPrimary(staticProfileRepo{
+		profiles: map[string]string{"mistral-small-3": "custom-model"},
+	})
+
+	p, err := repo.GetProfile(context.Background(), "mistral-small-3")
+	if err != nil {
+		t.Fatalf("expected profile to load, got %v", err)
+	}
+	if p.Model != "custom-model" {
+		t.Fatalf("expected primary profile to override built-in, got %+v", p)
+	}
+}
+
+func TestRepositoryWithPrimaryFallsBackToBuiltIns(t *testing.T) {
+	repo := NewRepositoryWithPrimary(staticProfileRepo{})
+
+	p, err := repo.GetProfile(context.Background(), "mistral-small-3")
+	if err != nil {
+		t.Fatalf("expected built-in profile to load, got %v", err)
+	}
+	if p.ID != "mistral-small-3" {
+		t.Fatalf("unexpected profile: %+v", p)
+	}
+}
+
+func TestRepositoryWithPrimaryDoesNotFallBackAfterPrimaryError(t *testing.T) {
+	repo := NewRepositoryWithPrimary(staticProfileRepo{err: profile.ErrInvalidProfile})
+
+	_, err := repo.GetProfile(context.Background(), "mistral-small-3")
+	if !errors.Is(err, profile.ErrInvalidProfile) {
+		t.Fatalf("expected primary error, got %v", err)
+	}
+}
+
+type staticProfileRepo struct {
+	profiles map[string]string
+	err      error
+}
+
+func (r staticProfileRepo) GetProfile(_ context.Context, id string) (*domain.ExecutionProfile, error) {
+	if r.err != nil {
+		return nil, r.err
+	}
+	if model, ok := r.profiles[id]; ok {
+		return &domain.ExecutionProfile{ID: id, Endpoint: "http://primary/v1", Model: model}, nil
+	}
+	return nil, profile.ErrProfileNotFound
+}

internal/profile/filesystem_repository.go

@@ -5,8 +5,9 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io/fs"
 	"os"
-	"path/filepath"
+	"path"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
@@ -30,11 +31,56 @@ func NewFilesystemRepository(dir string) Repository {
 }
 
 func (r *filesystemRepository) GetProfile(ctx context.Context, id string) (*domain.ExecutionProfile, error) {
+	return loadProfile(ctx, os.DirFS(r.dir), ".", id)
+}
+
+type fsRepository struct {
+	fsys fs.FS
+	root string
+}
+
+func NewFSRepository(fsys fs.FS, root string) Repository {
+	return &fsRepository{fsys: fsys, root: root}
+}
+
+func (r *fsRepository) GetProfile(ctx context.Context, id string) (*domain.ExecutionProfile, error) {
+	return loadProfile(ctx, r.fsys, r.root, id)
+}
+
+type overlayRepository struct {
+	primary  Repository
+	fallback Repository
+}
+
+func NewOverlayRepository(primary, fallback Repository) Repository {
+	return &overlayRepository{primary: primary, fallback: fallback}
+}
+
+func (r *overlayRepository) GetProfile(ctx context.Context, id string) (*domain.ExecutionProfile, error) {
+	if r.primary != nil {
+		prof, err := r.primary.GetProfile(ctx, id)
+		if err == nil {
+			return prof, nil
+		}
+		if !errors.Is(err, ErrProfileNotFound) {
+			return nil, err
+		}
+	}
+	if r.fallback == nil {
+		return nil, ErrProfileNotFound
+	}
+	return r.fallback.GetProfile(ctx, id)
+}
+
+func loadProfile(ctx context.Context, fsys fs.FS, root string, id string) (*domain.ExecutionProfile, error) {
 	if strings.TrimSpace(id) == "" {
 		return nil, fmt.Errorf("%w: profile id is required", ErrInvalidProfile)
 	}
+	if fsys == nil {
+		return nil, fmt.Errorf("failed to read profile directory: filesystem is nil")
+	}
 
-	files, err := filecatalog.FindYAMLFiles(ctx, r.dir)
+	files, err := filecatalog.FindFSYAMLFiles(ctx, fsys, root)
 	if err != nil {
 		return nil, fmt.Errorf("failed to read profile directory: %w", err)
 	}
@@ -47,9 +93,9 @@ func (r *filesystemRepository) GetProfile(ctx context.Context, id string) (*doma
 		default:
 		}
 
-		relPath := filecatalog.RelativePath(r.dir, fullPath)
-		fileMatch := filecatalog.Stem(filepath.Base(fullPath)) == id
-		data, err := os.ReadFile(fullPath)
+		relPath := filecatalog.DisplayPath(root, fullPath)
+		fileMatch := filecatalog.Stem(path.Base(fullPath)) == id
+		data, err := fs.ReadFile(fsys, fullPath)
 		if err != nil {
 			return nil, fmt.Errorf("failed to read profile file %s: %w", relPath, err)
 		}

internal/profile/repository_test.go

@@ -8,6 +8,9 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+	"testing/fstest"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
 )
 
 func TestFilesystemRepository_GetProfile(t *testing.T) {
@@ -261,3 +264,216 @@ func writeProfileTestFile(t *testing.T, path string, content string) {
 		t.Fatalf("failed to write profile test file %q: %v", path, err)
 	}
 }
+
+func TestFSRepository(t *testing.T) {
+	ctx := context.Background()
+
+	t.Run("loads valid profiles from nested directories", func(t *testing.T) {
+		repo := NewFSRepository(fstest.MapFS{
+			"profiles/provider/nested.yaml": profileMapFile(`
+id: nested-profile
+endpoint: http://localhost:8000/v1
+model: nested-model
+temperature: 0.1
+`),
+		}, "profiles")
+
+		p, err := repo.GetProfile(ctx, "nested-profile")
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if p.ID != "nested-profile" || p.Model != "nested-model" {
+			t.Fatalf("unexpected profile: %+v", p)
+		}
+	})
+
+	t.Run("rejects unknown YAML fields", func(t *testing.T) {
+		repo := NewFSRepository(fstest.MapFS{
+			"profiles/unknown.yaml": profileMapFile(`
+id: unknown-profile
+endpoint: http://localhost:8000/v1
+model: model
+unknown: value
+`),
+		}, "profiles")
+
+		_, err := repo.GetProfile(ctx, "unknown-profile")
+		if !errors.Is(err, ErrInvalidYAML) {
+			t.Fatalf("expected ErrInvalidYAML, got %v", err)
+		}
+	})
+
+	t.Run("rejects raw api_key in selected profile", func(t *testing.T) {
+		repo := NewFSRepository(fstest.MapFS{
+			"profiles/raw.yaml": profileMapFile(`
+id: raw-profile
+endpoint: http://localhost:8000/v1
+model: model
+api_key: secret
+`),
+		}, "profiles")
+
+		_, err := repo.GetProfile(ctx, "raw-profile")
+		if !errors.Is(err, ErrRawAPIKeyNotAllowed) {
+			t.Fatalf("expected ErrRawAPIKeyNotAllowed, got %v", err)
+		}
+	})
+
+	t.Run("ignores raw api_key in non-selected profiles", func(t *testing.T) {
+		repo := NewFSRepository(fstest.MapFS{
+			"profiles/raw.yaml": profileMapFile(`
+id: raw-profile
+endpoint: http://localhost:8000/v1
+model: model
+api_key: secret
+`),
+			"profiles/valid.yaml": profileMapFile(`
+id: valid-profile
+endpoint: http://localhost:8000/v1
+model: model
+`),
+		}, "profiles")
+
+		p, err := repo.GetProfile(ctx, "valid-profile")
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if p.ID != "valid-profile" {
+			t.Fatalf("unexpected profile: %+v", p)
+		}
+	})
+
+	t.Run("rejects duplicate IDs within one source", func(t *testing.T) {
+		repo := NewFSRepository(fstest.MapFS{
+			"profiles/a.yaml": profileMapFile(`
+id: duplicate-profile
+endpoint: http://localhost:8000/v1
+model: first
+`),
+			"profiles/nested/b.yaml": profileMapFile(`
+id: duplicate-profile
+endpoint: http://localhost:8000/v1
+model: second
+`),
+		}, "profiles")
+
+		_, err := repo.GetProfile(ctx, "duplicate-profile")
+		if !errors.Is(err, ErrInvalidProfile) {
+			t.Fatalf("expected ErrInvalidProfile, got %v", err)
+		}
+		for _, want := range []string{"duplicate execution profile id", "a.yaml", "nested/b.yaml"} {
+			if !strings.Contains(err.Error(), want) {
+				t.Fatalf("expected error to contain %q, got %v", want, err)
+			}
+		}
+	})
+}
+
+func TestOverlayRepository(t *testing.T) {
+	ctx := context.Background()
+	primaryProfile := &domain.ExecutionProfile{ID: "shared", Endpoint: "http://primary", Model: "primary"}
+	fallbackProfile := &domain.ExecutionProfile{ID: "shared", Endpoint: "http://fallback", Model: "fallback"}
+
+	t.Run("returns primary matches before fallback matches", func(t *testing.T) {
+		repo := NewOverlayRepository(
+			staticProfileRepo{profiles: map[string]*domain.ExecutionProfile{"shared": primaryProfile}},
+			staticProfileRepo{profiles: map[string]*domain.ExecutionProfile{"shared": fallbackProfile}},
+		)
+
+		p, err := repo.GetProfile(ctx, "shared")
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if p.Model != "primary" {
+			t.Fatalf("expected primary profile, got %+v", p)
+		}
+	})
+
+	t.Run("falls back on primary not found", func(t *testing.T) {
+		repo := NewOverlayRepository(
+			staticProfileRepo{},
+			staticProfileRepo{profiles: map[string]*domain.ExecutionProfile{"shared": fallbackProfile}},
+		)
+
+		p, err := repo.GetProfile(ctx, "shared")
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if p.Model != "fallback" {
+			t.Fatalf("expected fallback profile, got %+v", p)
+		}
+	})
+
+	t.Run("does not fall back after primary load errors", func(t *testing.T) {
+		for _, tc := range []struct {
+			name string
+			err  error
+		}{
+			{name: "invalid yaml", err: ErrInvalidYAML},
+			{name: "invalid profile", err: ErrInvalidProfile},
+			{name: "raw api key", err: ErrRawAPIKeyNotAllowed},
+		} {
+			t.Run(tc.name, func(t *testing.T) {
+				repo := NewOverlayRepository(
+					staticProfileRepo{err: tc.err},
+					staticProfileRepo{profiles: map[string]*domain.ExecutionProfile{"shared": fallbackProfile}},
+				)
+
+				_, err := repo.GetProfile(ctx, "shared")
+				if !errors.Is(err, tc.err) {
+					t.Fatalf("expected %v, got %v", tc.err, err)
+				}
+			})
+		}
+	})
+
+	t.Run("returns not found when both sources miss", func(t *testing.T) {
+		repo := NewOverlayRepository(staticProfileRepo{}, staticProfileRepo{})
+
+		_, err := repo.GetProfile(ctx, "missing")
+		if !errors.Is(err, ErrProfileNotFound) {
+			t.Fatalf("expected ErrProfileNotFound, got %v", err)
+		}
+	})
+
+	t.Run("nil primary uses fallback", func(t *testing.T) {
+		repo := NewOverlayRepository(nil, staticProfileRepo{profiles: map[string]*domain.ExecutionProfile{"shared": fallbackProfile}})
+
+		p, err := repo.GetProfile(ctx, "shared")
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if p.Model != "fallback" {
+			t.Fatalf("expected fallback profile, got %+v", p)
+		}
+	})
+
+	t.Run("nil fallback returns not found after primary miss", func(t *testing.T) {
+		repo := NewOverlayRepository(staticProfileRepo{}, nil)
+
+		_, err := repo.GetProfile(ctx, "missing")
+		if !errors.Is(err, ErrProfileNotFound) {
+			t.Fatalf("expected ErrProfileNotFound, got %v", err)
+		}
+	})
+}
+
+func profileMapFile(content string) *fstest.MapFile {
+	return &fstest.MapFile{Data: []byte(strings.TrimLeft(content, "\n"))}
+}
+
+type staticProfileRepo struct {
+	profiles map[string]*domain.ExecutionProfile
+	err      error
+}
+
+func (r staticProfileRepo) GetProfile(_ context.Context, id string) (*domain.ExecutionProfile, error) {
+	if r.err != nil {
+		return nil, r.err
+	}
+	if p, ok := r.profiles[id]; ok {
+		cp := *p
+		return &cp, nil
+	}
+	return nil, ErrProfileNotFound
+}

internal/promptdef/filesystem_repository.go

@@ -5,7 +5,9 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io/fs"
 	"os"
+	"path"
 	"path/filepath"
 	"strings"
 
@@ -24,6 +26,11 @@ type filesystemRepository struct {
 	dir string
 }
 
+type fsRepository struct {
+	fsys fs.FS
+	root string
+}
+
 type promptDefinitionFile struct {
 	ID             string                   `yaml:"id"`
 	Version        string                   `yaml:"version"`
@@ -65,6 +72,10 @@ func NewFilesystemRepository(dir string) Repository {
 	return &filesystemRepository{dir: dir}
 }
 
+func NewFSRepository(fsys fs.FS, root string) Repository {
+	return &fsRepository{fsys: fsys, root: root}
+}
+
 func (r *filesystemRepository) GetPromptDefinition(ctx context.Context, id string, version string) (*domain.PromptDefinition, error) {
 	if strings.TrimSpace(id) == "" {
 		return nil, fmt.Errorf("%w: prompt id is required", ErrInvalidPromptDefinition)
@@ -132,6 +143,10 @@ func (r *filesystemRepository) GetPromptDefinition(ctx context.Context, id strin
 	return nil, ErrPromptDefinitionNotFound
 }
 
+func (r *fsRepository) GetPromptDefinition(ctx context.Context, id string, version string) (*domain.PromptDefinition, error) {
+	return loadPromptDefinition(ctx, r.fsys, r.root, id, version)
+}
+
 type promptDefinitionMatch struct {
 	def  *domain.PromptDefinition
 	path string
@@ -166,7 +181,152 @@ func promptDefinitionFileHasID(path string, id string) bool {
 	return strings.TrimSpace(raw.ID) == id
 }
 
+func loadPromptDefinition(ctx context.Context, fsys fs.FS, root string, id string, version string) (*domain.PromptDefinition, error) {
+	if strings.TrimSpace(id) == "" {
+		return nil, fmt.Errorf("%w: prompt id is required", ErrInvalidPromptDefinition)
+	}
+	if fsys == nil {
+		return nil, fmt.Errorf("failed to read prompt definition directory: filesystem is nil")
+	}
+
+	files, err := filecatalog.FindFSYAMLFiles(ctx, fsys, root)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read prompt definition directory: %w", err)
+	}
+	cleanRoot := filecatalog.CleanFSRoot(root)
+	rootInfo, err := fs.Stat(fsys, cleanRoot)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read prompt definition directory: %w", err)
+	}
+
+	var matches []promptDefinitionMatch
+	for _, fullPath := range files {
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		default:
+		}
+
+		relPath := filecatalog.DisplayPath(root, fullPath)
+		fileMatch := filecatalog.Stem(path.Base(fullPath)) == id
+		data, err := fs.ReadFile(fsys, fullPath)
+		if err != nil {
+			if fileMatch {
+				return nil, fmt.Errorf("%w: %s: failed to read prompt definition file: %v", ErrInvalidYAML, relPath, err)
+			}
+			continue
+		}
+
+		raw, err := decodePromptDefinition(data)
+		if err != nil {
+			if fileMatch || promptDefinitionDataHasID(data, id) {
+				return nil, fmt.Errorf("%w: %s: %v", ErrInvalidYAML, relPath, err)
+			}
+			continue
+		}
+
+		def, err := normalizePromptDefinitionFromFS(raw, fsys, root, fullPath, rootInfo.IsDir())
+		if err != nil {
+			if fileMatch || strings.TrimSpace(raw.ID) == id {
+				return nil, fmt.Errorf("%w: %s: %v", ErrInvalidPromptDefinition, relPath, err)
+			}
+			continue
+		}
+
+		if def.ID != id {
+			continue
+		}
+		if version != "" && def.Version != version {
+			continue
+		}
+		matches = append(matches, promptDefinitionMatch{
+			def:  def,
+			path: relPath,
+		})
+	}
+
+	if len(matches) > 1 {
+		paths := make([]string, 0, len(matches))
+		for _, match := range matches {
+			paths = append(paths, match.path)
+		}
+		if version != "" {
+			return nil, fmt.Errorf("%w: duplicate prompt definition id %q version %q found in: %s", ErrInvalidPromptDefinition, id, version, strings.Join(paths, ", "))
+		}
+		return nil, fmt.Errorf("%w: duplicate prompt definition id %q found in: %s", ErrInvalidPromptDefinition, id, strings.Join(paths, ", "))
+	}
+
+	if len(matches) == 1 {
+		return matches[0].def, nil
+	}
+
+	return nil, ErrPromptDefinitionNotFound
+}
+
+func decodePromptDefinition(data []byte) (*promptDefinitionFile, error) {
+	var raw promptDefinitionFile
+	decoder := yaml.NewDecoder(bytes.NewReader(data))
+	decoder.KnownFields(true)
+	if err := decoder.Decode(&raw); err != nil {
+		return nil, err
+	}
+	return &raw, nil
+}
+
+func promptDefinitionDataHasID(data []byte, id string) bool {
+	var raw struct {
+		ID string `yaml:"id"`
+	}
+	if err := yaml.NewDecoder(bytes.NewReader(data)).Decode(&raw); err != nil {
+		return false
+	}
+	return strings.TrimSpace(raw.ID) == id
+}
+
 func normalizePromptDefinition(raw *promptDefinitionFile, sourcePath string) (*domain.PromptDefinition, error) {
+	promptDir := filepath.Dir(sourcePath)
+	return normalizePromptDefinitionWithContent(raw, func(contentFile string) (string, string, error) {
+		resolvedPath := strings.TrimSpace(contentFile)
+		if !filepath.IsAbs(resolvedPath) {
+			resolvedPath = filepath.Join(promptDir, resolvedPath)
+		}
+		resolvedPath = filepath.Clean(resolvedPath)
+
+		body, err := os.ReadFile(resolvedPath)
+		if err != nil {
+			return "", "", err
+		}
+		return string(body), resolvedPath, nil
+	})
+}
+
+func normalizePromptDefinitionFromFS(raw *promptDefinitionFile, fsys fs.FS, root string, sourcePath string, rootIsDir bool) (*domain.PromptDefinition, error) {
+	promptDir := path.Dir(sourcePath)
+	return normalizePromptDefinitionWithContent(raw, func(contentFile string) (string, string, error) {
+		var resolvedPath string
+		if rootIsDir {
+			var err error
+			resolvedPath, _, err = filecatalog.ResolveFSPath(root, promptDir, contentFile)
+			if err != nil {
+				return "", "", err
+			}
+		} else {
+			resolvedPath = strings.TrimSpace(contentFile)
+			if !path.IsAbs(resolvedPath) {
+				resolvedPath = path.Join(promptDir, resolvedPath)
+			}
+			resolvedPath = strings.TrimPrefix(path.Clean(resolvedPath), "/")
+		}
+
+		body, err := fs.ReadFile(fsys, resolvedPath)
+		if err != nil {
+			return "", "", err
+		}
+		return string(body), resolvedPath, nil
+	})
+}
+
+func normalizePromptDefinitionWithContent(raw *promptDefinitionFile, readContentFile func(string) (string, string, error)) (*domain.PromptDefinition, error) {
 	if raw == nil {
 		return nil, errors.New("prompt definition is nil")
 	}
@@ -206,7 +366,6 @@ func normalizePromptDefinition(raw *promptDefinitionFile, sourcePath string) (*d
 	}
 
 	templates := make([]domain.PromptMessageTemplate, 0, len(raw.Messages))
-	promptDir := filepath.Dir(sourcePath)
 	for i, msg := range raw.Messages {
 		role := strings.TrimSpace(msg.Role)
 		if role == "" {
@@ -227,17 +386,11 @@ func normalizePromptDefinition(raw *promptDefinitionFile, sourcePath string) (*d
 		templateContent := msg.Content
 		resolvedContentFile := ""
 		if hasContentFile {
-			resolvedPath := strings.TrimSpace(msg.ContentFile)
-			if !filepath.IsAbs(resolvedPath) {
-				resolvedPath = filepath.Join(promptDir, resolvedPath)
-			}
-			resolvedPath = filepath.Clean(resolvedPath)
-
-			body, err := os.ReadFile(resolvedPath)
+			body, resolvedPath, err := readContentFile(msg.ContentFile)
 			if err != nil {
 				return nil, fmt.Errorf("prompt %q message %d (%s): failed to read content_file %q: %w", id, i, role, msg.ContentFile, err)
 			}
-			templateContent = string(body)
+			templateContent = body
 			resolvedContentFile = resolvedPath
 		}
 

internal/promptdef/repository_test.go

@@ -8,6 +8,7 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+	"testing/fstest"
 
 	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
 )
@@ -324,6 +325,160 @@ output:
 	})
 }
 
+func TestFSRepositoryGetPromptDefinition(t *testing.T) {
+	repo := NewFSRepository(fstest.MapFS{
+		"prompts/nested/prompt.yaml": &fstest.MapFile{Data: []byte(`
+id: fs-prompt
+version: "1.0.0"
+inputs:
+  - name: transcript
+    required: true
+messages:
+  - role: user
+    content_file: ./messages/user.tmpl
+output:
+  format: markdown
+  validation_mode: basic
+  repair_attempts: 0
+`)},
+		"prompts/nested/messages/user.tmpl": &fstest.MapFile{Data: []byte(`Summarize {{input "transcript"}}.`)},
+	}, "prompts")
+
+	got, err := repo.GetPromptDefinition(context.Background(), "fs-prompt", "")
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if got.ID != "fs-prompt" {
+		t.Fatalf("unexpected prompt id: %q", got.ID)
+	}
+	if len(got.Templates) != 1 || !strings.Contains(got.Templates[0].Content, `{{input "transcript"}}`) {
+		t.Fatalf("expected content_file body to be loaded, got %+v", got.Templates)
+	}
+	if got.Templates[0].ContentFile != "prompts/nested/messages/user.tmpl" {
+		t.Fatalf("unexpected content file path: %q", got.Templates[0].ContentFile)
+	}
+}
+
+func TestFSRepositoryContentFileContainment(t *testing.T) {
+	t.Run("nested prompt can reference file inside root", func(t *testing.T) {
+		repo := NewFSRepository(fstest.MapFS{
+			"prompts/nested/prompt.yaml": &fstest.MapFile{Data: []byte(`
+id: fs-contained-prompt
+version: "1.0.0"
+messages:
+  - role: user
+    content_file: ../shared/user.tmpl
+output:
+  format: markdown
+  validation_mode: basic
+  repair_attempts: 0
+`)},
+			"prompts/shared/user.tmpl": &fstest.MapFile{Data: []byte(`Inside root.`)},
+		}, "prompts")
+
+		got, err := repo.GetPromptDefinition(context.Background(), "fs-contained-prompt", "")
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if len(got.Templates) != 1 || got.Templates[0].Content != "Inside root." {
+			t.Fatalf("expected contained content file, got %+v", got.Templates)
+		}
+	})
+
+	tests := []struct {
+		name        string
+		contentFile string
+		wantErr     string
+	}{
+		{name: "parent escape rejected", contentFile: "../outside.tmpl", wantErr: "escapes source root"},
+		{name: "absolute path rejected", contentFile: "/outside.tmpl", wantErr: "must be relative"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			repo := NewFSRepository(fstest.MapFS{
+				"prompts/prompt.yaml": &fstest.MapFile{Data: []byte(`
+id: fs-escaped-prompt
+version: "1.0.0"
+messages:
+  - role: user
+    content_file: ` + tc.contentFile + `
+output:
+  format: markdown
+  validation_mode: basic
+  repair_attempts: 0
+`)},
+				"outside.tmpl": &fstest.MapFile{Data: []byte(`Outside root.`)},
+			}, "prompts")
+
+			_, err := repo.GetPromptDefinition(context.Background(), "fs-escaped-prompt", "")
+			if !errors.Is(err, ErrInvalidPromptDefinition) {
+				t.Fatalf("expected ErrInvalidPromptDefinition, got %v", err)
+			}
+			if !strings.Contains(err.Error(), tc.wantErr) {
+				t.Fatalf("expected error to contain %q, got %v", tc.wantErr, err)
+			}
+		})
+	}
+}
+
+func TestFSRepositoryRejectsDuplicatePromptIDs(t *testing.T) {
+	repo := NewFSRepository(fstest.MapFS{
+		"one.yaml": &fstest.MapFile{Data: []byte(`
+id: duplicate-fs-prompt
+version: "1.0.0"
+messages:
+  - role: user
+    content: First.
+output:
+  format: text
+  validation_mode: none
+  repair_attempts: 0
+`)},
+		"nested/two.yaml": &fstest.MapFile{Data: []byte(`
+id: duplicate-fs-prompt
+version: "1.0.0"
+messages:
+  - role: user
+    content: Second.
+output:
+  format: text
+  validation_mode: none
+  repair_attempts: 0
+`)},
+	}, ".")
+
+	_, err := repo.GetPromptDefinition(context.Background(), "duplicate-fs-prompt", "")
+	if !errors.Is(err, ErrInvalidPromptDefinition) {
+		t.Fatalf("expected ErrInvalidPromptDefinition, got %v", err)
+	}
+	if !strings.Contains(err.Error(), "one.yaml") || !strings.Contains(err.Error(), "nested/two.yaml") {
+		t.Fatalf("expected duplicate paths in error, got %v", err)
+	}
+}
+
+func TestFSRepositoryRejectsUnknownYAMLFields(t *testing.T) {
+	repo := NewFSRepository(fstest.MapFS{
+		"not_named_like_id.yaml": &fstest.MapFile{Data: []byte(`
+id: strict-fs-prompt
+version: "1.0.0"
+unknown: true
+messages:
+  - role: user
+    content: Invalid.
+output:
+  format: text
+  validation_mode: none
+  repair_attempts: 0
+`)},
+	}, ".")
+
+	_, err := repo.GetPromptDefinition(context.Background(), "strict-fs-prompt", "")
+	if !errors.Is(err, ErrInvalidYAML) {
+		t.Fatalf("expected ErrInvalidYAML, got %v", err)
+	}
+}
+
 func assertCacheControl(t *testing.T, got *domain.CacheControl, wantType domain.CacheControlType, wantTTL string) {
 	t.Helper()
 	if got == nil {

internal/usecase/integration_test.go

@@ -1,127 +0,0 @@
-package usecase
-
-import (
-	"context"
-	"path/filepath"
-	"testing"
-
-	"gitea.maximumdirect.net/eric/scriptorium/internal/artifact"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/prompt"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/promptdef"
-	"gitea.maximumdirect.net/eric/scriptorium/internal/validate"
-)
-
-type integrationLLM struct{}
-
-func (f *integrationLLM) Generate(ctx context.Context, req domain.GenerateRequest) (*domain.GenerateResponse, error) {
-	lastIntegrationRequest = req
-	return &domain.GenerateResponse{
-		Content: `{"summary":"Party discovered a captive scout beneath the tower.","events":[{"title":"Scout found in cellar","type":"discovery","notes":"Scout requested rescue from goblin raiders."}]}`,
-		Usage: domain.TokenUsage{
-			PromptTokens:     42,
-			CompletionTokens: 36,
-			TotalTokens:      78,
-		},
-	}, nil
-}
-
-var lastIntegrationRequest domain.GenerateRequest
-
-func TestRunnerIntegrationWithPromptAndProfileFixturesAndValidation(t *testing.T) {
-	root, err := filepath.Abs(filepath.Join("..", ".."))
-	if err != nil {
-		t.Fatalf("failed to resolve repo root: %v", err)
-	}
-
-	promptsDir := filepath.Join(root, "examples", "prompts")
-	profilesDir := filepath.Join(root, "examples", "profiles")
-	schemasDir := filepath.Join(root, "examples", "schemas")
-	fixturesDir := filepath.Join(root, "examples", "fixtures")
-	t.Setenv("SCRIPTORIUM_API_KEY", "test-key")
-
-	runner := NewRunner(
-		promptdef.NewFilesystemRepository(promptsDir),
-		profile.NewFilesystemRepository(profilesDir),
-		artifact.NewCompositeReader(),
-		prompt.NewGoRenderer(),
-		&integrationLLM{},
-		validate.NewStandardValidator(schemasDir),
-	)
-
-	res, err := runner.Run(context.Background(), domain.RunRequest{
-		PromptID: "generic.structured_events",
-		Inputs: map[string]domain.ArtifactRef{
-			"transcript": {
-				Type: domain.ArtifactRefFile,
-				URI:  filepath.Join(fixturesDir, "transcript.md"),
-			},
-			"glossary": {
-				Type: domain.ArtifactRefFile,
-				URI:  filepath.Join(fixturesDir, "glossary.yml"),
-			},
-		},
-	})
-	if err != nil {
-		t.Fatalf("expected no error, got %v", err)
-	}
-
-	if res.PromptID != "generic.structured_events" {
-		t.Fatalf("unexpected prompt id: %q", res.PromptID)
-	}
-	if res.SelectedProfileID != "local-quality" {
-		t.Fatalf("expected selected profile local-quality from prompt default, got %q", res.SelectedProfileID)
-	}
-	if res.RunID == "" {
-		t.Fatal("expected run id")
-	}
-	if res.PromptHash == "" {
-		t.Fatal("expected prompt hash")
-	}
-	if res.PromptVersion != "1.0.0" {
-		t.Fatalf("unexpected prompt version: %q", res.PromptVersion)
-	}
-	if res.Validation.Status != domain.ValidationPassed {
-		t.Fatalf("expected passed validation, got %q", res.Validation.Status)
-	}
-	if res.Validation.Mode != domain.ValidationJSONSchema {
-		t.Fatalf("expected json_schema mode, got %q", res.Validation.Mode)
-	}
-	if lastIntegrationRequest.StructuredOutput == nil {
-		t.Fatal("expected provider-level structured output request for json_schema prompt")
-	}
-	if lastIntegrationRequest.StructuredOutput.Type != domain.StructuredOutputJSONSchema {
-		t.Fatalf("expected structured output type json_schema, got %q", lastIntegrationRequest.StructuredOutput.Type)
-	}
-	if lastIntegrationRequest.StructuredOutput.JSONSchema == nil || lastIntegrationRequest.StructuredOutput.JSONSchema.Schema == nil {
-		t.Fatalf("expected structured output json_schema payload, got %+v", lastIntegrationRequest.StructuredOutput.JSONSchema)
-	}
-	if res.Artifact.ContentType != "application/json" {
-		t.Fatalf("expected application/json output, got %q", res.Artifact.ContentType)
-	}
-	if len(res.RawOutput) == 0 {
-		t.Fatal("expected raw output to be preserved")
-	}
-	if res.PromptHash == "" {
-		t.Fatal("expected non-empty prompt hash")
-	}
-	if len(res.InputHashes) != 2 {
-		t.Fatalf("expected two input hashes, got %d", len(res.InputHashes))
-	}
-	if res.InputHashes["transcript"] == "" || res.InputHashes["glossary"] == "" {
-		t.Fatalf("expected both input hashes to be set, got %#v", res.InputHashes)
-	}
-	if res.Usage.TotalTokens != 78 {
-		t.Fatalf("expected usage from fake llm, got %+v", res.Usage)
-	}
-	if res.StartTime.IsZero() || res.EndTime.IsZero() {
-		t.Fatal("expected start/end timestamps")
-	}
-	if res.EndTime.Before(res.StartTime) {
-		t.Fatalf("expected end >= start, got start=%v end=%v", res.StartTime, res.EndTime)
-	}
-	if res.Duration < 0 {
-		t.Fatalf("expected non-negative duration, got %s", res.Duration)
-	}
-}

internal/usecase/runner.go

@@ -27,7 +27,9 @@ var (
 	ErrInvalidRequest   = errors.New("invalid run request")
 	ErrProfileRequired  = errors.New("profile selection is required")
 	ErrAPIKeyEnvMissing = errors.New("api_key_env points to an unset environment variable")
-	ErrProfileLoad      = errors.New("failed to load prompt definition")
+	ErrAPIKeyRequired   = errors.New("api key is required")
+	ErrPromptLoad       = errors.New("failed to load prompt definition")
+	ErrProfileLoad      = errors.New("failed to load execution profile")
 	ErrArtifactLoad     = errors.New("failed to load artifact")
 	ErrPromptRender     = errors.New("failed to render prompt")
 	ErrLLMGenerate      = errors.New("failed to generate output")
@@ -171,11 +173,11 @@ func (r *Runner) Prepare(ctx context.Context, req domain.RunRequest) (*domain.Pr
 
 	def, err := r.promptDefs.GetPromptDefinition(ctx, req.PromptID, req.PromptVersion)
 	if err != nil {
-		return nil, fmt.Errorf("%w: %w", ErrProfileLoad, err)
+		return nil, fmt.Errorf("%w: %w", ErrPromptLoad, err)
 	}
 	promptDefinitionHash, err := hashPromptDefinition(def)
 	if err != nil {
-		return nil, fmt.Errorf("%w: failed to hash prompt definition: %v", ErrProfileLoad, err)
+		return nil, fmt.Errorf("%w: failed to hash prompt definition: %v", ErrPromptLoad, err)
 	}
 
 	selectedProfileID := strings.TrimSpace(req.ProfileID)
@@ -195,13 +197,14 @@ func (r *Runner) Prepare(ctx context.Context, req domain.RunRequest) (*domain.Pr
 	if err != nil {
 		return nil, fmt.Errorf("%w: %w", ErrInvalidRequest, err)
 	}
+	effectiveModel.APIKey = req.APIKey
 	if strings.TrimSpace(effectiveModel.Endpoint) == "" {
 		return nil, fmt.Errorf("%w: execution endpoint is required", ErrInvalidRequest)
 	}
 	if strings.TrimSpace(effectiveModel.Model) == "" {
 		return nil, fmt.Errorf("%w: execution model is required", ErrInvalidRequest)
 	}
-	if err := validateAPIKeyEnv(effectiveModel.APIKeyEnv); err != nil {
+	if err := validateAPIKey(effectiveModel.APIKeyEnv, effectiveModel.APIKey, effectiveModel.APIKeyRequired); err != nil {
 		return nil, fmt.Errorf("%w: %w", ErrInvalidRequest, err)
 	}
 
@@ -362,6 +365,9 @@ func mergeExecutionTarget(base domain.ExecutionTarget, override domain.Execution
 	if strings.TrimSpace(override.APIKeyEnv) != "" {
 		out.APIKeyEnv = override.APIKeyEnv
 	}
+	if override.APIKeyRequired {
+		out.APIKeyRequired = true
+	}
 	if len(override.ExtraParams) > 0 {
 		out.ExtraParams = copyExtraParams(override.ExtraParams)
 	}
@@ -434,9 +440,15 @@ func resolveExecutionTarget(profileValue *domain.ExecutionProfile, override *dom
 	return out, presence, nil
 }
 
-func validateAPIKeyEnv(apiKeyEnv string) error {
+func validateAPIKey(apiKeyEnv string, apiKey string, apiKeyRequired bool) error {
+	if strings.TrimSpace(apiKey) != "" {
+		return nil
+	}
 	envName := strings.TrimSpace(apiKeyEnv)
 	if envName == "" {
+		if apiKeyRequired {
+			return ErrAPIKeyRequired
+		}
 		return nil
 	}
 	if strings.TrimSpace(os.Getenv(envName)) == "" {
@@ -459,6 +471,7 @@ func executionProfileToTarget(p *domain.ExecutionProfile) domain.ExecutionTarget
 		ServiceTier:     p.ServiceTier,
 		ReasoningEffort: p.ReasoningEffort,
 		APIKeyEnv:       p.APIKeyEnv,
+		APIKeyRequired:  p.APIKeyRequired,
 		ExtraParams:     copyExtraParams(p.ExtraParams),
 	}
 }

internal/usecase/runner_test.go

@@ -253,6 +253,17 @@ func TestRunnerPrepareSelectedProfileDoesNotExistFails(t *testing.T) {
 	}
 }
 
+func TestRunnerPreparePromptLoadFailure(t *testing.T) {
+	runner := NewRunner(&fakePromptRepo{err: errors.New("boom")}, &fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{"exec": defaultExecutionProfile()}}, defaultArtifactReader(), defaultRenderer(), &fakeLLM{}, nil)
+	_, err := runner.Prepare(context.Background(), domain.RunRequest{PromptID: "p"})
+	if !errors.Is(err, ErrPromptLoad) {
+		t.Fatalf("expected ErrPromptLoad, got %v", err)
+	}
+	if errors.Is(err, ErrProfileLoad) {
+		t.Fatalf("did not expect ErrProfileLoad, got %v", err)
+	}
+}
+
 func TestRunnerPrepareRuntimeOverrideBeatsSelectedProfileValue(t *testing.T) {
 	promptRepo := &fakePromptRepo{def: promptDef(domain.FormatText, domain.ValidationNone, 0)}
 	execRepo := &fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{
@@ -1179,6 +1190,75 @@ func TestRunnerRunAPIKeyEnvMissingEnvironmentValueFailsClearly(t *testing.T) {
 	}
 }
 
+func TestRunnerRunDirectAPIKeyBypassesMissingEnvAndReachesLLM(t *testing.T) {
+	const directKey = "direct-runner-key"
+	promptRepo := &fakePromptRepo{def: promptDef(domain.FormatText, domain.ValidationNone, 0)}
+	execRepo := &fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{
+		"exec": {ID: "exec", Endpoint: "http://profile/v1", Model: "profile-model", APIKeyEnv: "SCRIPTORIUM_MISSING_KEY"},
+	}}
+	llmClient := &fakeLLM{resp: &domain.GenerateResponse{Content: "ok"}}
+	runner := NewRunner(promptRepo, execRepo, defaultArtifactReader(), defaultRenderer(), llmClient, nil)
+
+	_, err := runner.Run(context.Background(), domain.RunRequest{
+		PromptID:  "p",
+		ProfileID: "exec",
+		APIKey:    directKey,
+		Inputs:    singleInputRef(),
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if llmClient.lastReq.Target.APIKey != directKey {
+		t.Fatalf("expected direct API key to reach LLM request")
+	}
+	if llmClient.lastReq.Target.APIKeyEnv != "SCRIPTORIUM_MISSING_KEY" {
+		t.Fatalf("expected api_key_env name to remain on target, got %q", llmClient.lastReq.Target.APIKeyEnv)
+	}
+}
+
+func TestRunnerPrepareAPIKeyRequiredFailsWithoutDirectKey(t *testing.T) {
+	promptRepo := &fakePromptRepo{def: promptDef(domain.FormatText, domain.ValidationNone, 0)}
+	execRepo := &fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{
+		"exec": {ID: "exec", Endpoint: "http://profile/v1", Model: "profile-model", APIKeyRequired: true},
+	}}
+	runner := NewRunner(promptRepo, execRepo, defaultArtifactReader(), defaultRenderer(), &fakeLLM{resp: &domain.GenerateResponse{Content: "ok"}}, nil)
+
+	_, err := runner.Prepare(context.Background(), domain.RunRequest{
+		PromptID:  "p",
+		ProfileID: "exec",
+		Inputs:    singleInputRef(),
+	})
+	if !errors.Is(err, ErrAPIKeyRequired) {
+		t.Fatalf("expected ErrAPIKeyRequired, got %v", err)
+	}
+}
+
+func TestRunnerRunAPIKeyRequiredSucceedsWithDirectKey(t *testing.T) {
+	const directKey = "direct-required-key"
+	promptRepo := &fakePromptRepo{def: promptDef(domain.FormatText, domain.ValidationNone, 0)}
+	execRepo := &fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{
+		"exec": {ID: "exec", Endpoint: "http://profile/v1", Model: "profile-model", APIKeyRequired: true},
+	}}
+	llmClient := &fakeLLM{resp: &domain.GenerateResponse{Content: "ok"}}
+	runner := NewRunner(promptRepo, execRepo, defaultArtifactReader(), defaultRenderer(), llmClient, nil)
+
+	_, err := runner.Run(context.Background(), domain.RunRequest{
+		PromptID:  "p",
+		ProfileID: "exec",
+		APIKey:    directKey,
+		Inputs:    singleInputRef(),
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if llmClient.lastReq.Target.APIKey != directKey {
+		t.Fatalf("expected direct API key to reach LLM request")
+	}
+	if !llmClient.lastReq.Target.APIKeyRequired {
+		t.Fatalf("expected APIKeyRequired to be carried to target")
+	}
+}
+
 func TestRunnerRunRuntimeAPIKeyEnvOverrideWorks(t *testing.T) {
 	const envName = "SCRIPTORIUM_RUNTIME_API_KEY"
 	t.Setenv(envName, "runtime-secret")
@@ -1254,8 +1334,11 @@ func TestRunnerRunAPIKeyValueNotPresentInMetadata(t *testing.T) {
 func TestRunnerRunPromptLoadFailure(t *testing.T) {
 	runner := NewRunner(&fakePromptRepo{err: errors.New("boom")}, &fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{"exec": defaultExecutionProfile()}}, defaultArtifactReader(), defaultRenderer(), &fakeLLM{}, nil)
 	_, err := runner.Run(context.Background(), domain.RunRequest{PromptID: "p"})
-	if !errors.Is(err, ErrProfileLoad) {
-		t.Fatalf("expected ErrProfileLoad, got %v", err)
+	if !errors.Is(err, ErrPromptLoad) {
+		t.Fatalf("expected ErrPromptLoad, got %v", err)
+	}
+	if errors.Is(err, ErrProfileLoad) {
+		t.Fatalf("did not expect ErrProfileLoad, got %v", err)
 	}
 }
 
@@ -1468,6 +1551,7 @@ func TestExecutionProfileToTargetPopulatesAllFieldsAndCopiesExtraParams(t *testi
 		ServiceTier:     "priority",
 		ReasoningEffort: "medium",
 		APIKeyEnv:       "SCRIPTORIUM_API_KEY",
+		APIKeyRequired:  true,
 		ExtraParams: map[string]any{
 			"provider_option": "on",
 		},
@@ -1482,7 +1566,8 @@ func TestExecutionProfileToTargetPopulatesAllFieldsAndCopiesExtraParams(t *testi
 		target.TimeoutSeconds != src.TimeoutSeconds ||
 		target.ServiceTier != src.ServiceTier ||
 		target.ReasoningEffort != src.ReasoningEffort ||
-		target.APIKeyEnv != src.APIKeyEnv {
+		target.APIKeyEnv != src.APIKeyEnv ||
+		target.APIKeyRequired != src.APIKeyRequired {
 		t.Fatalf("expected all profile fields to populate target, got %+v", target)
 	}
 	if !reflect.DeepEqual(target.ExtraParams, src.ExtraParams) {
@@ -1507,6 +1592,7 @@ func TestResolveExecutionTargetProfileValuesPopulateAllSupportedFields(t *testin
 		ServiceTier:     "priority",
 		ReasoningEffort: "low",
 		APIKeyEnv:       "PROFILE_KEY",
+		APIKeyRequired:  true,
 		ExtraParams: map[string]any{
 			"profile_option": "enabled",
 		},
@@ -1527,7 +1613,8 @@ func TestResolveExecutionTargetProfileValuesPopulateAllSupportedFields(t *testin
 		target.TimeoutSeconds != profileValue.TimeoutSeconds ||
 		target.ServiceTier != profileValue.ServiceTier ||
 		target.ReasoningEffort != profileValue.ReasoningEffort ||
-		target.APIKeyEnv != profileValue.APIKeyEnv {
+		target.APIKeyEnv != profileValue.APIKeyEnv ||
+		target.APIKeyRequired != profileValue.APIKeyRequired {
 		t.Fatalf("expected profile values to populate target, got %+v", target)
 	}
 	if !reflect.DeepEqual(target.ExtraParams, profileValue.ExtraParams) {

internal/validate/standard_validator.go

@@ -5,11 +5,14 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io/fs"
 	"os"
+	"path"
 	"path/filepath"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/filecatalog"
 	"github.com/santhosh-tekuri/jsonschema/v6"
 )
 
@@ -18,11 +21,30 @@ type StandardValidator struct {
 	schemaBaseDir string
 }
 
+type FSValidator struct {
+	fsys fs.FS
+	root string
+}
+
 func NewStandardValidator(schemaBaseDir string) Validator {
 	return &StandardValidator{schemaBaseDir: schemaBaseDir}
 }
 
+func NewFSValidator(fsys fs.FS, root string) Validator {
+	return &FSValidator{fsys: fsys, root: root}
+}
+
 func (v *StandardValidator) Validate(ctx context.Context, artifact *domain.Artifact, contract domain.OutputContract) (domain.ValidationResult, error) {
+	return validateArtifact(ctx, artifact, contract, v.validateJSONSchema)
+}
+
+func (v *FSValidator) Validate(ctx context.Context, artifact *domain.Artifact, contract domain.OutputContract) (domain.ValidationResult, error) {
+	return validateArtifact(ctx, artifact, contract, v.validateJSONSchema)
+}
+
+type schemaValidatorFunc func(instance any, schemaPath string) ([]string, error)
+
+func validateArtifact(ctx context.Context, artifact *domain.Artifact, contract domain.OutputContract, validateSchema schemaValidatorFunc) (domain.ValidationResult, error) {
 	select {
 	case <-ctx.Done():
 		return domain.ValidationResult{}, ctx.Err()
@@ -74,21 +96,14 @@ func (v *StandardValidator) Validate(ctx context.Context, artifact *domain.Artif
 			return res, nil
 		}
 
-		schemaPath, err := v.resolveSchemaPath(contract.SchemaPath)
+		validationErrors, err := validateSchema(instance, contract.SchemaPath)
 		if err != nil {
 			return domain.ValidationResult{}, err
 		}
-
-		compiler := jsonschema.NewCompiler()
-		schema, err := compiler.Compile(schemaPath)
-		if err != nil {
-			return domain.ValidationResult{}, fmt.Errorf("failed to compile JSON schema %q: %w", schemaPath, err)
-		}
-
-		if err := schema.Validate(instance); err != nil {
+		if len(validationErrors) > 0 {
 			res.Status = domain.ValidationFailed
 			res.IsValid = false
-			res.Errors = []string{fmt.Sprintf("json schema validation failed: %v", err)}
+			res.Errors = validationErrors
 			return res, nil
 		}
 
@@ -100,6 +115,46 @@ func (v *StandardValidator) Validate(ctx context.Context, artifact *domain.Artif
 	}
 }
 
+func (v *StandardValidator) validateJSONSchema(instance any, schemaPath string) ([]string, error) {
+	resolvedSchemaPath, err := v.resolveSchemaPath(schemaPath)
+	if err != nil {
+		return nil, err
+	}
+
+	compiler := jsonschema.NewCompiler()
+	schema, err := compiler.Compile(resolvedSchemaPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", resolvedSchemaPath, err)
+	}
+
+	if err := schema.Validate(instance); err != nil {
+		return []string{fmt.Sprintf("json schema validation failed: %v", err)}, nil
+	}
+	return nil, nil
+}
+
+func (v *FSValidator) validateJSONSchema(instance any, schemaPath string) ([]string, error) {
+	schemaName, schemaDoc, err := v.loadSchemaDocument(schemaPath)
+	if err != nil {
+		return nil, err
+	}
+
+	resourceURL := fsSchemaResourceURL(schemaName)
+	compiler := jsonschema.NewCompiler()
+	if err := compiler.AddResource(resourceURL, schemaDoc); err != nil {
+		return nil, fmt.Errorf("failed to register JSON schema %q: %w", schemaName, err)
+	}
+	schema, err := compiler.Compile(resourceURL)
+	if err != nil {
+		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", schemaName, err)
+	}
+
+	if err := schema.Validate(instance); err != nil {
+		return []string{fmt.Sprintf("json schema validation failed: %v", err)}, nil
+	}
+	return nil, nil
+}
+
 func parseJSON(body []byte) (any, error) {
 	var v any
 	if err := json.Unmarshal(body, &v); err != nil {
@@ -132,6 +187,20 @@ func (v *StandardValidator) LoadSchemaDocument(ctx context.Context, schemaPath s
 	return doc, nil
 }
 
+func (v *FSValidator) LoadSchemaDocument(ctx context.Context, schemaPath string) (any, error) {
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	default:
+	}
+
+	_, doc, err := v.loadSchemaDocument(schemaPath)
+	if err != nil {
+		return nil, err
+	}
+	return doc, nil
+}
+
 func (v *StandardValidator) resolveSchemaPath(schemaPath string) (string, error) {
 	if strings.TrimSpace(schemaPath) == "" {
 		return "", errors.New("schema path is required for json_schema validation")
@@ -149,3 +218,75 @@ func (v *StandardValidator) resolveSchemaPath(schemaPath string) (string, error)
 
 	return resolved, nil
 }
+
+func (v *FSValidator) loadSchemaDocument(schemaPath string) (string, any, error) {
+	resolved, err := v.resolveSchemaPath(schemaPath)
+	if err != nil {
+		return "", nil, err
+	}
+
+	raw, err := fs.ReadFile(v.fsys, resolved)
+	if err != nil {
+		return "", nil, fmt.Errorf("failed to read schema file %q: %w", resolved, err)
+	}
+
+	var doc any
+	if err := json.Unmarshal(raw, &doc); err != nil {
+		return "", nil, fmt.Errorf("failed to decode JSON schema %q: %w", resolved, err)
+	}
+	return resolved, doc, nil
+}
+
+func (v *FSValidator) resolveSchemaPath(schemaPath string) (string, error) {
+	if strings.TrimSpace(schemaPath) == "" {
+		return "", errors.New("schema path is required for json_schema validation")
+	}
+	if v.fsys == nil {
+		return "", errors.New("schema filesystem is nil")
+	}
+
+	cleanRoot := filecatalog.CleanFSRoot(v.root)
+	rootInfo, err := fs.Stat(v.fsys, cleanRoot)
+	if err != nil {
+		return "", fmt.Errorf("failed to access schema source %q: %w", cleanRoot, err)
+	}
+
+	var resolved string
+	if rootInfo.IsDir() {
+		resolvedPath, _, err := filecatalog.ResolveFSPath(cleanRoot, cleanRoot, schemaPath)
+		if err != nil {
+			return "", err
+		}
+		resolved = resolvedPath
+	} else {
+		cleanSchemaPath, err := cleanSchemaFSPath(schemaPath)
+		if err != nil {
+			return "", err
+		}
+		if cleanSchemaPath != path.Base(cleanRoot) {
+			return "", fmt.Errorf("schema path %q does not match schema file %q", cleanSchemaPath, path.Base(cleanRoot))
+		}
+		resolved = cleanRoot
+	}
+
+	if _, err := fs.Stat(v.fsys, resolved); err != nil {
+		return "", fmt.Errorf("failed to access schema file %q: %w", resolved, err)
+	}
+	return resolved, nil
+}
+
+func cleanSchemaFSPath(schemaPath string) (string, error) {
+	cleaned := strings.TrimSpace(schemaPath)
+	if cleaned == "" {
+		return "", errors.New("schema path is required for json_schema validation")
+	}
+	cleaned = path.Clean(cleaned)
+	if path.IsAbs(cleaned) {
+		return "", fmt.Errorf("schema path %q must be relative", schemaPath)
+	}
+	return cleaned, nil
+}
+
+func fsSchemaResourceURL(schemaName string) string {
+	return "scriptorium-schema:///" + strings.TrimPrefix(path.Clean(schemaName), "/")
+}

internal/validate/standard_validator_test.go

@@ -4,7 +4,9 @@ import (
 	"context"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
+	"testing/fstest"
 
 	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
 )
@@ -250,3 +252,132 @@ func TestStandardValidatorLoadSchemaDocumentInvalidJSON(t *testing.T) {
 		t.Fatal("expected decode error")
 	}
 }
+
+func TestFSValidatorJSONSchemaSuccess(t *testing.T) {
+	v := NewFSValidator(fstest.MapFS{
+		"schemas/events.schema.json": &fstest.MapFile{Data: []byte(`{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["events"],
+  "properties": {
+    "events": {"type": "array"}
+  }
+}`)},
+	}, "schemas")
+
+	res, err := v.Validate(context.Background(), &domain.Artifact{Body: []byte(`{"events":[]}`)}, domain.OutputContract{
+		ValidationMode: domain.ValidationJSONSchema,
+		SchemaPath:     "events.schema.json",
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if res.Status != domain.ValidationPassed || !res.IsValid {
+		t.Fatalf("expected passed/valid, got status=%q valid=%v", res.Status, res.IsValid)
+	}
+}
+
+func TestFSValidatorJSONSchemaPathContainment(t *testing.T) {
+	t.Run("nested schema inside root succeeds", func(t *testing.T) {
+		v := NewFSValidator(fstest.MapFS{
+			"schemas/nested/events.schema.json": &fstest.MapFile{Data: []byte(`{
+  "type": "object",
+  "required": ["events"],
+  "properties": {
+    "events": {"type": "array"}
+  }
+}`)},
+		}, "schemas")
+
+		res, err := v.Validate(context.Background(), &domain.Artifact{Body: []byte(`{"events":[]}`)}, domain.OutputContract{
+			ValidationMode: domain.ValidationJSONSchema,
+			SchemaPath:     "nested/events.schema.json",
+		})
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if res.Status != domain.ValidationPassed || !res.IsValid {
+			t.Fatalf("expected passed/valid, got status=%q valid=%v", res.Status, res.IsValid)
+		}
+	})
+
+	tests := []struct {
+		name       string
+		schemaPath string
+		wantErr    string
+	}{
+		{name: "parent escape rejected", schemaPath: "../outside.schema.json", wantErr: "escapes source root"},
+		{name: "absolute path rejected", schemaPath: "/outside.schema.json", wantErr: "must be relative"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			v := NewFSValidator(fstest.MapFS{
+				"schemas/events.schema.json":  &fstest.MapFile{Data: []byte(`{"type":"object"}`)},
+				"outside.schema.json":         &fstest.MapFile{Data: []byte(`{"type":"object"}`)},
+				"schemas/outside.schema.json": &fstest.MapFile{Data: []byte(`{"type":"object"}`)},
+			}, "schemas")
+
+			_, err := v.Validate(context.Background(), &domain.Artifact{Body: []byte(`{"events":[]}`)}, domain.OutputContract{
+				ValidationMode: domain.ValidationJSONSchema,
+				SchemaPath:     tc.schemaPath,
+			})
+			if err == nil {
+				t.Fatal("expected schema path error")
+			}
+			if !strings.Contains(err.Error(), tc.wantErr) {
+				t.Fatalf("expected error to contain %q, got %v", tc.wantErr, err)
+			}
+		})
+	}
+}
+
+func TestFSValidatorSingleSchemaFileUsesBaseName(t *testing.T) {
+	v := NewFSValidator(fstest.MapFS{
+		"events.schema.json": &fstest.MapFile{Data: []byte(`{
+  "type": "object",
+  "required": ["events"],
+  "properties": {
+    "events": {"type": "array"}
+  }
+}`)},
+	}, "events.schema.json")
+
+	res, err := v.Validate(context.Background(), &domain.Artifact{Body: []byte(`{"events":[]}`)}, domain.OutputContract{
+		ValidationMode: domain.ValidationJSONSchema,
+		SchemaPath:     "events.schema.json",
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if res.Status != domain.ValidationPassed || !res.IsValid {
+		t.Fatalf("expected passed/valid, got status=%q valid=%v", res.Status, res.IsValid)
+	}
+
+	_, err = v.Validate(context.Background(), &domain.Artifact{Body: []byte(`{"events":[]}`)}, domain.OutputContract{
+		ValidationMode: domain.ValidationJSONSchema,
+		SchemaPath:     "other.schema.json",
+	})
+	if err == nil {
+		t.Fatal("expected schema path mismatch error")
+	}
+}
+
+func TestFSValidatorLoadSchemaDocument(t *testing.T) {
+	v := NewFSValidator(fstest.MapFS{
+		"schemas/schema.json": &fstest.MapFile{Data: []byte(`{"type":"object"}`)},
+	}, "schemas")
+	loader, ok := v.(SchemaDocumentLoader)
+	if !ok {
+		t.Fatal("fs validator must implement SchemaDocumentLoader")
+	}
+
+	doc, err := loader.LoadSchemaDocument(context.Background(), "schema.json")
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	obj, ok := doc.(map[string]any)
+	if !ok || obj["type"] != "object" {
+		t.Fatalf("unexpected schema document: %#v", doc)
+	}
+}

json_copy.go

@@ -0,0 +1,218 @@
+package scriptorium
+
+import (
+	"encoding/json"
+	"fmt"
+	"math"
+	"reflect"
+	"strconv"
+)
+
+const maxSafeJSONInteger = 1<<53 - 1
+
+type jsonVisit struct {
+	typ reflect.Type
+	ptr uintptr
+}
+
+func copyPublicJSONMap(src map[string]any) (map[string]any, error) {
+	if src == nil {
+		return nil, nil
+	}
+	copied, err := copyPublicJSONValue(reflect.ValueOf(src), "extra_params", make(map[jsonVisit]struct{}))
+	if err != nil {
+		return nil, err
+	}
+	out, ok := copied.(map[string]any)
+	if !ok {
+		return nil, fmt.Errorf("extra_params: expected object")
+	}
+	return out, nil
+}
+
+func copyPublicJSONValue(value reflect.Value, path string, seen map[jsonVisit]struct{}) (any, error) {
+	if !value.IsValid() {
+		return nil, nil
+	}
+	if value.Kind() == reflect.Interface {
+		if value.IsNil() {
+			return nil, nil
+		}
+		return copyPublicJSONValue(value.Elem(), path, seen)
+	}
+	if !value.CanInterface() {
+		return nil, fmt.Errorf("%s: value cannot be copied", path)
+	}
+	if number, ok := value.Interface().(json.Number); ok {
+		f, err := strconv.ParseFloat(number.String(), 64)
+		if err != nil || math.IsNaN(f) || math.IsInf(f, 0) {
+			return nil, fmt.Errorf("%s: invalid JSON number", path)
+		}
+		return number, nil
+	}
+
+	switch value.Kind() {
+	case reflect.Bool, reflect.String:
+		return value.Interface(), nil
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		if value.Int() < -maxSafeJSONInteger || value.Int() > maxSafeJSONInteger {
+			return nil, fmt.Errorf("%s: integer is outside the JSON-safe range", path)
+		}
+		return value.Interface(), nil
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		if value.Uint() > maxSafeJSONInteger {
+			return nil, fmt.Errorf("%s: integer is outside the JSON-safe range", path)
+		}
+		return value.Interface(), nil
+	case reflect.Float32, reflect.Float64:
+		f := value.Convert(reflect.TypeOf(float64(0))).Float()
+		if math.IsNaN(f) || math.IsInf(f, 0) {
+			return nil, fmt.Errorf("%s: floating-point value must be finite", path)
+		}
+		return value.Interface(), nil
+	case reflect.Pointer:
+		if value.IsNil() {
+			return nil, nil
+		}
+		visit := jsonVisit{typ: value.Type(), ptr: value.Pointer()}
+		if _, ok := seen[visit]; ok {
+			return nil, fmt.Errorf("%s: cyclic value is not supported", path)
+		}
+		seen[visit] = struct{}{}
+		defer delete(seen, visit)
+		return copyPublicJSONValue(value.Elem(), path, seen)
+	case reflect.Map:
+		return copyPublicJSONMapValue(value, path, seen)
+	case reflect.Slice:
+		if value.IsNil() {
+			return nil, nil
+		}
+		return copyPublicJSONSequenceValue(value, path, seen)
+	case reflect.Array:
+		return copyPublicJSONSequenceValue(value, path, seen)
+	default:
+		return nil, fmt.Errorf("%s: unsupported JSON value type %s", path, value.Type())
+	}
+}
+
+func copyPublicJSONMapValue(value reflect.Value, path string, seen map[jsonVisit]struct{}) (any, error) {
+	if value.IsNil() {
+		return nil, nil
+	}
+	if value.Type().Key().Kind() != reflect.String {
+		return nil, fmt.Errorf("%s: map key type %s is not supported", path, value.Type().Key())
+	}
+
+	visit := jsonVisit{typ: value.Type(), ptr: value.Pointer()}
+	if _, ok := seen[visit]; ok {
+		return nil, fmt.Errorf("%s: cyclic value is not supported", path)
+	}
+	seen[visit] = struct{}{}
+	defer delete(seen, visit)
+
+	type entry struct {
+		key   reflect.Value
+		name  string
+		value any
+	}
+	entries := make([]entry, 0, value.Len())
+	preserveType := true
+	elemType := value.Type().Elem()
+	iter := value.MapRange()
+	for iter.Next() {
+		key := iter.Key()
+		name := key.String()
+		copied, err := copyPublicJSONValue(iter.Value(), path+"."+name, seen)
+		if err != nil {
+			return nil, err
+		}
+		entries = append(entries, entry{key: key, name: name, value: copied})
+		if copied == nil {
+			if !canAssignNil(elemType) {
+				preserveType = false
+			}
+			continue
+		}
+		if !reflect.TypeOf(copied).AssignableTo(elemType) {
+			preserveType = false
+		}
+	}
+
+	if preserveType {
+		out := reflect.MakeMapWithSize(value.Type(), len(entries))
+		for _, entry := range entries {
+			if entry.value == nil {
+				out.SetMapIndex(entry.key, reflect.Zero(elemType))
+				continue
+			}
+			out.SetMapIndex(entry.key, reflect.ValueOf(entry.value))
+		}
+		return out.Interface(), nil
+	}
+
+	out := make(map[string]any, len(entries))
+	for _, entry := range entries {
+		out[entry.name] = entry.value
+	}
+	return out, nil
+}
+
+func copyPublicJSONSequenceValue(value reflect.Value, path string, seen map[jsonVisit]struct{}) (any, error) {
+	var visit jsonVisit
+	if value.Kind() == reflect.Slice {
+		visit = jsonVisit{typ: value.Type(), ptr: value.Pointer()}
+		if _, ok := seen[visit]; ok {
+			return nil, fmt.Errorf("%s: cyclic value is not supported", path)
+		}
+		seen[visit] = struct{}{}
+		defer delete(seen, visit)
+	}
+
+	values := make([]any, value.Len())
+	preserveType := true
+	elemType := value.Type().Elem()
+	for i := 0; i < value.Len(); i++ {
+		copied, err := copyPublicJSONValue(value.Index(i), fmt.Sprintf("%s[%d]", path, i), seen)
+		if err != nil {
+			return nil, err
+		}
+		values[i] = copied
+		if copied == nil {
+			if !canAssignNil(elemType) {
+				preserveType = false
+			}
+			continue
+		}
+		if !reflect.TypeOf(copied).AssignableTo(elemType) {
+			preserveType = false
+		}
+	}
+
+	if preserveType {
+		out := reflect.New(value.Type()).Elem()
+		if value.Kind() == reflect.Slice {
+			out = reflect.MakeSlice(value.Type(), value.Len(), value.Len())
+		}
+		for i, copied := range values {
+			if copied == nil {
+				out.Index(i).Set(reflect.Zero(elemType))
+				continue
+			}
+			out.Index(i).Set(reflect.ValueOf(copied))
+		}
+		return out.Interface(), nil
+	}
+
+	out := make([]any, len(values))
+	copy(out, values)
+	return out, nil
+}
+
+func canAssignNil(typ reflect.Type) bool {
+	switch typ.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
+		return true
+	default:
+		return false
+	}
+}

llm_adapter.go

@@ -0,0 +1,23 @@
+package scriptorium
+
+import (
+	"context"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+)
+
+type publicLLMClientAdapter struct {
+	client LLMClient
+}
+
+func (a publicLLMClientAdapter) Generate(ctx context.Context, req domain.GenerateRequest) (*domain.GenerateResponse, error) {
+	resp, err := a.client.Generate(ctx, fromDomainGenerateRequest(req))
+	if err != nil {
+		return nil, err
+	}
+	if resp == nil {
+		return nil, fmt.Errorf("%w: llm client returned nil response", ErrLLMGenerate)
+	}
+	return toDomainGenerateResponse(resp), nil
+}

profiles.go

@@ -0,0 +1,124 @@
+package scriptorium
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
+)
+
+// OpenAICompatibleProfile returns an ordinary in-memory Profile for an
+// OpenAI-compatible chat-completions endpoint.
+//
+// It does not register global state, maintain a model catalog, or resolve
+// credentials. If APIKeyRequired is true, callers satisfy it with
+// RunRequest.APIKey. Raw API keys do not belong in profiles.
+func OpenAICompatibleProfile(cfg OpenAICompatibleProfileConfig) Profile {
+	return Profile{
+		ID:              cfg.ID,
+		Endpoint:        cfg.Endpoint,
+		Model:           cfg.Model,
+		Temperature:     cfg.Temperature,
+		MaxTokens:       cfg.MaxTokens,
+		TopP:            cfg.TopP,
+		TimeoutSeconds:  cfg.TimeoutSeconds,
+		ServiceTier:     cfg.ServiceTier,
+		ReasoningEffort: cfg.ReasoningEffort,
+		APIKeyRequired:  cfg.APIKeyRequired,
+		ExtraParams:     copyShallowAnyMap(cfg.ExtraParams),
+	}
+}
+
+func copyShallowAnyMap(src map[string]any) map[string]any {
+	if src == nil {
+		return nil
+	}
+	out := make(map[string]any, len(src))
+	for k, v := range src {
+		out[k] = v
+	}
+	return out
+}
+
+type memoryProfileRepository struct {
+	profiles map[string]domain.ExecutionProfile
+}
+
+func newMemoryProfileRepository(profiles []Profile) (*memoryProfileRepository, error) {
+	repo := &memoryProfileRepository{profiles: make(map[string]domain.ExecutionProfile, len(profiles))}
+	for _, publicProfile := range profiles {
+		prof, err := toDomainProfile(publicProfile)
+		if err != nil {
+			return nil, err
+		}
+		if _, exists := repo.profiles[prof.ID]; exists {
+			return nil, fmt.Errorf("duplicate profile id %q", prof.ID)
+		}
+		repo.profiles[prof.ID] = prof
+	}
+	return repo, nil
+}
+
+func (r *memoryProfileRepository) GetProfile(_ context.Context, id string) (*domain.ExecutionProfile, error) {
+	if r == nil {
+		return nil, profile.ErrProfileNotFound
+	}
+	prof, ok := r.profiles[id]
+	if !ok {
+		return nil, profile.ErrProfileNotFound
+	}
+	prof.ExtraParams = copyAnyMap(prof.ExtraParams)
+	return &prof, nil
+}
+
+func toDomainProfile(publicProfile Profile) (domain.ExecutionProfile, error) {
+	extraParams, err := copyPublicJSONMap(publicProfile.ExtraParams)
+	if err != nil {
+		return domain.ExecutionProfile{}, err
+	}
+	prof := domain.ExecutionProfile{
+		ID:              strings.TrimSpace(publicProfile.ID),
+		Endpoint:        publicProfile.Endpoint,
+		Model:           publicProfile.Model,
+		Temperature:     publicProfile.Temperature,
+		MaxTokens:       publicProfile.MaxTokens,
+		TopP:            publicProfile.TopP,
+		TimeoutSeconds:  publicProfile.TimeoutSeconds,
+		ServiceTier:     publicProfile.ServiceTier,
+		ReasoningEffort: publicProfile.ReasoningEffort,
+		APIKeyRequired:  publicProfile.APIKeyRequired,
+		ExtraParams:     extraParams,
+	}
+	if err := validatePublicProfile(prof); err != nil {
+		return domain.ExecutionProfile{}, err
+	}
+	return prof, nil
+}
+
+func validatePublicProfile(prof domain.ExecutionProfile) error {
+	if strings.TrimSpace(prof.ID) == "" {
+		return errors.New("id is required")
+	}
+	if strings.TrimSpace(prof.Endpoint) == "" {
+		return errors.New("endpoint is required")
+	}
+	if strings.TrimSpace(prof.Model) == "" {
+		return errors.New("model is required")
+	}
+	if prof.Temperature < 0 || prof.Temperature > 2 {
+		return errors.New("temperature must be between 0 and 2")
+	}
+	if prof.MaxTokens < 0 {
+		return errors.New("max_tokens must be greater than or equal to 0")
+	}
+	if prof.TopP < 0 || prof.TopP > 1 {
+		return errors.New("top_p must be between 0 and 1")
+	}
+	if prof.TimeoutSeconds < 0 {
+		return errors.New("timeout_seconds must be greater than or equal to 0")
+	}
+	return nil
+}

testdata/framework/fixtures/glossary.yml

@@ -0,0 +1,2 @@
+archive: A catalogued collection of written records.
+marker: A small label used to classify an entry.

testdata/framework/fixtures/transcript.md

@@ -0,0 +1,2 @@
+Nia labels the archive.
+The archive receives a blue marker.