Prepare documentation for the v0.7.0 release

README.md

@@ -33,10 +33,13 @@ boundary and constraints that framework work must preserve.
 
 ## Release Guidance
 
-Consumers upgrading from `v0.5.0` to `v0.6.0` should read the
+Consumers upgrading from `v0.6.0` to `v0.7.0` should read the
-[v0.6.0 changelog and migration guide](docs/releases/v0.6.0.md).
+[v0.7.0 changelog and migration guide](docs/releases/v0.7.0.md).
 
 Earlier adopters can consult the
+[v0.6.0 changelog and migration guide](docs/releases/v0.6.0.md).
+
+Consumers upgrading from `v0.4.0` to `v0.5.0` can consult the
 [v0.5.0 changelog and migration guide](docs/releases/v0.5.0.md).
 
 Consumers upgrading from `v0.3.0` to `v0.4.0` should read the

backends.go

@@ -9,6 +9,10 @@ import (
 // backend.
 const BackendOpenRouter = backend.OpenRouterID
 
+// BackendRakestrawHome is the reserved ID of Promptkit's built-in
+// Rakestrawhome backend.
+const BackendRakestrawHome = backend.RakestrawHomeID
+
 // BackendLocal is the case-sensitive conventional ID used by [LocalBackend].
 // It is not a built-in or reserved backend and must be registered with
 // [WithBackend].
@@ -20,15 +24,18 @@ const BackendLocal = "local"
 // to this configuration value do not break source compatibility.
 type Backend struct {
 	// ID is the stable, case-sensitive registry key. NewEngine trims it and
-	// requires a non-blank value. BackendOpenRouter is reserved.
+	// requires a non-blank value. Built-in backend IDs are reserved.
 	ID string
 	// Endpoint is the OpenAI-compatible base endpoint. NewEngine trims it and
 	// requires an absolute HTTP or HTTPS URL with a host and without user
 	// information, a query string, or a fragment. Paths are allowed.
 	Endpoint string
-	// APIKeyEnv optionally names the environment variable containing the API
+	// APIKeyEnv optionally names an environment lookup source for an API key.
-	// key. NewEngine trims it and requires the portable form
+	// NewEngine trims it and requires the portable form [A-Za-z_][A-Za-z0-9_]*.
-	// [A-Za-z_][A-Za-z0-9_]*. Store only the name, never a credential value.
+	// A direct RunRequest.APIKey takes precedence. When no usable credential is
+	// available, the built-in client omits Authorization; injected clients own
+	// their own credential-resolution behavior. Store only the name, never a
+	// credential value.
 	APIKeyEnv string
 	// ExtraParams contains backend-wide request defaults. Values must be
 	// JSON-compatible, finite, acyclic, and keyed by non-empty strings. Keys
@@ -74,11 +81,11 @@ func LocalBackend(endpoint string, concurrencyLimit int) Backend {
 //
 // Registrations accumulate in option order. Every normalized ID must be unique
 // across consumer registrations and built-ins; a duplicate or invalid
-// definition makes NewEngine fail with ErrInvalidConfig. In particular,
+// definition makes NewEngine fail with ErrInvalidConfig. Built-in IDs,
-// BackendOpenRouter cannot be replaced. The immutable registration is scoped
+// including [BackendOpenRouter] and [BackendRakestrawHome], cannot be
-// to the resulting Engine and cannot be enumerated, replaced, removed, or
+// replaced. The immutable registration is scoped to the resulting Engine and
-// mutated after construction. WithBackend does not install package-global
+// cannot be enumerated, replaced, removed, or mutated after construction.
-// state.
+// WithBackend does not install package-global state.
 func WithBackend(backend Backend) Option {
 	queueCapacity := 0
 	queueCapacitySet := backend.QueueCapacity != nil

doc.go

@@ -23,8 +23,9 @@
 // InspectProfile return copied inspection values. Returned values and values
 // passed to extension interfaces are likewise isolated from engine state.
 // Callers own those copies and may mutate them after the call that supplied or
-// returned them. Returned structured errors are likewise caller-owned and may
+// returned them. [CapacityError] values are caller-owned and may be mutated
-// be mutated without affecting engine state or another error.
+// without affecting engine state or another error. Immutable [GenerationError]
+// values are also caller-owned and do not retain shared engine state.
 //
 // # Security and sensitive data
 //
@@ -53,9 +54,14 @@
 // Construction, inspection, handle, and error values, including [Config],
 // [Backend], [RunRequest], [ArtifactRef], [ExecutionTargetOverride], [Profile],
 // [OpenAICompatibleProfileConfig], [ProfileInspection],
-// [PromptInputDefinition], [PromptInspection], [PreparedExecution], and
+// [PromptInputDefinition], [PromptInspection], [PreparedExecution],
-// [CapacityError], do not have stable JSON representations. Direct API keys
+// [CapacityError], and [GenerationError], do not have stable JSON
-// are nevertheless excluded from JSON for every public value.
+// representations. Direct API keys are nevertheless excluded from JSON for
+// every public value.
+
+// Provider-derived [GenerationError] accessor values are untrusted and can
+// contain sensitive request or schema fragments. Applications must apply their
+// own disclosure policy before logging, displaying, or returning them.
 //
 // JSON timestamps use time.Time's RFC 3339 encoding and are omitted when zero.
 // PreparedRun and RunResult durations are encoded as integer milliseconds in

docs/consumers/pkg-promptkit.md

@@ -189,6 +189,53 @@ For programmatic profiles,
 [`OpenAICompatibleProfile`](../../profiles.go) converts ordinary
 OpenAI-compatible settings into a value accepted by `WithProfiles`.
 
+### Alias A Built-In Profile
+
+Give an application-owned profile ID a built-in base when prompts should select
+the application ID while inheriting the built-in target. The child can override
+only the setting it owns:
+
+```go
+promptkit.WithProfiles(promptkit.Profile{
+	ID:              "weather-light",
+	BaseProfileID:   "deepseek-4-flash",
+	ReasoningEffort: "high",
+})
+```
+
+Select `weather-light` in a prompt or `RunRequest.ProfileID`; it remains the
+reported selected profile. See the [profile inheritance format
+reference](../formats.md#profile-inheritance) and the
+[`Profile` GoDoc](../../types.go) for exact lookup, merging, and validation
+behavior.
+
+### Use The Rakestrawhome Built-In Profile
+
+Set `RAKESTRAWHOME_INFERENCE_API_KEY` in the application environment, then
+select `rakestrawhome-gemma-4-31b` as an ordinary profile ID. For example, a
+prepared result identifies the selected built-in through
+`BackendRakestrawHome`:
+
+```go
+prepared, err := engine.Prepare(ctx, promptkit.RunRequest{
+	PromptID:  "meeting.summary",
+	ProfileID: "rakestrawhome-gemma-4-31b",
+	Inputs:    inputs,
+})
+if err != nil {
+	return err
+}
+if prepared.SelectedBackendID != promptkit.BackendRakestrawHome {
+	return fmt.Errorf("unexpected backend %q", prepared.SelectedBackendID)
+}
+```
+
+Do not register `rakestrawhome` manually. When adopting this built-in, remove
+an existing `WithBackend` registration with that exact ID; retaining it causes
+the intentional duplicate-ID configuration error. Direct request credentials
+and runtime endpoint overrides remain supported under their ordinary GoDoc and
+format contracts.
+
 ### Inspect A Profile Before Prompt Work
 
 Use [`Engine.InspectProfile`](../../engine.go) to validate one configured
@@ -204,7 +251,7 @@ if err != nil {
 
 target := inspection.EffectiveModelParams
 if target.APIKeyEnv != "" {
-	// Apply application policy for the named environment variable.
+	// This is a configured optional environment lookup source.
 } else if inspection.APIKeyRequired {
 	// Arrange a direct credential before later execution.
 }
@@ -213,9 +260,11 @@ if target.APIKeyEnv != "" {
 Use this configuration-time boundary when only the profile and its target need
 checking. Use `Prepare` when the application also needs prompt, input, schema,
 or rendering work; use prepared execution when that work must remain tied to a
-later execution. Inspection reports credential requirements but leaves the
+later execution. A reported `APIKeyEnv` is a configured optional source, while
-timing of credential enforcement to the application. The method's
+`APIKeyRequired` is the explicit local requirement. The
-[GoDoc](../../engine.go) owns its exact result and error contract.
+[credential format reference](../formats.md#credentials) and the method's
+[GoDoc](../../engine.go) own the exact precedence, timing, result, and error
+contracts.
 
 ### Set A Per-Run Session And Reasoning
 
@@ -423,6 +472,24 @@ status; those choices remain with the consuming application. The
 contract, while the [`Engine.Run` and error GoDoc](../../engine.go) owns broad
 error and cancellation identities.
 
+For a non-2xx response from the built-in OpenAI-compatible client, inspect the
+status and deliberately selected provider diagnostic when useful:
+
+```go
+var generationErr *promptkit.GenerationError
+if errors.As(err, &generationErr) {
+	status := generationErr.StatusCode()
+	message := generationErr.ProviderMessage()
+	_, _ = status, message // Apply application retry and presentation policy.
+}
+```
+
+All provider fields are untrusted and can contain sensitive request or schema
+fragments. Do not log, display, or return them without an application-specific
+disclosure policy. Promptkit does not assign retry or presentation behavior.
+The [`GenerationError` GoDoc](../../generation_error.go) owns the exact typed
+error contract.
+
 ## Application Boundary
 
 Promptkit is an importable library. It does not own a command, inbound HTTP

docs/formats.md

@@ -144,6 +144,17 @@ A request-level `OutputContract` replaces the complete prompt output contract.
 It does not merge individual fields. If its format is empty, Promptkit uses
 `text`.
 
+## Built-In Backends
+
+Every engine provides these reserved OpenAI-compatible backend IDs. Consumers
+must not register either ID with `WithBackend`; exact registration and
+reservation behavior belongs to the [`Backend` GoDoc](../backends.go).
+
+| ID | Base endpoint | API-key environment variable | Active generation limit | Default queue capacity |
+| --- | --- | --- | ---: | ---: |
+| `openrouter` | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` | 16 | 1024 |
+| `rakestrawhome` | `https://inference.ai.rakestrawhome.com/v1` | `RAKESTRAWHOME_INFERENCE_API_KEY` | 4 | 1024 |
+
 ## Profile Definitions
 
 A profile supplies model execution settings:
@@ -162,9 +173,19 @@ extra_params:
   provider_option: enabled
 ```
 
+A derived profile can use a named base and override only the settings it owns:
+
+```yaml
+id: local-summary-fast
+base_profile: local-summary
+timeout_seconds: 30
+reasoning_effort: low
+```
+
 | Field | Required | Meaning |
 | --- | --- | --- |
 | `id` | yes | Profile identifier, trimmed before selection and publication. It must be non-empty after trimming and unique within one source after normalization. |
+| `base_profile` | no | One optional parent profile ID. A derived profile may inherit target fields from it. |
 | `backend` | unless `endpoint` is present | Backend registry ID. It is trimmed and registry membership is checked when the profile is prepared or inspected. |
 | `endpoint` | unless `backend` is present | OpenAI-compatible base URL, including an API version path when required. A nonempty value is trimmed and must be absolute HTTP or HTTPS with a host and without user information, a query, or a fragment. When both connection fields are present, this overrides the backend endpoint without changing backend identity. |
 | `model` | yes | Non-empty provider model name. |
@@ -174,16 +195,21 @@ extra_params:
 | `timeout_seconds` | no | Per-generation deadline in whole seconds; integer zero or greater. |
 | `service_tier` | no | Provider-specific request tier. |
 | `reasoning_effort` | no | Provider-specific reasoning setting. |
-| `api_key_env` | no | Name of an environment variable containing the API key. |
+| `api_key_env` | no | Optional environment-variable lookup source for an API key. |
 | `extra_params` | no | JSON-compatible provider-specific outbound fields. |
 
 Raw `api_key` is prohibited in profile YAML. Store only an environment
 variable name in `api_key_env`.
 
+A standalone profile must provide a model and at least one of `backend` or
+`endpoint`. A derived profile may omit those target fields because its selected
+base chain can provide them. Local parsing still validates a derived profile's
+own ID, supplied endpoint, execution-setting bounds, and `extra_params`.
+
 Promptkit does not infer a backend from a model or endpoint. Endpoint-only
 profiles remain supported and have no effective backend ID.
-The engine always provides the built-in `openrouter` ID. Consumers can add
+The engine always provides the built-in `openrouter` and `rakestrawhome` IDs.
-engine-scoped IDs with
+Consumers can add engine-scoped IDs with
 [`WithBackend`](../backends.go); exact registration validation belongs to its
 GoDoc.
 
@@ -255,41 +281,66 @@ profiles. They use `APIKeyRequired` for request-scoped credentials instead of
 `api_key_env`. Preparation and exact profile inspection use this same source
 precedence.
 
+When a selected definition names `base_profile`, every profile ID in that
+chain is looked up through this same precedence order. A higher-precedence
+definition therefore shadows a lower-precedence definition of the same base
+ID, including a built-in. References are not source-qualified.
+
+### Profile Inheritance
+
+Promptkit resolves one linear base chain of at most 32 profiles, including the
+selected profile. It merges settings from the root base to the selected leaf.
+The leaf's `id` remains the selected profile identity. Nonblank string fields
+(`backend`, `endpoint`, `model`, `service_tier`, `reasoning_effort`, and
+`api_key_env`) and nonzero numeric fields replace inherited values. A nonempty
+`extra_params` map replaces the complete inherited map rather than merging
+keys, and `APIKeyRequired: true` remains true through the chain. Backend and
+endpoint are independent: replacing one does not clear the other.
+
+There is no profile-level clearing syntax. Blank strings, zero numbers, false,
+and empty maps remain unspecified and inherit from a base. Use existing
+presence-aware request overrides where an execution needs an explicit zero or
+empty reasoning setting.
+
+An absent directly selected profile reports the ordinary not-found error. Once
+the selected profile exists, a missing base, cycle, overlong chain, or
+incomplete resolved target is a profile-load failure. Ordinary operations
+resolve chains afresh; prepared execution retains the fully resolved target.
+
 ## Built-In Profile Catalog
 
-Every built-in selects the `openrouter` backend. The engine's built-in backend
+Every built-in profile selects one maintained built-in backend and inherits
-registry supplies `https://openrouter.ai/api/v1` and the environment-variable
+that backend's connection and credential metadata. Profile files do not repeat
-name `OPENROUTER_API_KEY`, so individual profiles contain only model and
+those values. A configured, application fallback, or in-memory profile with
-generation settings. Built-in profile files do not repeat those connection
+the same profile ID takes precedence.
-values. A configured, application fallback, or in-memory profile with the same
-profile ID takes precedence.
 
-| Provider | ID | Model |
+| Provider | ID | Backend | Model |
-| --- | --- | --- |
+| --- | --- | --- | --- |
-| aion-labs | `aion-2` | `aion-labs/aion-2.0` |
+| aion-labs | `aion-2` | `openrouter` | `aion-labs/aion-2.0` |
-| anthropic | `claude-fable-latest` | `~anthropic/claude-fable-latest` |
+| anthropic | `claude-fable-latest` | `openrouter` | `~anthropic/claude-fable-latest` |
-| anthropic | `claude-haiku-latest` | `~anthropic/claude-haiku-latest` |
+| anthropic | `claude-haiku-latest` | `openrouter` | `~anthropic/claude-haiku-latest` |
-| anthropic | `claude-opus-latest` | `~anthropic/claude-opus-latest` |
+| anthropic | `claude-opus-latest` | `openrouter` | `~anthropic/claude-opus-latest` |
-| anthropic | `claude-sonnet-latest` | `~anthropic/claude-sonnet-latest` |
+| anthropic | `claude-sonnet-latest` | `openrouter` | `~anthropic/claude-sonnet-latest` |
-| deepseek | `deepseek-3-2` | `deepseek/deepseek-v3.2` |
+| deepseek | `deepseek-3-2` | `openrouter` | `deepseek/deepseek-v3.2` |
-| deepseek | `deepseek-4-flash` | `deepseek/deepseek-v4-flash` |
+| deepseek | `deepseek-4-flash` | `openrouter` | `deepseek/deepseek-v4-flash` |
-| deepseek | `deepseek-4-pro` | `deepseek/deepseek-v4-pro` |
+| deepseek | `deepseek-4-pro` | `openrouter` | `deepseek/deepseek-v4-pro` |
-| google | `gemini-2-flash` | `google/gemini-2.5-flash` |
+| google | `gemini-2-flash` | `openrouter` | `google/gemini-2.5-flash` |
-| google | `gemini-2-flash-lite` | `google/gemini-2.5-flash-lite` |
+| google | `gemini-2-flash-lite` | `openrouter` | `google/gemini-2.5-flash-lite` |
-| google | `gemini-2-pro` | `google/gemini-2.5-pro` |
+| google | `gemini-2-pro` | `openrouter` | `google/gemini-2.5-pro` |
-| google | `gemini-3-flash-lite` | `google/gemini-3.1-flash-lite` |
+| google | `gemini-3-flash-lite` | `openrouter` | `google/gemini-3.1-flash-lite` |
-| google | `gemini-flash-latest` | `~google/gemini-flash-latest` |
+| google | `gemini-flash-latest` | `openrouter` | `~google/gemini-flash-latest` |
-| google | `gemini-pro-latest` | `~google/gemini-pro-latest` |
+| google | `gemini-pro-latest` | `openrouter` | `~google/gemini-pro-latest` |
-| google | `gemma-4-31b` | `google/gemma-4-31b-it:exacto` |
+| google | `gemma-4-31b` | `openrouter` | `google/gemma-4-31b-it:exacto` |
-| minimax | `minimax-m2` | `minimax/minimax-m2.5` |
+| google | `rakestrawhome-gemma-4-31b` | `rakestrawhome` | `google/gemma-4-31b-it` |
-| minimax | `minimax-m3` | `minimax/minimax-m3` |
+| minimax | `minimax-m2` | `openrouter` | `minimax/minimax-m2.5` |
-| mistral | `mistral-large-2512` | `mistralai/mistral-large-2512` |
+| minimax | `minimax-m3` | `openrouter` | `minimax/minimax-m3` |
-| mistral | `mistral-medium-3-5` | `mistralai/mistral-medium-3-5` |
+| mistral | `mistral-large-2512` | `openrouter` | `mistralai/mistral-large-2512` |
-| mistral | `mistral-small-3` | `mistralai/mistral-small-3.2-24b-instruct` |
+| mistral | `mistral-medium-3-5` | `openrouter` | `mistralai/mistral-medium-3-5` |
-| mistral | `mistral-small-4` | `mistralai/mistral-small-2603` |
+| mistral | `mistral-small-3` | `openrouter` | `mistralai/mistral-small-3.2-24b-instruct` |
-| nvidia | `nemotron-3-ultra` | `nvidia/nemotron-3-ultra-550b-a55b` |
+| mistral | `mistral-small-4` | `openrouter` | `mistralai/mistral-small-2603` |
-| openai | `gpt-5-mini` | `openai/gpt-5.4-mini` |
+| nvidia | `nemotron-3-ultra` | `openrouter` | `nvidia/nemotron-3-ultra-550b-a55b` |
-| openai | `gpt-5-nano` | `openai/gpt-5.4-nano` |
+| openai | `gpt-5-mini` | `openrouter` | `openai/gpt-5.4-mini` |
+| openai | `gpt-5-nano` | `openrouter` | `openai/gpt-5.4-nano` |
 
 ## Schemas
 
@@ -308,16 +359,25 @@ schema produces a failed validation result.
 Credential values belong at the request or environment boundary, never in
 prompt, profile, schema, or example files:
 
-- a file profile names an environment variable with `api_key_env`;
+- a backend or file profile can name an optional environment lookup source
-- an in-memory profile may set `APIKeyRequired`;
+  with `APIKeyEnv` or `api_key_env`;
-- a request can provide a direct `APIKey` or override `APIKeyEnv`; and
+- an in-memory profile may set `APIKeyRequired` as an explicit local
+  requirement;
+- a request can provide a direct `APIKey` or override the optional `APIKeyEnv`
+  source; and
 - a direct request key takes precedence over environment lookup.
 
 After a direct request key, the credential-source precedence is request
 `APIKeyEnv`, profile `api_key_env`, then the backend default. An in-memory
 profile with `APIKeyRequired` clears an inherited backend environment name and
 requires a direct key unless the request explicitly supplies `APIKeyEnv`.
-Promptkit validates required credential availability during preparation.
+Named environment sources are optional: when the selected source is absent,
+empty, or whitespace-only, the built-in client omits the `Authorization`
+header and handles the provider response normally. `APIKeyRequired` is the
+only explicit local availability requirement. Promptkit validates required
+credential availability during preparation and rechecks it when a prepared
+execution runs. Injected clients receive resolved source metadata but define
+their own credential-resolution behavior.
 Direct keys are excluded from JSON results and redacted by public string
 formatters. Environment-variable names may appear in prepared metadata, but
 their values do not.

docs/integrations/openai-compatible-chat.md

@@ -31,11 +31,13 @@ does not serialize it in the provider request.
 
 ## Authentication
 
-A non-empty API key supplied directly on the execution target takes
+A usable API key supplied directly on the execution target takes precedence.
-precedence. Otherwise, when an API-key environment-variable name is supplied,
+Otherwise, when an API-key environment-variable name is supplied, the client
-the client reads that variable and requires a non-empty value. The selected
+reads and trims that variable. A bearer header is sent only when the resolved
-key is sent as `Authorization: Bearer <key>`. No authorization header is sent
+direct or environment credential is non-empty. When neither source is usable,
-when neither mechanism is configured.
+the client omits `Authorization` and handles the provider response normally.
+An explicitly required target with no usable source is rejected before
+transport.
 
 The target contains the already resolved environment-variable name: an
 explicit request override takes precedence over profile metadata, which takes
@@ -102,10 +104,26 @@ and cache-write token counts. Invalid or truncated JSON, trailing non-whitespace
 data, a second JSON value, absent choices, empty first-choice content, and size
 overflow are malformed responses and return no partial result.
 
-For a non-2xx status, the error includes the status code but never the provider
+For a non-2xx status, Promptkit recognizes one JSON document with a top-level
-response body. Promptkit does not yet parse provider error envelopes; bounded
+object-valued `error` member. Its optional `message` and `type` fields must be
-non-success parsing belongs to the
+strings, and `code` may be a string or JSON number. Valid supported fields are
-[structured-generation-error roadmap](../roadmap/structured-generation-errors.md).
+handled independently, numeric codes retain their JSON number text, and
+unknown fields are ignored. Missing, invalid, malformed, or multiply framed
+envelopes contribute no provider detail.
+
+Non-success bodies have a 65,536-byte limit. A larger declared
+`Content-Length` is not read; otherwise the client reads at most one additional
+byte to detect streamed or underreported overflow. Empty, unreadable,
+oversized, malformed, and unrecognized bodies retain only the received status.
+The body is always closed and no oversized stream is drained beyond that probe.
+
+Extracted strings are made valid UTF-8, trimmed, and converted to one line by
+collapsing Unicode whitespace, control, and format-character runs. Blank
+values are omitted. Codes and types longer than 256 Unicode code points are
+omitted; messages longer than 4,096 code points are truncated at a code-point
+boundary with an ellipsis inside the limit. Promptkit never exposes raw bodies,
+headers, endpoints, credentials, request data, schemas, generated content, or
+unsupported provider metadata through this handling.
 
 An outbound `http.Client.Do` failure retains both Promptkit's request-failure
 identity and the exact transport error for `errors.Is` and `errors.As` checks.

docs/internal/llm.md

@@ -37,8 +37,9 @@ resolved request target may supply the endpoint. Generation then:
 4. composes `/chat/completions` through parsed URL path operations;
 5. resolves authentication;
 6. performs the outbound request under the applicable deadlines; and
-7. decodes one strictly framed, size-bounded response object and maps its first
+7. decodes one strictly framed, size-bounded successful response object and
-   choice and token usage.
+   maps its first choice and token usage, or decodes bounded structured
+   non-success detail.
 
 `internal/llm` owns the set of reserved OpenAI-compatible request fields used
 when validating extra parameters. Backend registration consumes the same rule
@@ -54,12 +55,14 @@ the target, rendered messages, and structured-output constraint retained by
 executable preparation. Execution does not reopen or rerender consumer
 sources.
 
-Before backend admission, the runner rechecks that the frozen credential
+Before backend admission, the runner rechecks a frozen credential
-environment-variable name is available. The handle does not retain the
+environment-variable name only when the target explicitly requires a
-environment value; the model client resolves the value visible when generation
+credential. The handle does not retain the environment value; the model client
-begins. A direct request key remains in private execution state only until the
+resolves the value visible when generation begins. For optional sources with no
-claimed execution finishes or an unclaimed handle is discarded. Exact public
+usable value, the built-in client omits `Authorization` and continues to the
-ownership and redaction semantics belong to the
+provider. A direct request key remains in private execution state only until
+the claimed execution finishes or an unclaimed handle is discarded. Exact
+public ownership and redaction semantics belong to the
 [`PreparedExecution` GoDoc](../../prepared_execution.go).
 
 ## Failure Categories
@@ -67,21 +70,32 @@ ownership and redaction semantics belong to the
 The package preserves distinct error identities for invalid client
 configuration, invalid generation requests, request execution failures,
 non-success provider statuses, and malformed successful responses. Provider
-response bodies are not included in non-success errors.
+response bodies are never exposed in raw form through non-success errors.
 
 Invalid nonempty configured endpoints are configuration failures. A missing or
 invalid final selected endpoint is an invalid generation request and is
 rejected before transport.
 
+Authentication resolves a trimmed direct key before a trimmed configured
+environment value. Optional missing, empty, or whitespace-only sources do not
+block transport and produce no `Authorization` header. An explicitly required
+target with no usable source is rejected before transport with the existing
+invalid-request diagnostics.
+
 Successful response bodies have a fixed 16 MiB limit enforced by declared
 length and by reading at most one byte beyond the boundary. The decoder accepts
 exactly one JSON object plus trailing whitespace and EOF. Size overflow,
 truncation, malformed JSON, trailing data, and a second value are malformed
 responses with no partial result or provider content in the error. Every body
-is closed, and an unbounded oversized stream is not drained. Non-success
+is closed, and an unbounded oversized stream is not drained.
-responses remain status-only; bounded provider error-envelope parsing belongs
+
-to the
+For a non-success response, `ProviderHTTPError` retains the HTTP status and
-[structured-generation-error roadmap](../roadmap/structured-generation-errors.md).
+only normalized detail from the bounded recognized envelope. It retains
+`ErrUnexpectedStatus` through unwrapping. The client owns response closure;
+its bounded reader and parser never close or drain a body themselves. The root
+facade converts this concrete internal error into the public
+[`GenerationError`](../../generation_error.go), while arbitrary injected-client
+errors continue through the ordinary generation-error mapping unchanged.
 
 An `http.Client.Do` failure is represented by a redacting multi-cause error:
 the package request-failure sentinel and the exact returned transport error are
@@ -99,10 +113,14 @@ The
 own configuration, client cloning, deterministic deadline precedence,
 authentication, request and response mapping, malformed data, error identity,
 cancellation, endpoint selection and composition, pre-transport rejection, and
-bounded single-document response framing, closure, and response-body
+bounded single-document successful-response framing, closure, and
-suppression. The root
+response-body suppression. The focused
-transport contract tests also verify that resolved backend settings reach this
+[provider HTTP error tests](../../internal/llm/provider_http_error_test.go)
-client without serializing backend identity and that ordinary-run cancellation
+own envelope parsing, normalization, and bounded-reader cases; their
-retains its public generation and context identities. All use local test
+[transport tests](../../internal/llm/provider_http_error_transport_test.go)
-servers or controlled test transports; the default suite makes no live or paid
+own non-success response closure and integration. Root transport contract tests
-provider requests.
+own public `GenerationError` conversion, while also verifying that resolved
+backend settings reach this client without serializing backend identity and
+that ordinary-run cancellation retains its public generation and context
+identities. All use local test servers or controlled test transports; the
+default suite makes no live or paid provider requests.

docs/internal/overview.md

@@ -11,22 +11,22 @@ contributor workflow and validation.
 
 | Component | Implemented responsibility | References |
 | --- | --- | --- |
-| Root `promptkit` package | Provides the supported engine facade, source, backend-registration, and injection options, public request, result, prompt-inspection, and profile-inspection values, opaque prepared-execution handles, profile construction, extension interfaces, value conversion, redacted formatting, typed capacity errors, public error mapping, and engine-local profile-source assembly including application fallbacks. | [Package GoDoc](../../doc.go), [prepared execution](../../prepared_execution.go), [backend API](../../backends.go), [engine assembly](../../engine.go) |
+| Root `promptkit` package | Provides the supported engine facade, source, backend-registration, and injection options, public request, result, prompt-inspection, and profile-inspection values, opaque prepared-execution handles, profile construction, extension interfaces, value conversion, redacted formatting, typed capacity and generation error mapping, and engine-local profile-source assembly including application fallbacks. | [Package GoDoc](../../doc.go), [prepared execution](../../prepared_execution.go), [backend API](../../backends.go), [engine assembly](../../engine.go) |
 | `examples/go-library/prepare` | Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, and `Prepare`. It is not a public library package. | [Example program](../../examples/go-library/prepare/main.go) |
 | `examples/go-library/run` | Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, an injected deterministic model client, and `Run`. It is not a public library package. | [Example program](../../examples/go-library/run/main.go) |
-| `internal/backend` | Constructs each engine's immutable registry from the built-in OpenRouter definition and consumer additions, validates and defensively copies definitions through the shared JSON-value package, and consumes the LLM-owned OpenAI-compatible reserved request-field rule. | [Backend registry](../../internal/backend/registry.go) |
+| `internal/backend` | Constructs each engine's immutable registry from the maintained built-in definitions and consumer additions, validates and defensively copies definitions through the shared JSON-value package, and consumes the LLM-owned OpenAI-compatible reserved request-field rule. | [Backend registry](../../internal/backend/registry.go) |
 | `internal/capacity` | Owns engine-local bounded execution admission and FIFO model-generation permits for limited backend IDs, including cancellation-safe waiter removal and client wrapping. | [Internal capacity management](capacity.md) |
 | `internal/domain` | Defines internal framework values for requests, artifacts, prompt definitions, profiles, execution targets, rendering, generation, and validation, and owns source-neutral invariants for shared execution settings, OpenAI-compatible base endpoints, session identifiers, and output contracts. Source parsing, required fields, other source-specific normalization, defaulting, and boundary-specific error classification remain with their callers. | [Domain declarations](../../internal/domain/domain.go), [endpoint invariant](../../internal/domain/endpoint.go) |
 | `internal/defaults` | Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits. | [Framework defaults](../../internal/defaults/defaults.go) |
 | `internal/filecatalog` | Provides deterministic YAML discovery and path helpers for operating-system filesystems and `fs.FS` sources. | [File catalog](../../internal/filecatalog/catalog.go) |
 | `internal/jsonvalue` | Validates and deeply copies bounded JSON-compatible extra-parameter and prepared-schema trees while preserving supported concrete value types and rejecting cycles or excessive depth and work. | [JSON values](../../internal/jsonvalue/jsonvalue.go) |
 | `internal/promptdef` | Loads strictly decoded, validated prompt definitions from filesystem and `fs.FS` sources, including version selection and contained file-backed message content. | [Framework formats](../formats.md), [prompt-definition repository](../../internal/promptdef/filesystem_repository.go) |
-| `internal/profile` | Loads strictly decoded, validated execution profiles, including backend selection, from filesystem and `fs.FS` sources and composes repositories with error-preserving fallback. | [Framework formats](../formats.md), [profile repositories](../../internal/profile/filesystem_repository.go) |
+| `internal/profile` | Loads strictly decoded, locally validated execution profiles from filesystem and `fs.FS` sources, overlays raw sources with error-preserving fallback, and resolves inherited profiles. | [Framework formats](../formats.md), [profile repositories](../../internal/profile/filesystem_repository.go), [internal sources](sources.md#profiles-and-built-ins) |
-| `internal/profile/builtin` | Embeds the built-in profile catalog, whose entries select OpenRouter. | [Built-in catalog](../formats.md#built-in-profile-catalog), [repository](../../internal/profile/builtin/repository.go) |
+| `internal/profile/builtin` | Embeds the built-in profile catalog, whose entries select maintained built-in backends. | [Built-in catalog](../formats.md#built-in-profile-catalog), [repository](../../internal/profile/builtin/repository.go) |
 | `internal/prompt` | Renders prompt messages from Go templates with artifact, variable, session, and cache-control data. | [Go-template renderer](../../internal/prompt/go_renderer.go) |
 | `internal/artifact` | Resolves ordinary inline and unrestricted caller-selected file references into copied artifacts with metadata and hashes. | [Internal sources and validation](sources.md) |
 | `internal/validate` | Validates basic, JSON, and JSON Schema output using operating-system filesystem or `fs.FS` schema sources and creates operation-local validation plans with canonical contained schema resources. | [Framework formats](../formats.md#schemas), [internal sources and validation](sources.md) |
-| `internal/llm` | Defines the internal generation boundary and implements outbound OpenAI-compatible chat requests from resolved execution targets, including response decoding, authentication, deadline handling, and ownership of the OpenAI-compatible reserved request-field policy. | [Internal model client](llm.md) |
+| `internal/llm` | Defines the internal generation boundary and implements outbound OpenAI-compatible chat requests from resolved execution targets, including bounded structured non-success response decoding, successful-response decoding, authentication, deadline handling, and ownership of the OpenAI-compatible reserved request-field policy. | [Internal model client](llm.md) |
 | `internal/usecase` | Resolves prompt definitions and hashes, profiles, backends, and targets for exact inspection and request settings for preparation, and coordinates ordinary execution and one-attempt prepared execution across internal sources, rendering, artifact loading, operation-local validation plans, generation, capacity, and optional repair. | [Internal runner](runner.md), [prepared-execution implementation](../../internal/usecase/prepared_execution.go) |
 
 The root package assembles these internal components without exposing their

docs/internal/sources.md

@@ -39,17 +39,17 @@ duplicate detection, and source containment:
 
 ## Profiles And Built-Ins
 
-`internal/profile` loads and validates execution profiles from an
+`internal/profile` loads, locally validates, overlays, and resolves execution
-operating-system filesystem or an `fs.FS`. A file contains exactly one YAML
+profiles from an operating-system filesystem or an `fs.FS`. A file contains
-document and its trimmed YAML `id` is its only selection identity; filenames do
+exactly one YAML document and its trimmed YAML `id` is its only selection
-not confer authority. Each point lookup reads discovered files once for their
+identity; filenames do not confer authority. Each point lookup reads discovered
-metadata and reuses the selected file's bytes for strict decoding; unrelated
+files once for their metadata and reuses the selected file's bytes for strict
-profiles are not fully decoded. Strict selected decoding recognizes the
+decoding; unrelated profiles are not fully decoded. Strict selected decoding
-optional `backend` field, trims its value, and requires a model plus at least
+recognizes `base_profile` and the optional `backend` field, trims their values,
-one non-blank backend or endpoint. File-backed `extra_params` values are
+and permits inherited target fields only when a base is named. File-backed
-validated and defensively copied through the shared bounded JSON-value owner
+`extra_params` values are validated and defensively copied through the shared
-before a profile is published. OpenAI-compatible reserved-field policy remains
+bounded JSON-value owner before a profile is published. OpenAI-compatible
-with the model-client and backend-registry owners.
+reserved-field policy remains with the model-client and backend-registry owners.
 
 The overlay repository consults the next repository only when the
 higher-precedence repository reports that a profile is absent. A reliably
@@ -59,22 +59,34 @@ backend registry membership because the available registry belongs to the
 assembled engine; the runner checks membership during preparation and exact
 profile inspection.
 
-The root engine assembles profile repositories in precedence order: in-memory
+The root engine assembles one raw composite catalog in precedence order:
-profiles, one ordinary configured source, an application fallback source, then
+in-memory profiles, one ordinary configured source, an application fallback
-the embedded built-in catalog. An explicit file or `fs.FS` profile source
+source, then the embedded built-in catalog. An explicit file or `fs.FS` profile
-replaces `Config.ProfileDir` within the ordinary configured-source category.
+source replaces `Config.ProfileDir` within the ordinary configured-source
+category. One outer resolving repository wraps that complete raw catalog, so
+each base lookup observes the same precedence and shadowing rules.
 
-Exact profile inspection performs one point-in-time lookup through those
+The resolving repository traverses every selected chain afresh, retains no
-profile sources and checks the resolved target without reading prompt, input,
+cache, detects cycles, limits a chain to 32 profiles, merges root-to-leaf into a
+new caller-owned value, and validates the final target before publishing it. It
+does not check backend registry membership. Exact `base_profile` syntax, merge
+rules, and consumer-visible failure behavior belong to the [framework format
+reference](../formats.md#profile-inheritance).
+
+Exact profile inspection performs one point-in-time resolved lookup through
+those profile sources and checks the final target without reading prompt, input,
 or schema sources. It does not retain that lookup for a later execution.
+Prepared execution instead freezes the fully resolved target; a later ordinary
+operation performs a fresh traversal.
 
 `internal/profile/builtin` embeds the maintained built-in profile catalog.
-Every embedded profile selects `openrouter` and inherits its endpoint and
+Every embedded profile selects a maintained built-in backend and inherits that
-credential environment-variable name from the built-in backend registry rather
+backend's endpoint and credential environment-variable name from the built-in
-than repeating those values. Profile loading and overlay behavior are owned by
+backend registry rather than repeating those values. Profile loading and
-the [profile repository tests](../../internal/profile/repository_test.go),
+overlay behavior are owned by the
-while catalog completeness, the backend-selection invariant, and duplicate IDs
+[profile repository tests](../../internal/profile/repository_test.go), while
-are owned by the
+catalog completeness, the backend-selection invariant, and duplicate IDs are
+owned by the
 [built-in repository tests](../../internal/profile/builtin/repository_test.go).
 
 ## Ordinary Artifacts

docs/policy/architecture.md

@@ -22,7 +22,7 @@ The implemented internal components consist of:
 - `internal/domain`, which owns framework data values and source-neutral
   invariants shared by later internal components;
 - `internal/backend`, which owns validated immutable OpenAI-compatible backend
-  definitions and the built-in OpenRouter definition;
+  definitions and the maintained built-in definitions;
 - `internal/capacity`, which owns engine-local bounded run admission and
   model-generation scheduling for limited backends;
 - `internal/defaults`, which owns application-neutral framework defaults and

docs/releases/v0.7.0.md

@@ -0,0 +1,155 @@
+# Promptkit v0.7.0
+
+This supplemental changelog and migration guide summarizes the consumer-facing
+changes from `v0.6.0` to `v0.7.0`. The annotated `v0.7.0` tag is the
+authoritative release record. Exact current contracts belong to the linked
+GoDoc and durable documentation.
+
+## Summary
+
+`v0.7.0` expands provider integration and profile composition while making
+credential and generation-failure handling more flexible:
+
+- Promptkit now includes the `rakestrawhome` backend and its Gemma profile;
+- built-in generation failures expose bounded structured provider details;
+- an unavailable optional API-key environment source no longer prevents a
+  request from reaching an upstream that permits unauthenticated access; and
+- profiles can inherit from and selectively refine another profile.
+
+## Compatibility
+
+This release adds public declarations and fields but removes none. Existing
+keyed configuration literals and ordinary `errors.Is` handling continue to
+work.
+
+Adding `BaseProfileID` to `Profile` and `OpenAICompatibleProfileConfig` changes
+their struct shape. Consumers using positional composite literals for either
+type must convert them to keyed literals. Existing keyed literals require no
+change.
+
+The `rakestrawhome` backend ID is now built in and reserved. A consumer that
+previously registered that exact ID with `WithBackend` must remove its manual
+registration before upgrading. Other custom backend registrations are
+unchanged.
+
+When an optional backend, profile, or request `APIKeyEnv` is unset, empty, or
+whitespace-only, the built-in client now omits `Authorization` and sends the
+request. Previously this condition could fail before transport. Set
+`Profile.APIKeyRequired` when missing credentials must remain a local
+preflight error.
+
+Provider non-success responses continue to match `ErrLLMGenerate`. Their
+rendered wording is not a compatibility contract; consumers can now use
+`errors.As` with `*GenerationError` when structured status information is
+needed.
+
+## Upgrade
+
+Update the module dependency with:
+
+```sh
+go get gitea.maximumdirect.net/eric/promptkit@v0.7.0
+go mod tidy
+```
+
+Remove any manual `rakestrawhome` backend registration, convert positional
+profile literals to keyed literals, and run the consuming project's ordinary
+and race-enabled tests.
+
+## Rakestrawhome Built-In Backend And Profile
+
+Every engine now includes the reserved `rakestrawhome` backend, identified by
+`BackendRakestrawHome`. The built-in `rakestrawhome-gemma-4-31b` profile
+selects that backend. Consumers can use the maintained endpoint, credential,
+capacity, and model defaults without registering either definition themselves.
+
+See the [built-in backend and profile catalogs](../formats.md#built-in-backends)
+and the [consumer adoption example](../consumers/pkg-promptkit.md#use-the-rakestrawhome-built-in-profile)
+for the current contracts.
+
+## Structured Generation Errors
+
+Non-2xx responses from the built-in OpenAI-compatible client now return an
+immutable `*GenerationError`. Consumers can inspect the HTTP status and any
+safely extracted provider code, type, or message while retaining the ordinary
+generation-error category:
+
+```go
+var generationErr *promptkit.GenerationError
+if errors.As(err, &generationErr) {
+	status := generationErr.StatusCode()
+	_ = status
+}
+```
+
+Provider fields are bounded and normalized but remain untrusted and may
+contain sensitive request or schema details. Default and Go-syntax formatting
+omit those fields. Applications must apply their own disclosure policy before
+logging or presenting accessor values.
+
+See the [`GenerationError` GoDoc](../../generation_error.go), the
+[consumer error-handling guide](../consumers/pkg-promptkit.md#handle-errors),
+and the [OpenAI-compatible response contract](../integrations/openai-compatible-chat.md#response-handling).
+
+## Optional Credential Sources
+
+`APIKeyEnv` names an optional environment lookup source unless the selected
+profile explicitly sets `APIKeyRequired`. When neither a direct request key nor
+a usable environment value exists, the built-in client omits the bearer header
+and handles the upstream response normally. This supports local and other
+OpenAI-compatible providers that permit unauthenticated requests without
+hiding an authentication error returned by a provider that requires one.
+
+The [credential format reference](../formats.md#credentials), the
+[`Backend` GoDoc](../../backends.go), the
+[`ExecutionTargetOverride` GoDoc](../../types.go), and the
+[authentication integration contract](../integrations/openai-compatible-chat.md#authentication)
+define the current precedence and availability rules.
+
+## Profile Inheritance
+
+YAML profiles can name one parent with `base_profile`; in-memory profiles use
+`Profile.BaseProfileID`, and `OpenAICompatibleProfileConfig` forwards the same
+field. A profile can act as an application-owned alias of a built-in or refine
+selected inherited settings:
+
+```go
+promptkit.WithProfiles(promptkit.Profile{
+	ID:              "weather-light",
+	BaseProfileID:   "deepseek-4-flash",
+	ReasoningEffort: "high",
+})
+```
+
+Base lookup observes the existing source precedence. Chains are linear,
+cycle-safe, and resolved afresh for ordinary operations. Prepared execution
+freezes the fully resolved target. The selected leaf ID remains public while
+effective execution settings reflect the resolved chain.
+
+See the [profile inheritance format reference](../formats.md#profile-inheritance),
+the [consumer alias example](../consumers/pkg-promptkit.md#alias-a-built-in-profile),
+and the [`Profile` GoDoc](../../types.go) for exact merge and validation
+behavior.
+
+## Public API Changes
+
+The release adds:
+
+- `BackendRakestrawHome`;
+- `GenerationError`, including `StatusCode`, `ProviderCode`, `ProviderType`,
+  `ProviderMessage`, `Error`, `GoString`, and `Unwrap`;
+- `Profile.BaseProfileID`; and
+- `OpenAICompatibleProfileConfig.BaseProfileID`.
+
+No public declaration was removed.
+
+## Consumer Action
+
+- Remove a manual backend registration whose ID is exactly `rakestrawhome`.
+- Convert positional `Profile` or `OpenAICompatibleProfileConfig` literals to
+  keyed literals.
+- Set `Profile.APIKeyRequired` where a missing credential must fail locally
+  instead of reaching the provider unauthenticated.
+- Treat `GenerationError` provider fields as untrusted and potentially
+  sensitive when adopting the new accessors.
+- Run consumer ordinary and race-enabled tests after updating the module.

docs/roadmap/future.md

@@ -40,12 +40,11 @@ consumers.
 
 ### Public bounded output repair
 
-After the codebase-audit remediations are complete, Promptkit should make its
+Promptkit should make its bounded output-repair capability available through
-bounded output-repair capability available through the public engine. A
+the public engine. A consumer should be able to request a limited number of
-consumer should be able to request a limited number of corrective generation
+corrective generation attempts when JSON or JSON Schema output fails content
-attempts when JSON or JSON Schema output fails content validation, without
+validation, without having to reproduce Promptkit's generation, validation,
-having to reproduce Promptkit's generation, validation, capacity, and result-
+capacity, and result-accounting orchestration.
-accounting orchestration.
 
 - Repair is validation recovery, not a general provider retry, failover, or
   backoff policy. Transport failures, cancellation, and operational schema or
@@ -62,10 +61,6 @@ accounting orchestration.
 - Ordinary and prepared execution should expose coherent behavior, including
   cancellation, frozen prepared state, error identity, and capacity lifetime.
 
-Select this work only after the accepted audit findings affecting shared
-execution invariants, validation, orchestration, transport, and repair
-internals have been remediated.
-
 ## Entry Format
 
 Use a short heading followed by a concise summary. Add focused bullets when

docs/roadmap/structured-generation-errors.md

@@ -1,71 +0,0 @@
-# Structured Generation Errors
-
-## Purpose
-
-Promptkit should give downstream applications actionable, machine-readable
-details when the built-in OpenAI-compatible client receives a non-success HTTP
-response. Today the client reports only the status code and discards the
-provider response body. This makes ordinary configuration failures—such as an
-unsupported strict JSON Schema keyword—unnecessarily difficult to diagnose.
-
-## Target End State
-
-Failures from the built-in transport are available through a public typed error
-that works with `errors.As` while continuing to match `ErrLLMGenerate` through
-`errors.Is`. The error should expose:
-
-- the HTTP status code;
-- a normalized provider error code or type when supplied; and
-- a bounded provider message extracted from a recognized OpenAI-compatible
-  JSON error envelope.
-
-The ordinary `Error()` string should remain safe and concise: it should include
-the status and provider code or type, but not automatically include the
-provider message. Consumers that deliberately want the provider's diagnostic
-text can retrieve it from the typed error and apply their own disclosure and
-logging policy.
-
-This contract should be available for both ordinary and prepared execution.
-Errors returned by injected model clients must continue to preserve their own
-identity and should not be converted into fabricated HTTP details.
-
-## Safety And Compatibility Boundaries
-
-- Never expose the raw response body, response headers, endpoint, credentials,
-  request messages, schema document, or generated content through this API.
-- Read only a small fixed maximum response body, reject malformed or
-  unrecognized envelopes, normalize invalid UTF-8 and control characters, and
-  cap every retained diagnostic field independently.
-- Treat the extracted provider message as untrusted and potentially sensitive:
-  its GoDoc must tell consumers not to log or display it without applying their
-  own policy.
-- Preserve the existing generic behavior when a response is empty, non-JSON,
-  oversized, or does not match a recognized error envelope.
-- Do not assign retryability from an HTTP status. Promptkit supplies facts;
-  downstream applications retain retry and presentation policy.
-
-## Recommended API Direction
-
-Prefer one immutable public `GenerationError` value, constructed internally and
-carrying accessors for HTTP status, provider code or type, and provider message.
-This keeps the exact representation evolvable while giving consumers an
-idiomatic `errors.As` contract. Public Go declarations and GoDoc should own the
-final exact names and semantics.
-
-The internal OpenAI-compatible client should parse only the conventional
-top-level `error` envelope and pass normalized details through the use-case and
-public error-mapping layers. The integration documentation should continue to
-own wire behavior; the public declarations should own the consumer contract.
-
-## Acceptance Criteria
-
-- A downstream consumer can distinguish a provider HTTP 400 from other
-  generation failures and obtain a bounded provider explanation when present.
-- The typed error still satisfies `errors.Is(err, ErrLLMGenerate)`.
-- Existing cancellation, capacity, validation, and injected-client error
-  identities remain unchanged.
-- Tests cover recognized string and numeric provider codes, absent and malformed
-  envelopes, oversized bodies and fields, control characters, and error-chain
-  behavior without making live provider requests.
-- Current-state GoDoc and the OpenAI-compatible integration and internal-client
-  documents are updated only when the implementation lands.

engine.go

@@ -53,9 +53,9 @@ var (
 	// an execution profile or resolve its backend, except for the profile
 	// not-found case represented by ErrProfileNotFound.
 	ErrProfileLoad = errors.New("failed to load execution profile")
-	// ErrAPIKeyEnvMissing identifies an APIKeyEnv whose environment variable is
+	// ErrAPIKeyEnvMissing identifies an explicitly required APIKeyEnv whose
-	// unset or empty when no direct RunRequest.APIKey takes precedence. Such an
+	// environment variable is unset or empty after direct RunRequest.APIKey
-	// error also matches ErrInvalidRequest.
+	// precedence is applied. Such an error also matches ErrInvalidRequest.
 	ErrAPIKeyEnvMissing = errors.New("api_key_env points to an unset environment variable")
 	// ErrArtifactLoad identifies a failure to resolve an input artifact. Errors
 	// returned by an injected ArtifactReader remain available through errors.Is.
@@ -69,8 +69,9 @@ var (
 	// request, an LLM or provider rate-limit response, or ErrLLMGenerate.
 	ErrCapacityExceeded = errors.New("backend capacity exceeded")
 	// ErrLLMGenerate identifies a model-client failure or a nil successful
-	// response. Errors returned by an injected LLMClient remain available
+	// response. A built-in OpenAI-compatible non-2xx response is available as a
-	// through errors.Is.
+	// [GenerationError]. Errors returned by an injected LLMClient remain
+	// available through errors.Is.
 	ErrLLMGenerate = errors.New("failed to generate output")
 	// ErrValidation identifies an operational failure to load or compile a
 	// schema or validate output. A completed validation whose Status is
@@ -303,10 +304,12 @@ func WithFallbackProfileFS(fsys fs.FS, root string) Option {
 // WithProfiles configures in-memory profiles that take precedence over
 // ordinary configured, application fallback, and built-in profiles.
 //
-// NewEngine validates and copies every profile. IDs must be unique within one
+// NewEngine locally validates and copies every profile. IDs must be unique
-// call. An invalid profile, duplicate ID, or unsupported ExtraParams value
+// within one call. An invalid local definition, duplicate ID, or unsupported
-// makes construction fail with ErrInvalidConfig. Repeating WithProfiles
+// ExtraParams value makes construction fail with ErrInvalidConfig. A derived
-// replaces the complete earlier in-memory set rather than merging it.
+// profile's base reference and resolved target completeness are checked when it
+// is selected or inspected. Repeating WithProfiles replaces the complete
+// earlier in-memory set rather than merging it.
 func WithProfiles(profiles ...Profile) Option {
 	return optionFunc(func(options *engineOptions) error {
 		repo, err := newMemoryProfileRepository(profiles)
@@ -457,7 +460,7 @@ func newProfileRepository(profileDir string, options engineOptions) profile.Repo
 		repository = profile.NewOverlayRepository(options.memoryProfiles, repository)
 	}
 
-	return repository
+	return profile.NewResolvingRepository(repository)
 }
 
 func fileSource(name string) (fs.FS, string, error) {
@@ -646,11 +649,13 @@ func (e *Engine) PrepareExecution(ctx context.Context, req RunRequest) (*Prepare
 // discoverable as [CapacityError] and still matches ErrCapacityExceeded. It
 // occurs before artifacts, schemas, rendering, or model generation because the
 // selected backend's admission capacity is full; it does not match
-// ErrInvalidRequest or ErrLLMGenerate. Errors from injected clients remain
+// ErrInvalidRequest or ErrLLMGenerate. A built-in OpenAI-compatible non-2xx
-// available through errors.Is. Cancellation while waiting for model-generation
+// response is discoverable as [GenerationError]. Errors from injected clients
-// capacity matches both ErrLLMGenerate and the context error. Cancellation
+// remain available through errors.Is. Cancellation while waiting for
-// otherwise follows the active collaborator's documented behavior. A nil
+// model-generation capacity matches both ErrLLMGenerate and the context error.
-// Engine returns ErrInvalidConfig. Run returns no partial result on error.
+// Cancellation otherwise follows the active collaborator's documented
+// behavior. A nil Engine returns ErrInvalidConfig. Run returns no partial
+// result on error.
 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)
@@ -688,9 +693,10 @@ func (e *Engine) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
 // ErrCapacityExceeded, ErrLLMGenerate, or ErrValidation as applicable while
 // preserving documented collaborator and context identities. An engine
 // admission rejection is discoverable as [CapacityError] and still matches
-// ErrCapacityExceeded. A completed content-validation rejection is returned
+// ErrCapacityExceeded. A built-in OpenAI-compatible non-2xx response is
-// in RunResult, not as an operational error. An operational error returns no
+// discoverable as [GenerationError]. A completed content-validation rejection
-// partial RunResult.
+// is returned in RunResult, not as an operational error. An operational error
+// returns no partial RunResult.
 func (e *Engine) RunPrepared(ctx context.Context, prepared *PreparedExecution) (*RunResult, error) {
 	if e == nil || e.runner == nil {
 		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)

engine_test.go

@@ -977,37 +977,72 @@ func TestPrepareDirectAPIKeyBypassesMissingEnvWithoutLeakingOrHashing(t *testing
 	}
 }
 
-func TestMissingCredentialsFailClearlyWhenProfileRequiresAuth(t *testing.T) {
+func TestOptionalMissingCredentialsReachUpstream(t *testing.T) {
 	const missingEnv = "PROMPTKIT_PUBLIC_AUTH_MISSING"
+	const providerBody = `{"error":{"message":"authentication failed","type":"authentication_error","code":"invalid_api_key"}}`
 	t.Setenv(missingEnv, "")
 
-	profileDir := t.TempDir()
+	called := false
-	writePublicProfileFileWithAPIKeyEnv(t, profileDir, "requires-auth", "http://localhost:8000/v1", "test-model", missingEnv)
+	config := promptkit.Config{
-	engine, err := promptkit.NewEngine(promptkit.Config{
+		PromptDir: frameworkPromptDir,
-		PromptDir:  frameworkPromptDir,
+		SchemaDir: frameworkSchemaDir,
-		ProfileDir: profileDir,
+		HTTPClient: &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
-		SchemaDir:  frameworkSchemaDir,
+			called = true
-	})
+			if values := req.Header.Values("Authorization"); len(values) != 0 {
+				t.Fatalf("Authorization values = %q, want absent", values)
+			}
+			return &http.Response{
+				StatusCode:    http.StatusUnauthorized,
+				ContentLength: int64(len(providerBody)),
+				Body:          io.NopCloser(strings.NewReader(providerBody)),
+			}, nil
+		})},
+	}
+	engine, err := promptkit.NewEngine(config,
+		promptkit.WithBackend(promptkit.Backend{
+			ID:        "optional-auth",
+			Endpoint:  "http://provider.test/v1",
+			APIKeyEnv: missingEnv,
+		}),
+		promptkit.WithProfiles(promptkit.Profile{
+			ID:        "optional-auth-profile",
+			BackendID: "optional-auth",
+			Model:     "test-model",
+		}),
+	)
 	if err != nil {
 		t.Fatalf("expected engine construction to succeed, got %v", err)
 	}
 
-	_, err = engine.Prepare(context.Background(), promptkit.RunRequest{
+	result, err := engine.Run(context.Background(), promptkit.RunRequest{
 		PromptID:  frameworkMarkdownSummaryPromptID,
-		ProfileID: "requires-auth",
+		ProfileID: "optional-auth-profile",
 		Inputs: map[string]promptkit.ArtifactRef{
 			"transcript": promptkit.Inline("Rin opens the gate."),
 			"glossary":   promptkit.Inline("gate: A guarded passage."),
 		},
 	})
-	if !errors.Is(err, promptkit.ErrInvalidRequest) {
+	if !called {
-		t.Fatalf("expected invalid request for missing credentials, got %v", err)
+		t.Fatal("optional missing credential did not reach upstream")
 	}
-	if !errors.Is(err, promptkit.ErrAPIKeyEnvMissing) {
+	if result != nil {
-		t.Fatalf("expected missing credential environment error, got %v", err)
+		t.Fatalf("result = %+v, want nil", result)
 	}
-	if err == nil || !strings.Contains(err.Error(), missingEnv) {
+	if errors.Is(err, promptkit.ErrInvalidRequest) || errors.Is(err, promptkit.ErrAPIKeyEnvMissing) {
-		t.Fatalf("expected missing env name in error, got %v", err)
+		t.Fatalf("error = %v, want upstream generation error without credential identities", err)
+	}
+	if !errors.Is(err, promptkit.ErrLLMGenerate) {
+		t.Fatalf("error = %v, want ErrLLMGenerate", err)
+	}
+	var generationErr *promptkit.GenerationError
+	if !errors.As(err, &generationErr) {
+		t.Fatalf("error = %v, want GenerationError", err)
+	}
+	if generationErr.StatusCode() != http.StatusUnauthorized ||
+		generationErr.ProviderType() != "authentication_error" ||
+		generationErr.ProviderCode() != "invalid_api_key" ||
+		generationErr.ProviderMessage() != "authentication failed" {
+		t.Fatalf("GenerationError = %+v, want structured upstream authentication failure", generationErr)
 	}
 }
 
@@ -1164,8 +1199,9 @@ func TestArtifactReaderFailuresPreserveArtifactLoadErrors(t *testing.T) {
 }
 
 func TestRunAddsLLMGenerateToCollaboratorPublicError(t *testing.T) {
+	injectedErr := errors.New("injected model client failure")
 	engine := newContractEngineWithOptions(t, frameworkSchemaDir,
-		promptkit.WithLLMClient(&fakeLLMClient{err: promptkit.ErrArtifactLoad}),
+		promptkit.WithLLMClient(&fakeLLMClient{err: injectedErr}),
 	)
 
 	_, err := engine.Run(context.Background(), promptkit.RunRequest{
@@ -1178,8 +1214,12 @@ func TestRunAddsLLMGenerateToCollaboratorPublicError(t *testing.T) {
 	if !errors.Is(err, promptkit.ErrLLMGenerate) {
 		t.Fatalf("expected ErrLLMGenerate, got %v", err)
 	}
-	if !errors.Is(err, promptkit.ErrArtifactLoad) {
+	if !errors.Is(err, injectedErr) {
-		t.Fatalf("expected preserved ErrArtifactLoad, got %v", err)
+		t.Fatalf("expected preserved injected error, got %v", err)
+	}
+	var generationErr *promptkit.GenerationError
+	if errors.As(err, &generationErr) {
+		t.Fatalf("injected error became GenerationError: %v", err)
 	}
 }
 
@@ -1492,43 +1532,63 @@ func TestSelectedProfileRepositoryReadFailureMapsToProfileLoad(t *testing.T) {
 }
 
 func TestPrepareUsesBuiltInProfileWithoutProfileDir(t *testing.T) {
-	t.Setenv("OPENROUTER_API_KEY", "test-key")
+	tests := []struct {
-	engine, err := promptkit.NewEngine(promptkit.Config{
+		name      string
-		PromptDir: frameworkPromptDir,
+		profileID string
-		SchemaDir: frameworkSchemaDir,
+		backendID string
-	})
+		endpoint  string
-	if err != nil {
+		apiKeyEnv string
-		t.Fatalf("expected engine construction to succeed, got %v", err)
+		model     string
+	}{
+		{
+			name:      "OpenRouter",
+			profileID: "mistral-small-3",
+			backendID: promptkit.BackendOpenRouter,
+			endpoint:  "https://openrouter.ai/api/v1",
+			apiKeyEnv: "OPENROUTER_API_KEY",
+			model:     "mistralai/mistral-small-3.2-24b-instruct",
+		},
+		{
+			name:      "Rakestrawhome",
+			profileID: "rakestrawhome-gemma-4-31b",
+			backendID: promptkit.BackendRakestrawHome,
+			endpoint:  "https://inference.ai.rakestrawhome.com/v1",
+			apiKeyEnv: "RAKESTRAWHOME_INFERENCE_API_KEY",
+			model:     "google/gemma-4-31b-it",
+		},
 	}
 
-	prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{
+	for _, tc := range tests {
-		PromptID:  frameworkMarkdownSummaryPromptID,
+		t.Run(tc.name, func(t *testing.T) {
-		ProfileID: "mistral-small-3",
+			t.Setenv(tc.apiKeyEnv, "test-key")
-		Inputs: map[string]promptkit.ArtifactRef{
+			engine, err := promptkit.NewEngine(promptkit.Config{
-			"transcript": promptkit.Inline("Rin opens the gate."),
+				PromptDir: frameworkPromptDir,
-			"glossary":   promptkit.Inline("gate: A guarded passage."),
+				SchemaDir: frameworkSchemaDir,
-		},
+			})
-	})
+			if err != nil {
-	if err != nil {
+				t.Fatalf("expected engine construction to succeed, got %v", err)
-		t.Fatalf("expected built-in profile prepare to succeed, got %v", err)
+			}
-	}
+
-	if prepared.SelectedProfileID != "mistral-small-3" {
+			prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{
-		t.Fatalf("unexpected selected profile: %q", prepared.SelectedProfileID)
+				PromptID:  frameworkMarkdownSummaryPromptID,
-	}
+				ProfileID: tc.profileID,
-	if prepared.SelectedBackendID != promptkit.BackendOpenRouter {
+				Inputs: map[string]promptkit.ArtifactRef{
-		t.Fatalf("unexpected selected backend: %q", prepared.SelectedBackendID)
+					"transcript": promptkit.Inline("Rin opens the gate."),
-	}
+					"glossary":   promptkit.Inline("gate: A guarded passage."),
-	if prepared.EffectiveModelParams.BackendID != promptkit.BackendOpenRouter {
+				},
-		t.Fatalf("unexpected effective backend: %q", prepared.EffectiveModelParams.BackendID)
+			})
-	}
+			if err != nil {
-	if prepared.EffectiveModelParams.Endpoint != "https://openrouter.ai/api/v1" {
+				t.Fatalf("expected built-in profile prepare to succeed, got %v", err)
-		t.Fatalf("unexpected built-in endpoint: %q", prepared.EffectiveModelParams.Endpoint)
+			}
-	}
+			if prepared.SelectedProfileID != tc.profileID ||
-	if prepared.EffectiveModelParams.APIKeyEnv != "OPENROUTER_API_KEY" {
+				prepared.SelectedBackendID != tc.backendID ||
-		t.Fatalf("unexpected built-in api key environment name: %q", prepared.EffectiveModelParams.APIKeyEnv)
+				prepared.EffectiveModelParams.BackendID != tc.backendID ||
-	}
+				prepared.EffectiveModelParams.Endpoint != tc.endpoint ||
-	if prepared.EffectiveModelParams.Model != "mistralai/mistral-small-3.2-24b-instruct" {
+				prepared.EffectiveModelParams.APIKeyEnv != tc.apiKeyEnv ||
-		t.Fatalf("unexpected built-in model: %q", prepared.EffectiveModelParams.Model)
+				prepared.EffectiveModelParams.Model != tc.model {
+				t.Fatalf("unexpected built-in preparation: %#v", prepared)
+			}
+		})
 	}
 }
 
@@ -1958,6 +2018,25 @@ func TestWithProfilesRejectsDuplicateIDs(t *testing.T) {
 	}
 }
 
+func TestWithProfilesAcceptsDerivedDefinitionWithoutTargetFields(t *testing.T) {
+	_, err := promptkit.NewEngine(promptkit.Config{PromptDir: frameworkPromptDir},
+		promptkit.WithProfiles(promptkit.Profile{
+			ID:            " derived-profile ",
+			BaseProfileID: " base-profile ",
+		}),
+	)
+	if err != nil {
+		t.Fatalf("derived profile should be accepted during construction: %v", err)
+	}
+
+	_, err = promptkit.NewEngine(promptkit.Config{PromptDir: frameworkPromptDir},
+		promptkit.WithProfiles(promptkit.Profile{ID: "standalone-profile"}),
+	)
+	if !errors.Is(err, promptkit.ErrInvalidConfig) {
+		t.Fatalf("standalone incomplete profile error = %v, want ErrInvalidConfig", err)
+	}
+}
+
 func TestWithProfilesRejectsInvalidExecutionSettings(t *testing.T) {
 	type testCase struct {
 		name    string
@@ -2110,6 +2189,7 @@ func TestOpenAICompatibleProfileMapsEveryField(t *testing.T) {
 	extraParams := map[string]any{"provider_option": "distinct-extra-params"}
 	got := promptkit.OpenAICompatibleProfile(promptkit.OpenAICompatibleProfileConfig{
 		ID:              "distinct-id",
+		BaseProfileID:   "distinct-base",
 		BackendID:       "distinct-backend",
 		Endpoint:        "https://distinct.example/v1",
 		Model:           "distinct-model",
@@ -2124,6 +2204,7 @@ func TestOpenAICompatibleProfileMapsEveryField(t *testing.T) {
 	})
 	want := promptkit.Profile{
 		ID:              "distinct-id",
+		BaseProfileID:   "distinct-base",
 		BackendID:       "distinct-backend",
 		Endpoint:        "https://distinct.example/v1",
 		Model:           "distinct-model",

errors.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"gitea.maximumdirect.net/eric/promptkit/internal/capacity"
+	"gitea.maximumdirect.net/eric/promptkit/internal/llm"
 	"gitea.maximumdirect.net/eric/promptkit/internal/profile"
 	"gitea.maximumdirect.net/eric/promptkit/internal/promptdef"
 	"gitea.maximumdirect.net/eric/promptkit/internal/usecase"
@@ -21,6 +22,19 @@ func mapPublicError(err error) error {
 		return &CapacityError{BackendID: internalCapacityError.BackendID}
 	}
 	publicErr := publicErrorFor(err)
+	var providerHTTPError *llm.ProviderHTTPError
+	if errors.As(err, &providerHTTPError) && providerHTTPError != nil {
+		generationErr := newGenerationError(
+			providerHTTPError.StatusCode(),
+			providerHTTPError.ProviderCode(),
+			providerHTTPError.ProviderType(),
+			providerHTTPError.ProviderMessage(),
+		)
+		if publicErr != nil && !errors.Is(publicErr, ErrLLMGenerate) {
+			return fmt.Errorf("%w: %w", publicErr, generationErr)
+		}
+		return generationErr
+	}
 	if publicErr == nil {
 		return err
 	}

errors_internal_test.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"testing"
 
+	"gitea.maximumdirect.net/eric/promptkit/internal/llm"
 	"gitea.maximumdirect.net/eric/promptkit/internal/usecase"
 )
 
@@ -48,3 +49,27 @@ func TestMapPublicErrorTranslatesCapacityError(t *testing.T) {
 		t.Fatalf("mapped backend ID changed with source error: %q", publicErr.BackendID)
 	}
 }
+
+func TestMapPublicErrorPreservesValidationAroundGenerationError(t *testing.T) {
+	internalErr := fmt.Errorf(
+		"%w: %w",
+		usecase.ErrValidation,
+		&llm.ProviderHTTPError{},
+	)
+
+	err := mapPublicError(internalErr)
+	if !errors.Is(err, ErrValidation) {
+		t.Fatalf("mapped error=%v, want ErrValidation", err)
+	}
+	if !errors.Is(err, ErrLLMGenerate) {
+		t.Fatalf("mapped error=%v, want ErrLLMGenerate", err)
+	}
+	var generationErr *GenerationError
+	if !errors.As(err, &generationErr) || generationErr == nil {
+		t.Fatalf("mapped error=%v, want GenerationError", err)
+	}
+	var leakedInternalErr *llm.ProviderHTTPError
+	if errors.As(err, &leakedInternalErr) {
+		t.Fatalf("mapped error exposes internal ProviderHTTPError: %v", err)
+	}
+}

generation_error.go

@@ -0,0 +1,87 @@
+package promptkit
+
+import "fmt"
+
+// GenerationError reports a non-2xx response from Promptkit's built-in
+// OpenAI-compatible client during [Engine.Run] or [Engine.RunPrepared].
+//
+// Engine-produced values are immutable, caller-owned values. Use errors.Is to
+// match [ErrLLMGenerate] and errors.As with a *GenerationError target to obtain
+// this type. The four provider accessors expose untrusted provider-controlled
+// values that can contain sensitive request or schema fragments. Applications
+// must apply their own disclosure policy before logging, displaying, or
+// returning them to another caller.
+//
+// Accessors, Error, GoString, and Unwrap are safe on a nil receiver and a zero
+// value. Default and Go-syntax formatting deliberately redact provider details.
+// GenerationError has no stable JSON representation.
+type GenerationError struct {
+	statusCode      int
+	providerCode    string
+	providerType    string
+	providerMessage string
+}
+
+func newGenerationError(statusCode int, providerCode, providerType, providerMessage string) *GenerationError {
+	return &GenerationError{
+		statusCode:      statusCode,
+		providerCode:    providerCode,
+		providerType:    providerType,
+		providerMessage: providerMessage,
+	}
+}
+
+// StatusCode returns the received provider HTTP status code, or zero for a nil
+// receiver or zero value.
+func (e *GenerationError) StatusCode() int {
+	if e == nil {
+		return 0
+	}
+	return e.statusCode
+}
+
+// ProviderCode returns the normalized provider error code, if present. Its
+// value is untrusted and may contain sensitive data.
+func (e *GenerationError) ProviderCode() string {
+	if e == nil {
+		return ""
+	}
+	return e.providerCode
+}
+
+// ProviderType returns the normalized provider error type, if present. Its
+// value is untrusted and may contain sensitive data.
+func (e *GenerationError) ProviderType() string {
+	if e == nil {
+		return ""
+	}
+	return e.providerType
+}
+
+// ProviderMessage returns the bounded normalized provider diagnostic, if
+// present. Its value is untrusted and may contain sensitive data.
+func (e *GenerationError) ProviderMessage() string {
+	if e == nil {
+		return ""
+	}
+	return e.providerMessage
+}
+
+// Error returns a redacted diagnostic that is not a parsing contract.
+func (e *GenerationError) Error() string {
+	if e == nil || e.statusCode == 0 {
+		return ErrLLMGenerate.Error()
+	}
+	return fmt.Sprintf("%s: provider returned HTTP status %d", ErrLLMGenerate, e.statusCode)
+}
+
+// GoString returns the same redacted diagnostic as Error.
+func (e *GenerationError) GoString() string {
+	return e.Error()
+}
+
+// Unwrap returns ErrLLMGenerate. It is safe to call on a nil receiver or zero
+// value.
+func (e *GenerationError) Unwrap() error {
+	return ErrLLMGenerate
+}

generation_error_contract_test.go

@@ -0,0 +1,95 @@
+package promptkit_test
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/promptkit"
+)
+
+func TestBuiltInGenerationError(t *testing.T) {
+	const (
+		codeMarker    = "provider-code-marker"
+		typeMarker    = "provider-type-marker"
+		messageMarker = "provider-message-marker"
+	)
+	engine := newBuiltInGenerationErrorEngine(t, http.StatusUnprocessableEntity,
+		`{"error":{"code":"`+codeMarker+`","type":"`+typeMarker+`","message":"`+messageMarker+`"}}`)
+
+	result, err := engine.Run(context.Background(), generationErrorRunRequest())
+	if result != nil {
+		t.Fatalf("Run result = %#v, want nil", result)
+	}
+	assertGenerationError(t, err, http.StatusUnprocessableEntity, codeMarker, typeMarker, messageMarker)
+
+	preparedEngine := newBuiltInGenerationErrorEngine(t, http.StatusServiceUnavailable, `{"error":{}}`)
+	prepared, err := preparedEngine.PrepareExecution(context.Background(), generationErrorRunRequest())
+	if err != nil {
+		t.Fatalf("PrepareExecution: %v", err)
+	}
+	result, err = preparedEngine.RunPrepared(context.Background(), prepared)
+	if result != nil {
+		t.Fatalf("RunPrepared result = %#v, want nil", result)
+	}
+	assertGenerationError(t, err, http.StatusServiceUnavailable, "", "", "")
+}
+
+func assertGenerationError(t *testing.T, err error, statusCode int, code, providerType, message string) {
+	t.Helper()
+
+	if !errors.Is(err, promptkit.ErrLLMGenerate) {
+		t.Fatalf("errors.Is(%v, ErrLLMGenerate) = false", err)
+	}
+	var generationErr *promptkit.GenerationError
+	if !errors.As(err, &generationErr) || generationErr == nil {
+		t.Fatalf("error = %T, want *GenerationError", err)
+	}
+	if generationErr.StatusCode() != statusCode || generationErr.ProviderCode() != code || generationErr.ProviderType() != providerType || generationErr.ProviderMessage() != message {
+		t.Fatalf("GenerationError = %#v", generationErr)
+	}
+
+	wantFormatted := fmt.Sprintf("failed to generate output: provider returned HTTP status %d", statusCode)
+	for _, rendered := range []string{fmt.Sprintf("%v", generationErr), fmt.Sprintf("%+v", generationErr), fmt.Sprintf("%#v", generationErr)} {
+		if rendered != wantFormatted {
+			t.Fatalf("formatted error = %q, want %q", rendered, wantFormatted)
+		}
+		for _, marker := range []string{code, providerType, message} {
+			if marker != "" && strings.Contains(rendered, marker) {
+				t.Fatalf("formatted error exposed provider marker %q: %q", marker, rendered)
+			}
+		}
+	}
+}
+
+func newBuiltInGenerationErrorEngine(t *testing.T, statusCode int, body string) *promptkit.Engine {
+	t.Helper()
+
+	config := contractConfig(frameworkSchemaDir)
+	config.HTTPClient = &http.Client{Transport: roundTripFunc(func(*http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode:    statusCode,
+			ContentLength: int64(len(body)),
+			Body:          io.NopCloser(strings.NewReader(body)),
+		}, nil
+	})}
+	engine, err := promptkit.NewEngine(config)
+	if err != nil {
+		t.Fatalf("NewEngine: %v", err)
+	}
+	return engine
+}
+
+func generationErrorRunRequest() promptkit.RunRequest {
+	return promptkit.RunRequest{
+		PromptID: frameworkMarkdownSummaryPromptID,
+		Inputs: map[string]promptkit.ArtifactRef{
+			"transcript": promptkit.Inline("Rin opens the gate."),
+			"glossary":   promptkit.Inline("gate: A guarded passage."),
+		},
+	}
+}

generation_error_internal_test.go

@@ -0,0 +1,32 @@
+package promptkit
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestGenerationErrorNilAndZeroValue(t *testing.T) {
+	var nilError *GenerationError
+	zeroError := &GenerationError{}
+
+	for name, err := range map[string]*GenerationError{
+		"nil":  nilError,
+		"zero": zeroError,
+	} {
+		t.Run(name, func(t *testing.T) {
+			if err.StatusCode() != 0 || err.ProviderCode() != "" || err.ProviderType() != "" || err.ProviderMessage() != "" {
+				t.Fatalf("accessors returned provider details: %#v", err)
+			}
+			if err.Error() != "failed to generate output" || err.GoString() != "failed to generate output" {
+				t.Fatalf("redacted formatting = (%q, %q)", err.Error(), err.GoString())
+			}
+			if fmt.Sprintf("%v", err) != "failed to generate output" || fmt.Sprintf("%#v", err) != "failed to generate output" {
+				t.Fatalf("formatted error = (%q, %q)", fmt.Sprintf("%v", err), fmt.Sprintf("%#v", err))
+			}
+			if !errors.Is(err, ErrLLMGenerate) {
+				t.Fatalf("errors.Is(%v, ErrLLMGenerate) = false", err)
+			}
+		})
+	}
+}

internal/backend/registry.go

@@ -18,12 +18,20 @@ const (
 	// OpenRouterID is the reserved ID of Promptkit's built-in OpenRouter
 	// backend.
 	OpenRouterID = "openrouter"
+	// RakestrawHomeID is the reserved ID of Promptkit's built-in Rakestrawhome
+	// backend.
+	RakestrawHomeID = "rakestrawhome"
 
 	openRouterEndpoint  = "https://openrouter.ai/api/v1"
 	openRouterAPIKeyEnv = "OPENROUTER_API_KEY"
 
 	openRouterConcurrencyLimit = 16
-	defaultQueueCapacity       = 1024
+
+	rakestrawHomeEndpoint  = "https://inference.ai.rakestrawhome.com/v1"
+	rakestrawHomeAPIKeyEnv = "RAKESTRAWHOME_INFERENCE_API_KEY"
+
+	rakestrawHomeConcurrencyLimit = 4
+	defaultQueueCapacity          = 1024
 )
 
 // ErrBackendNotFound identifies a registry lookup for an unknown backend ID.
@@ -36,20 +44,16 @@ type Registry struct {
 	backends map[string]domain.Backend
 }
 
-// NewRegistry constructs a registry containing the built-in OpenRouter
+// NewRegistry constructs a registry containing the built-in definitions
-// definition followed by the supplied additions. Every ID must be unique.
+// followed by the supplied additions. Every ID must be unique.
 func NewRegistry(additions []domain.Backend) (*Registry, error) {
+	builtIns := builtInBackends()
 	registry := &Registry{
-		backends: make(map[string]domain.Backend, len(additions)+1),
+		backends: make(map[string]domain.Backend, len(builtIns)+len(additions)),
 	}
 
-	definitions := make([]domain.Backend, 0, len(additions)+1)
+	definitions := make([]domain.Backend, 0, len(builtIns)+len(additions))
-	definitions = append(definitions, domain.Backend{
+	definitions = append(definitions, builtIns...)
-		ID:               OpenRouterID,
-		Endpoint:         openRouterEndpoint,
-		APIKeyEnv:        openRouterAPIKeyEnv,
-		ConcurrencyLimit: openRouterConcurrencyLimit,
-	})
 	definitions = append(definitions, additions...)
 
 	for _, definition := range definitions {
@@ -71,6 +75,23 @@ func NewRegistry(additions []domain.Backend) (*Registry, error) {
 	return registry, nil
 }
 
+func builtInBackends() []domain.Backend {
+	return []domain.Backend{
+		{
+			ID:               OpenRouterID,
+			Endpoint:         openRouterEndpoint,
+			APIKeyEnv:        openRouterAPIKeyEnv,
+			ConcurrencyLimit: openRouterConcurrencyLimit,
+		},
+		{
+			ID:               RakestrawHomeID,
+			Endpoint:         rakestrawHomeEndpoint,
+			APIKeyEnv:        rakestrawHomeAPIKeyEnv,
+			ConcurrencyLimit: rakestrawHomeConcurrencyLimit,
+		},
+	}
+}
+
 // GetBackend returns a defensive copy of the backend registered with id.
 func (r *Registry) GetBackend(id string) (domain.Backend, error) {
 	if r == nil {

internal/backend/registry_test.go

@@ -11,32 +11,63 @@ import (
 
 const validEndpoint = "https://backend.example/v1"
 
-func TestRegistryIncludesExactOpenRouterDefinition(t *testing.T) {
+func TestRegistryIncludesExactBuiltInDefinitions(t *testing.T) {
 	registry, err := backend.NewRegistry(nil)
 	if err != nil {
 		t.Fatalf("construct registry: %v", err)
 	}
 
-	definition, err := registry.GetBackend(backend.OpenRouterID)
+	tests := []struct {
-	if err != nil {
+		name       string
-		t.Fatalf("look up OpenRouter: %v", err)
+		id         string
+		endpoint   string
+		apiKeyEnv  string
+		concurrent int
+	}{
+		{
+			name:       "OpenRouter",
+			id:         backend.OpenRouterID,
+			endpoint:   "https://openrouter.ai/api/v1",
+			apiKeyEnv:  "OPENROUTER_API_KEY",
+			concurrent: 16,
+		},
+		{
+			name:       "Rakestrawhome",
+			id:         backend.RakestrawHomeID,
+			endpoint:   "https://inference.ai.rakestrawhome.com/v1",
+			apiKeyEnv:  "RAKESTRAWHOME_INFERENCE_API_KEY",
+			concurrent: 4,
+		},
 	}
-	if definition.ID != "openrouter" ||
+	for _, tc := range tests {
-		definition.Endpoint != "https://openrouter.ai/api/v1" ||
+		t.Run(tc.name, func(t *testing.T) {
-		definition.APIKeyEnv != "OPENROUTER_API_KEY" ||
+			definition, err := registry.GetBackend(tc.id)
-		definition.ConcurrencyLimit != 16 ||
+			if err != nil {
-		definition.QueueCapacity != 1024 ||
+				t.Fatalf("look up built-in: %v", err)
-		!definition.QueueCapacitySet ||
+			}
-		definition.ExtraParams != nil {
+			if definition.ID != tc.id ||
-		t.Fatalf("unexpected OpenRouter definition: %#v", definition)
+				definition.Endpoint != tc.endpoint ||
+				definition.APIKeyEnv != tc.apiKeyEnv ||
+				definition.ConcurrencyLimit != tc.concurrent ||
+				definition.QueueCapacity != 1024 ||
+				!definition.QueueCapacitySet ||
+				definition.ExtraParams != nil {
+				t.Fatalf("unexpected built-in definition: %#v", definition)
+			}
+		})
 	}
+
 	policies := registry.CapacityPolicies()
-	if len(policies) != 1 ||
+	if len(policies) != 2 ||
-		policies["openrouter"] != (domain.BackendCapacityPolicy{
+		policies[backend.OpenRouterID] != (domain.BackendCapacityPolicy{
 			ConcurrencyLimit: 16,
 			QueueCapacity:    1024,
+		}) ||
+		policies[backend.RakestrawHomeID] != (domain.BackendCapacityPolicy{
+			ConcurrencyLimit: 4,
+			QueueCapacity:    1024,
 		}) {
-		t.Fatalf("unexpected OpenRouter capacity policies: %#v", policies)
+		t.Fatalf("unexpected built-in capacity policies: %#v", policies)
 	}
 }
 
@@ -109,11 +140,12 @@ func TestRegistryNormalizesUniqueAdditionsAndIsolatesMutations(t *testing.T) {
 	}
 
 	policies := registry.CapacityPolicies()
-	if len(policies) != 2 {
+	if len(policies) != 3 {
 		t.Fatalf("unexpected capacity policy count: %#v", policies)
 	}
 	policies["custom"] = domain.BackendCapacityPolicy{}
 	delete(policies, backend.OpenRouterID)
+	delete(policies, backend.RakestrawHomeID)
 	againPolicies := registry.CapacityPolicies()
 	if againPolicies["custom"] != (domain.BackendCapacityPolicy{
 		ConcurrencyLimit: 3,
@@ -122,7 +154,10 @@ func TestRegistryNormalizesUniqueAdditionsAndIsolatesMutations(t *testing.T) {
 		t.Fatalf("capacity policy map mutated registry state: %#v", againPolicies)
 	}
 	if _, ok := againPolicies[backend.OpenRouterID]; !ok {
-		t.Fatalf("capacity policy deletion mutated registry state: %#v", againPolicies)
+		t.Fatalf("OpenRouter capacity policy deletion mutated registry state: %#v", againPolicies)
+	}
+	if _, ok := againPolicies[backend.RakestrawHomeID]; !ok {
+		t.Fatalf("Rakestrawhome capacity policy deletion mutated registry state: %#v", againPolicies)
 	}
 }
 
@@ -242,11 +277,14 @@ func TestNewRegistryRejectsDuplicateIDs(t *testing.T) {
 		wantID    string
 	}{
 		{
-			name: "built-in collision after normalization",
+			name:      "OpenRouter collision after normalization",
-			additions: []domain.Backend{{
+			additions: []domain.Backend{{ID: " openrouter "}},
-				ID: " openrouter ",
+			wantID:    backend.OpenRouterID,
-			}},
+		},
-			wantID: "openrouter",
+		{
+			name:      "Rakestrawhome collision after normalization",
+			additions: []domain.Backend{{ID: " rakestrawhome "}},
+			wantID:    backend.RakestrawHomeID,
 		},
 		{
 			name: "consumer collision after normalization",

internal/domain/domain.go

@@ -192,6 +192,7 @@ type BackendCapacityPolicy struct {
 // ExecutionProfile describes how and where to execute a model.
 type ExecutionProfile struct {
 	ID              string         `yaml:"id"`
+	BaseProfileID   string         `yaml:"base_profile"`
 	BackendID       string         `yaml:"backend"`
 	Endpoint        string         `yaml:"endpoint"`
 	Model           string         `yaml:"model"`

internal/llm/openai_compatible_client.go

@@ -133,13 +133,18 @@ func (c *OpenAICompatibleClient) Generate(ctx context.Context, req domain.Genera
 		return nil, fmt.Errorf("%w: failed to create request: %v", ErrRequestFailed, err)
 	}
 	httpReq.Header.Set("Content-Type", "application/json")
-	if apiKey := strings.TrimSpace(req.Target.APIKey); apiKey != "" {
+	apiKey := strings.TrimSpace(req.Target.APIKey)
-		httpReq.Header.Set("Authorization", "Bearer "+apiKey)
+	envName := strings.TrimSpace(req.Target.APIKeyEnv)
-	} else if envName := strings.TrimSpace(req.Target.APIKeyEnv); envName != "" {
+	if apiKey == "" && envName != "" {
-		apiKey := strings.TrimSpace(os.Getenv(envName))
+		apiKey = strings.TrimSpace(os.Getenv(envName))
-		if apiKey == "" {
+	}
+	if apiKey == "" && req.Target.APIKeyRequired {
+		if envName != "" {
 			return nil, fmt.Errorf("%w: api key environment variable %q is not set", ErrInvalidRequest, envName)
 		}
+		return nil, fmt.Errorf("%w: api key is required", ErrInvalidRequest)
+	}
+	if apiKey != "" {
 		httpReq.Header.Set("Authorization", "Bearer "+apiKey)
 	}
 
@@ -155,8 +160,11 @@ func (c *OpenAICompatibleClient) Generate(ctx context.Context, req domain.Genera
 	defer httpResp.Body.Close()
 
 	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
-		_, _ = io.Copy(io.Discard, io.LimitReader(httpResp.Body, 4096))
+		return nil, providerHTTPErrorFromBody(
-		return nil, fmt.Errorf("%w: status=%d", ErrUnexpectedStatus, httpResp.StatusCode)
+			httpResp.StatusCode,
+			httpResp.ContentLength,
+			httpResp.Body,
+		)
 	}
 	if httpResp.ContentLength > maxOpenAIChatResponseBytes {
 		return nil, openAIChatResponseTooLargeError()

internal/llm/openai_compatible_client_test.go

@@ -501,36 +501,61 @@ func checkCompleteRequestAndResponseMapping(t *testing.T) {
 
 func TestOpenAICompatibleClientAuthentication(t *testing.T) {
 	tests := []struct {
-		name          string
+		name              string
-		configureEnv  func(*testing.T)
+		configureEnv      func(*testing.T)
-		target        domain.ExecutionTarget
+		target            domain.ExecutionTarget
-		wantAuth      string
+		wantAuthorization string
-		wantErr       error
+		wantError         error
-		wantCallCount int
+		wantCallCount     int
 	}{
 		{
 			name: "direct key takes precedence over environment",
 			configureEnv: func(t *testing.T) {
-				t.Setenv("PROMPTKIT_TEST_API_KEY", "env-key")
+				t.Setenv("PROMPTKIT_TEST_API_KEY", " env-key ")
 			},
 			target: domain.ExecutionTarget{
 				APIKeyEnv: "PROMPTKIT_TEST_API_KEY",
-				APIKey:    "direct-llm-key",
+				APIKey:    " direct-llm-key ",
 			},
-			wantAuth:      "Bearer direct-llm-key",
+			wantAuthorization: "Bearer direct-llm-key",
-			wantCallCount: 1,
+			wantCallCount:     1,
+		},
+		{
+			name: "environment key supplies authorization",
+			configureEnv: func(t *testing.T) {
+				t.Setenv("PROMPTKIT_TEST_API_KEY", " env-key ")
+			},
+			target:            domain.ExecutionTarget{APIKeyEnv: "PROMPTKIT_TEST_API_KEY"},
+			wantAuthorization: "Bearer env-key",
+			wantCallCount:     1,
 		},
 		{
 			name:          "no key omits authorization",
 			wantCallCount: 1,
 		},
 		{
-			name: "missing environment key fails before transport",
+			name: "optional missing environment omits authorization",
 			configureEnv: func(t *testing.T) {
 				t.Setenv("PROMPTKIT_MISSING_KEY", "")
 			},
-			target:  domain.ExecutionTarget{APIKeyEnv: "PROMPTKIT_MISSING_KEY"},
+			target:        domain.ExecutionTarget{APIKeyEnv: "PROMPTKIT_MISSING_KEY"},
-			wantErr: ErrInvalidRequest,
+			wantCallCount: 1,
+		},
+		{
+			name: "required missing environment fails before transport",
+			configureEnv: func(t *testing.T) {
+				t.Setenv("PROMPTKIT_MISSING_KEY", "")
+			},
+			target: domain.ExecutionTarget{
+				APIKeyEnv:      "PROMPTKIT_MISSING_KEY",
+				APIKeyRequired: true,
+			},
+			wantError: ErrInvalidRequest,
+		},
+		{
+			name:      "required target without source fails before transport",
+			target:    domain.ExecutionTarget{APIKeyRequired: true},
+			wantError: ErrInvalidRequest,
 		},
 	}
 
@@ -545,9 +570,9 @@ func TestOpenAICompatibleClientAuthentication(t *testing.T) {
 			request.Target = tc.target
 
 			_, err := client.Generate(context.Background(), request)
-			if tc.wantErr != nil {
+			if tc.wantError != nil {
-				if !errors.Is(err, tc.wantErr) {
+				if !errors.Is(err, tc.wantError) {
-					t.Fatalf("error = %v, want %v", err, tc.wantErr)
+					t.Fatalf("error = %v, want %v", err, tc.wantError)
 				}
 			} else if err != nil {
 				t.Fatalf("generate: %v", err)
@@ -556,8 +581,13 @@ func TestOpenAICompatibleClientAuthentication(t *testing.T) {
 				t.Fatalf("provider calls = %d, want %d", got, tc.wantCallCount)
 			}
 			if tc.wantCallCount == 1 {
-				if got := provider.lastRequest(t).header.Get("Authorization"); got != tc.wantAuth {
+				values := provider.lastRequest(t).header.Values("Authorization")
-					t.Fatalf("Authorization = %q, want %q", got, tc.wantAuth)
+				if tc.wantAuthorization == "" {
+					if len(values) != 0 {
+						t.Fatalf("Authorization values = %q, want absent", values)
+					}
+				} else if len(values) != 1 || values[0] != tc.wantAuthorization {
+					t.Fatalf("Authorization values = %q, want [%q]", values, tc.wantAuthorization)
 				}
 			}
 		})
@@ -1114,6 +1144,15 @@ func checkCommonResponseFailures(t *testing.T) {
 			if !errors.Is(err, tc.wantErr) {
 				t.Fatalf("error = %v, want %v", err, tc.wantErr)
 			}
+			if tc.statusCode < http.StatusOK || tc.statusCode >= http.StatusMultipleChoices {
+				var providerHTTPError *ProviderHTTPError
+				if !errors.As(err, &providerHTTPError) {
+					t.Fatalf("error = %T, want *ProviderHTTPError", err)
+				}
+				if got := providerHTTPError.StatusCode(); got != tc.statusCode {
+					t.Fatalf("provider status = %d, want %d", got, tc.statusCode)
+				}
+			}
 			if tc.wantText != "" && !strings.Contains(err.Error(), tc.wantText) {
 				t.Fatalf("error %q does not contain %q", err, tc.wantText)
 			}

internal/llm/provider_http_error.go

@@ -0,0 +1,189 @@
+package llm
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"unicode"
+)
+
+const (
+	maxProviderErrorResponseBytes   int64 = 64 << 10
+	maxProviderErrorIdentifierRunes       = 256
+	maxProviderErrorMessageRunes          = 4096
+)
+
+// ProviderHTTPError describes a non-success response from an LLM provider.
+type ProviderHTTPError struct {
+	statusCode      int
+	providerCode    string
+	providerType    string
+	providerMessage string
+}
+
+func (e *ProviderHTTPError) StatusCode() int {
+	if e == nil {
+		return 0
+	}
+	return e.statusCode
+}
+
+func (e *ProviderHTTPError) ProviderCode() string {
+	if e == nil {
+		return ""
+	}
+	return e.providerCode
+}
+
+func (e *ProviderHTTPError) ProviderType() string {
+	if e == nil {
+		return ""
+	}
+	return e.providerType
+}
+
+func (e *ProviderHTTPError) ProviderMessage() string {
+	if e == nil {
+		return ""
+	}
+	return e.providerMessage
+}
+
+func (e *ProviderHTTPError) Error() string {
+	if e == nil || e.statusCode == 0 {
+		return ErrUnexpectedStatus.Error()
+	}
+	return fmt.Sprintf("%s: status=%d", ErrUnexpectedStatus, e.statusCode)
+}
+
+func (e *ProviderHTTPError) GoString() string {
+	return e.Error()
+}
+
+func (e *ProviderHTTPError) Unwrap() error {
+	return ErrUnexpectedStatus
+}
+
+type providerErrorDetails struct {
+	providerCode    string
+	providerType    string
+	providerMessage string
+}
+
+func newProviderHTTPError(statusCode int, details providerErrorDetails) *ProviderHTTPError {
+	return &ProviderHTTPError{
+		statusCode:      statusCode,
+		providerCode:    details.providerCode,
+		providerType:    details.providerType,
+		providerMessage: details.providerMessage,
+	}
+}
+
+func providerHTTPErrorFromBody(statusCode int, contentLength int64, body io.Reader) *ProviderHTTPError {
+	if contentLength > maxProviderErrorResponseBytes {
+		return newProviderHTTPError(statusCode, providerErrorDetails{})
+	}
+
+	limited := &io.LimitedReader{
+		R: body,
+		N: maxProviderErrorResponseBytes + 1,
+	}
+	contents, err := io.ReadAll(limited)
+	if err != nil || limited.N == 0 {
+		return newProviderHTTPError(statusCode, providerErrorDetails{})
+	}
+	return newProviderHTTPError(statusCode, parseProviderErrorEnvelope(contents))
+}
+
+func parseProviderErrorEnvelope(body []byte) providerErrorDetails {
+	decoder := json.NewDecoder(strings.NewReader(string(body)))
+	decoder.UseNumber()
+
+	var envelope map[string]json.RawMessage
+	if err := decoder.Decode(&envelope); err != nil {
+		return providerErrorDetails{}
+	}
+	var trailing any
+	if err := decoder.Decode(&trailing); !errors.Is(err, io.EOF) {
+		return providerErrorDetails{}
+	}
+
+	rawError, ok := envelope["error"]
+	if !ok {
+		return providerErrorDetails{}
+	}
+	var providerError map[string]json.RawMessage
+	if err := json.Unmarshal(rawError, &providerError); err != nil || providerError == nil {
+		return providerErrorDetails{}
+	}
+
+	var details providerErrorDetails
+	if raw, ok := providerError["message"]; ok {
+		var value string
+		if json.Unmarshal(raw, &value) == nil {
+			details.providerMessage = normalizeProviderErrorMessage(value)
+		}
+	}
+	if raw, ok := providerError["type"]; ok {
+		var value string
+		if json.Unmarshal(raw, &value) == nil {
+			details.providerType = normalizeProviderErrorIdentifier(value)
+		}
+	}
+	if raw, ok := providerError["code"]; ok {
+		var value any
+		fieldDecoder := json.NewDecoder(strings.NewReader(string(raw)))
+		fieldDecoder.UseNumber()
+		if fieldDecoder.Decode(&value) == nil {
+			switch value := value.(type) {
+			case string:
+				details.providerCode = normalizeProviderErrorIdentifier(value)
+			case json.Number:
+				details.providerCode = normalizeProviderErrorIdentifier(value.String())
+			}
+		}
+	}
+
+	return details
+}
+
+func normalizeProviderErrorIdentifier(value string) string {
+	normalized := normalizeProviderErrorText(value)
+	if len([]rune(normalized)) > maxProviderErrorIdentifierRunes {
+		return ""
+	}
+	return normalized
+}
+
+func normalizeProviderErrorMessage(value string) string {
+	normalized := normalizeProviderErrorText(value)
+	runes := []rune(normalized)
+	if len(runes) <= maxProviderErrorMessageRunes {
+		return normalized
+	}
+	return string(runes[:maxProviderErrorMessageRunes-1]) + "…"
+}
+
+func normalizeProviderErrorText(value string) string {
+	value = strings.ToValidUTF8(value, "<22>")
+
+	var result strings.Builder
+	result.Grow(len(value))
+	separatorPending := false
+	for _, r := range value {
+		if unicode.IsSpace(r) || unicode.IsControl(r) || unicode.In(r, unicode.Cf) {
+			if result.Len() > 0 {
+				separatorPending = true
+			}
+			continue
+		}
+		if separatorPending {
+			result.WriteByte(' ')
+			separatorPending = false
+		}
+		result.WriteRune(r)
+	}
+	return result.String()
+}

internal/llm/provider_http_error_test.go

@@ -0,0 +1,255 @@
+package llm
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"reflect"
+	"strings"
+	"testing"
+	"unicode/utf8"
+)
+
+type guardedReader struct {
+	reader    io.Reader
+	remaining int64
+	bytes     int64
+	violated  bool
+}
+
+func (r *guardedReader) Read(buffer []byte) (int, error) {
+	if int64(len(buffer)) > r.remaining {
+		r.violated = true
+		return 0, errors.New("reader was read past its allowed boundary")
+	}
+	n, err := r.reader.Read(buffer)
+	r.bytes += int64(n)
+	r.remaining -= int64(n)
+	return n, err
+}
+
+type failingReader struct {
+	err error
+}
+
+func (r failingReader) Read([]byte) (int, error) {
+	return 0, r.err
+}
+
+func TestProviderHTTPErrorEnvelopeParsing(t *testing.T) {
+	tests := []struct {
+		name string
+		body string
+		want providerErrorDetails
+	}{
+		{
+			name: "all supported string fields",
+			body: `{"error":{"message":"diagnostic","type":"invalid_request_error","code":"unsupported_parameter"}}`,
+			want: providerErrorDetails{providerMessage: "diagnostic", providerType: "invalid_request_error", providerCode: "unsupported_parameter"},
+		},
+		{
+			name: "integer code",
+			body: `{"error":{"code":17}}`,
+			want: providerErrorDetails{providerCode: "17"},
+		},
+		{
+			name: "fractional code",
+			body: `{"error":{"code":1.25}}`,
+			want: providerErrorDetails{providerCode: "1.25"},
+		},
+		{
+			name: "exponent code",
+			body: `{"error":{"code":6.02e+23}}`,
+			want: providerErrorDetails{providerCode: "6.02e+23"},
+		},
+		{
+			name: "invalid fields do not discard valid fields",
+			body: `{"error":{"message":null,"type":"invalid_request_error","code":false}}`,
+			want: providerErrorDetails{providerType: "invalid_request_error"},
+		},
+		{
+			name: "unknown fields are ignored",
+			body: `{"trace":"do not retain","error":{"param":"temperature","metadata":{"secret":"x"}}}`,
+			want: providerErrorDetails{},
+		},
+		{name: "missing error", body: `{}`, want: providerErrorDetails{}},
+		{name: "null error", body: `{"error":null}`, want: providerErrorDetails{}},
+		{name: "scalar error", body: `{"error":"nope"}`, want: providerErrorDetails{}},
+		{name: "empty error", body: `{"error":{}}`, want: providerErrorDetails{}},
+		{name: "malformed", body: `{"error":`, want: providerErrorDetails{}},
+		{name: "truncated", body: `{"error":{"message":"x"`, want: providerErrorDetails{}},
+		{name: "trailing garbage", body: `{"error":{"message":"x"}} garbage`, want: providerErrorDetails{}},
+		{name: "second document", body: `{"error":{"message":"x"}} {}`, want: providerErrorDetails{}},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := parseProviderErrorEnvelope([]byte(tc.body)); !reflect.DeepEqual(got, tc.want) {
+				t.Fatalf("parseProviderErrorEnvelope() = %#v, want %#v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestProviderErrorTextNormalizationAndLimits(t *testing.T) {
+	validIdentifier := strings.Repeat("界", maxProviderErrorIdentifierRunes)
+	validMessage := strings.Repeat("界", maxProviderErrorMessageRunes)
+	tests := []struct {
+		name string
+		got  string
+		want string
+	}{
+		{name: "multibyte text", got: "Grüße 世界", want: "Grüße 世界"},
+		{name: "invalid UTF-8", got: string([]byte{'a', 0xff, 'b'}), want: "a<>b"},
+		{name: "whitespace control and format runs", got: " \n\talpha\x00\u200b\u200bbeta \r ", want: "alpha beta"},
+		{name: "blank normalization", got: "\t\u200b\n", want: ""},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := normalizeProviderErrorText(tc.got); got != tc.want {
+				t.Fatalf("normalizeProviderErrorText() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+
+	if got := normalizeProviderErrorIdentifier(validIdentifier); got != validIdentifier {
+		t.Fatalf("exact identifier boundary = %q, want retained value", got)
+	}
+	if got := normalizeProviderErrorIdentifier(validIdentifier + "界"); got != "" {
+		t.Fatalf("overlong identifier = %q, want empty", got)
+	}
+	if got := normalizeProviderErrorMessage(validMessage); got != validMessage {
+		t.Fatalf("exact message boundary = %q, want retained value", got)
+	}
+	wantTruncatedMessage := strings.Repeat("界", maxProviderErrorMessageRunes-1) + "…"
+	if got := normalizeProviderErrorMessage(validMessage + "界"); got != wantTruncatedMessage {
+		t.Fatalf("overlong message length = %d, want %d", utf8.RuneCountInString(got), maxProviderErrorMessageRunes)
+	}
+}
+
+func TestProviderHTTPErrorIdentityAndFormatting(t *testing.T) {
+	const marker = "provider-secret-marker"
+	err := newProviderHTTPError(429, providerErrorDetails{
+		providerCode:    marker + "-code",
+		providerType:    marker + "-type",
+		providerMessage: marker + "-message",
+	})
+
+	if err.StatusCode() != 429 || err.ProviderCode() != marker+"-code" || err.ProviderType() != marker+"-type" || err.ProviderMessage() != marker+"-message" {
+		t.Fatalf("accessors returned unexpected values: %#v", err)
+	}
+	if !errors.Is(err, ErrUnexpectedStatus) {
+		t.Fatalf("errors.Is(%v, ErrUnexpectedStatus) = false", err)
+	}
+	for _, rendered := range []string{fmt.Sprintf("%v", err), fmt.Sprintf("%+v", err), fmt.Sprintf("%#v", err)} {
+		if rendered != "llm returned non-success status: status=429" {
+			t.Fatalf("formatted error = %q", rendered)
+		}
+		if strings.Contains(rendered, marker) {
+			t.Fatalf("formatted error exposed provider marker: %q", rendered)
+		}
+	}
+
+	var nilError *ProviderHTTPError
+	if nilError.StatusCode() != 0 || nilError.ProviderCode() != "" || nilError.ProviderType() != "" || nilError.ProviderMessage() != "" {
+		t.Fatal("nil accessors returned provider values")
+	}
+	if nilError.Error() != "llm returned non-success status" || nilError.GoString() != "llm returned non-success status" || !errors.Is(nilError, ErrUnexpectedStatus) {
+		t.Fatalf("nil error behavior is not safe: %v", nilError)
+	}
+
+	zero := &ProviderHTTPError{}
+	if zero.Error() != "llm returned non-success status" || zero.GoString() != "llm returned non-success status" || !errors.Is(zero, ErrUnexpectedStatus) {
+		t.Fatalf("zero error behavior is not safe: %v", zero)
+	}
+}
+
+func TestProviderHTTPErrorBodyBounds(t *testing.T) {
+	const (
+		statusCode = 502
+		marker     = "provider-body-marker"
+	)
+
+	ordinaryBody := `{"error":{"message":"` + marker + `"}}`
+	exactLimitBody := ordinaryBody + strings.Repeat(" ", int(maxProviderErrorResponseBytes)-len(ordinaryBody))
+	overLimitBody := ordinaryBody + strings.Repeat(" ", int(maxProviderErrorResponseBytes)+1-len(ordinaryBody))
+	tests := []struct {
+		name          string
+		contentLength int64
+		reader        io.Reader
+		wantRead      int64
+		wantMessage   string
+	}{
+		{
+			name:          "recognized envelope",
+			contentLength: int64(len(ordinaryBody)),
+			reader:        strings.NewReader(ordinaryBody),
+			wantRead:      int64(len(ordinaryBody)),
+			wantMessage:   marker,
+		},
+		{
+			name:          "exact limit",
+			contentLength: maxProviderErrorResponseBytes,
+			reader:        strings.NewReader(exactLimitBody),
+			wantRead:      maxProviderErrorResponseBytes,
+			wantMessage:   marker,
+		},
+		{
+			name:          "declared oversize does not read",
+			contentLength: maxProviderErrorResponseBytes + 1,
+			reader:        strings.NewReader(ordinaryBody),
+			wantRead:      0,
+		},
+		{
+			name:          "unknown length oversize",
+			contentLength: -1,
+			reader:        strings.NewReader(overLimitBody),
+			wantRead:      maxProviderErrorResponseBytes + 1,
+		},
+		{
+			name:          "underreported oversize",
+			contentLength: maxProviderErrorResponseBytes,
+			reader:        strings.NewReader(overLimitBody),
+			wantRead:      maxProviderErrorResponseBytes + 1,
+		},
+		{
+			name:          "read failure",
+			contentLength: -1,
+			reader:        failingReader{err: errors.New("read failure")},
+			wantRead:      0,
+		},
+		{
+			name:          "empty body",
+			contentLength: 0,
+			reader:        strings.NewReader(""),
+			wantRead:      0,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			reader := &guardedReader{
+				reader:    tc.reader,
+				remaining: maxProviderErrorResponseBytes + 1,
+			}
+			err := providerHTTPErrorFromBody(statusCode, tc.contentLength, reader)
+			if err == nil || err.StatusCode() != statusCode {
+				t.Fatalf("error status = %v, want %d", err, statusCode)
+			}
+			if reader.bytes != tc.wantRead {
+				t.Fatalf("body bytes read = %d, want %d", reader.bytes, tc.wantRead)
+			}
+			if reader.violated {
+				t.Fatal("body reader was asked to read beyond the overflow probe")
+			}
+			if got := err.ProviderMessage(); got != tc.wantMessage {
+				t.Fatalf("provider message = %q, want %q", got, tc.wantMessage)
+			}
+			if tc.wantMessage == "" {
+				if err.ProviderCode() != "" || err.ProviderType() != "" || strings.Contains(err.Error(), marker) {
+					t.Fatalf("discarded details were retained: %#v", err)
+				}
+			}
+		})
+	}
+}

internal/llm/provider_http_error_transport_test.go

@@ -0,0 +1,145 @@
+package llm
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestOpenAICompatibleClientStructuredNonSuccessResponse(t *testing.T) {
+	body := `{"error":{"message":"  provider\nmessage\u200b","type":"invalid\ttype","code":1.5e+4}}`
+	responseBody := &countingReadCloser{reader: strings.NewReader(body)}
+	client := newNonSuccessResponseClient(t, http.StatusBadRequest, int64(len(body)), responseBody)
+
+	response, err := client.Generate(context.Background(), ordinaryGenerateRequest())
+	if response != nil {
+		t.Fatalf("response = %#v, want nil", response)
+	}
+	if !errors.Is(err, ErrUnexpectedStatus) {
+		t.Fatalf("errors.Is(%v, ErrUnexpectedStatus) = false", err)
+	}
+	var providerHTTPError *ProviderHTTPError
+	if !errors.As(err, &providerHTTPError) {
+		t.Fatalf("error = %T, want *ProviderHTTPError", err)
+	}
+	if providerHTTPError.StatusCode() != http.StatusBadRequest || providerHTTPError.ProviderCode() != "1.5e+4" || providerHTTPError.ProviderType() != "invalid type" || providerHTTPError.ProviderMessage() != "provider message" {
+		t.Fatalf("provider error = %#v", providerHTTPError)
+	}
+	if !responseBody.closed {
+		t.Fatal("non-success response body was not closed")
+	}
+}
+
+func TestOpenAICompatibleClientNonSuccessBodyOwnership(t *testing.T) {
+	const marker = "provider-body-marker"
+	normalBody := `{"error":{"message":"` + marker + `"}}`
+	overLimitBody := normalBody + strings.Repeat(" ", int(maxProviderErrorResponseBytes)+1-len(normalBody))
+	tests := []struct {
+		name          string
+		contentLength int64
+		reader        io.Reader
+		wantRead      int64
+		wantMessage   string
+	}{
+		{
+			name:          "normal",
+			contentLength: int64(len(normalBody)),
+			reader:        strings.NewReader(normalBody),
+			wantRead:      int64(len(normalBody)),
+			wantMessage:   marker,
+		},
+		{
+			name:          "declared oversize",
+			contentLength: maxProviderErrorResponseBytes + 1,
+			reader:        strings.NewReader(normalBody),
+			wantRead:      0,
+		},
+		{
+			name:          "streamed oversize",
+			contentLength: -1,
+			reader: &guardedReader{
+				reader:    strings.NewReader(overLimitBody),
+				remaining: maxProviderErrorResponseBytes + 1,
+			},
+			wantRead: maxProviderErrorResponseBytes + 1,
+		},
+		{
+			name:          "underreported oversize",
+			contentLength: maxProviderErrorResponseBytes,
+			reader: &guardedReader{
+				reader:    strings.NewReader(overLimitBody),
+				remaining: maxProviderErrorResponseBytes + 1,
+			},
+			wantRead: maxProviderErrorResponseBytes + 1,
+		},
+		{
+			name:          "malformed",
+			contentLength: 1,
+			reader:        strings.NewReader("{"),
+			wantRead:      1,
+		},
+		{
+			name:          "read failure",
+			contentLength: -1,
+			reader:        failingReader{err: errors.New("response read failed")},
+			wantRead:      0,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			body := &countingReadCloser{reader: tc.reader}
+			client := newNonSuccessResponseClient(t, http.StatusBadGateway, tc.contentLength, body)
+
+			response, err := client.Generate(context.Background(), ordinaryGenerateRequest())
+			if response != nil {
+				t.Fatalf("response = %#v, want nil", response)
+			}
+			var providerHTTPError *ProviderHTTPError
+			if !errors.As(err, &providerHTTPError) {
+				t.Fatalf("error = %T, want *ProviderHTTPError", err)
+			}
+			if !body.closed {
+				t.Fatal("response body was not closed")
+			}
+			if body.bytesRead != tc.wantRead {
+				t.Fatalf("body bytes read = %d, want %d", body.bytesRead, tc.wantRead)
+			}
+			if body.bytesRead > maxProviderErrorResponseBytes+1 {
+				t.Fatalf("body bytes read = %d, exceeds overflow probe", body.bytesRead)
+			}
+			if guarded, ok := tc.reader.(*guardedReader); ok && guarded.violated {
+				t.Fatal("body reader was asked to read beyond the overflow probe")
+			}
+			if got := providerHTTPError.ProviderMessage(); got != tc.wantMessage {
+				t.Fatalf("provider message = %q, want %q", got, tc.wantMessage)
+			}
+			if tc.wantMessage == "" && (providerHTTPError.ProviderCode() != "" || providerHTTPError.ProviderType() != "" || strings.Contains(providerHTTPError.Error(), marker)) {
+				t.Fatalf("discarded details were retained: %#v", providerHTTPError)
+			}
+		})
+	}
+}
+
+func newNonSuccessResponseClient(t *testing.T, statusCode int, contentLength int64, body io.ReadCloser) *OpenAICompatibleClient {
+	t.Helper()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{
+		BaseURL: "https://provider.example/v1",
+		Model:   "m",
+		HTTPClient: &http.Client{Transport: roundTripFunc(func(*http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode:    statusCode,
+				ContentLength: contentLength,
+				Body:          body,
+			}, nil
+		})},
+	})
+	if err != nil {
+		t.Fatalf("construct client: %v", err)
+	}
+	return client
+}

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

@@ -0,0 +1,3 @@
+id: rakestrawhome-gemma-4-31b
+backend: rakestrawhome
+model: google/gemma-4-31b-it

internal/profile/builtin/repository_test.go

@@ -26,8 +26,8 @@ func TestBuiltInProfilesValidateThroughRepository(t *testing.T) {
 			if p.ID != id {
 				t.Fatalf("expected profile id %q, got %q", id, p.ID)
 			}
-			if p.BackendID != backend.OpenRouterID {
+			if !builtInBackendIDs[p.BackendID] {
-				t.Fatalf("expected profile %q to select %q, got %q", id, backend.OpenRouterID, p.BackendID)
+				t.Fatalf("expected profile %q to select a maintained built-in, got %q", id, p.BackendID)
 			}
 			if p.Endpoint != "" || p.APIKeyEnv != "" {
 				t.Fatalf("expected profile %q to inherit backend connection settings, got endpoint=%q api_key_env=%q", id, p.Endpoint, p.APIKeyEnv)
@@ -40,6 +40,33 @@ func TestBuiltInProfilesDoNotContainDuplicateIDsOrRawAPIKeys(t *testing.T) {
 	loadBuiltInProfileIDs(t)
 }
 
+func TestRakestrawhomeGemmaProfileUsesNativeDefaults(t *testing.T) {
+	p, err := NewRepository().GetProfile(context.Background(), "rakestrawhome-gemma-4-31b")
+	if err != nil {
+		t.Fatalf("load Rakestrawhome Gemma profile: %v", err)
+	}
+	if p.ID != "rakestrawhome-gemma-4-31b" ||
+		p.BackendID != backend.RakestrawHomeID ||
+		p.Model != "google/gemma-4-31b-it" ||
+		p.Endpoint != "" ||
+		p.Temperature != 0 ||
+		p.MaxTokens != 0 ||
+		p.TopP != 0 ||
+		p.TimeoutSeconds != 0 ||
+		p.ServiceTier != "" ||
+		p.ReasoningEffort != "" ||
+		p.APIKeyEnv != "" ||
+		p.APIKeyRequired ||
+		p.ExtraParams != nil {
+		t.Fatalf("unexpected Rakestrawhome Gemma profile: %#v", p)
+	}
+}
+
+var builtInBackendIDs = map[string]bool{
+	backend.OpenRouterID:    true,
+	backend.RakestrawHomeID: true,
+}
+
 func loadBuiltInProfileIDs(t *testing.T) map[string]string {
 	t.Helper()
 
@@ -64,8 +91,9 @@ func loadBuiltInProfileIDs(t *testing.T) map[string]string {
 		if _, ok := raw["api_key"]; ok {
 			t.Fatalf("built-in profile %s contains raw api_key", name)
 		}
-		if raw["backend"] != backend.OpenRouterID {
+		backendID, ok := raw["backend"].(string)
-			t.Fatalf("built-in profile %s does not select %q", name, backend.OpenRouterID)
+		if !ok || !builtInBackendIDs[backendID] {
+			t.Fatalf("built-in profile %s does not select a maintained built-in: %#v", name, raw["backend"])
 		}
 		if _, ok := raw["endpoint"]; ok {
 			t.Fatalf("built-in profile %s repeats endpoint", name)

internal/profile/definition.go

@@ -0,0 +1,47 @@
+package profile
+
+import (
+	"errors"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/promptkit/internal/domain"
+)
+
+// NormalizeAndValidateDefinition normalizes and validates one source-local
+// profile definition without resolving a base profile.
+func NormalizeAndValidateDefinition(profile *domain.ExecutionProfile) error {
+	if profile == nil {
+		return errors.New("profile is required")
+	}
+
+	profile.ID = strings.TrimSpace(profile.ID)
+	profile.BaseProfileID = strings.TrimSpace(profile.BaseProfileID)
+	profile.BackendID = strings.TrimSpace(profile.BackendID)
+	profile.Endpoint = strings.TrimSpace(profile.Endpoint)
+
+	if profile.ID == "" {
+		return errors.New("id is required")
+	}
+	if profile.Endpoint != "" {
+		endpoint, err := domain.NormalizeOpenAICompatibleBaseEndpoint(profile.Endpoint)
+		if err != nil {
+			return err
+		}
+		profile.Endpoint = endpoint
+	}
+	if profile.BaseProfileID == "" {
+		if profile.BackendID == "" && profile.Endpoint == "" {
+			return errors.New("backend or endpoint is required")
+		}
+		if strings.TrimSpace(profile.Model) == "" {
+			return errors.New("model is required")
+		}
+	}
+
+	return domain.ValidateExecutionTargetSettings(domain.ExecutionTarget{
+		Temperature:    profile.Temperature,
+		MaxTokens:      profile.MaxTokens,
+		TopP:           profile.TopP,
+		TimeoutSeconds: profile.TimeoutSeconds,
+	})
+}

internal/profile/filesystem_repository.go

@@ -127,12 +127,11 @@ func loadProfile(ctx context.Context, fsys fs.FS, root string, id string) (*doma
 		if prof.ID != id {
 			continue
 		}
-		prof.BackendID = strings.TrimSpace(prof.BackendID)
 		prof.ExtraParams, err = jsonvalue.CopyMap(prof.ExtraParams)
 		if err != nil {
 			return nil, fmt.Errorf("%w: %s: %v", ErrInvalidProfile, relPath, err)
 		}
-		if err := normalizeAndValidateProfile(prof); err != nil {
+		if err := NormalizeAndValidateDefinition(prof); err != nil {
 			if errors.Is(err, ErrRawAPIKeyNotAllowed) {
 				return nil, fmt.Errorf("%w: %s", err, relPath)
 			}
@@ -255,30 +254,3 @@ func requireYAMLStreamEnd(decoder *yaml.Decoder) error {
 	}
 	return errors.New("profile file must contain exactly one YAML document")
 }
-
-func normalizeAndValidateProfile(p *domain.ExecutionProfile) error {
-	if strings.TrimSpace(p.ID) == "" {
-		return errors.New("id is required")
-	}
-	p.Endpoint = strings.TrimSpace(p.Endpoint)
-	if strings.TrimSpace(p.BackendID) == "" && p.Endpoint == "" {
-		return errors.New("backend or endpoint is required")
-	}
-	if p.Endpoint != "" {
-		endpoint, err := domain.NormalizeOpenAICompatibleBaseEndpoint(p.Endpoint)
-		if err != nil {
-			return err
-		}
-		p.Endpoint = endpoint
-	}
-	if strings.TrimSpace(p.Model) == "" {
-		return errors.New("model is required")
-	}
-
-	return domain.ValidateExecutionTargetSettings(domain.ExecutionTarget{
-		Temperature:    p.Temperature,
-		MaxTokens:      p.MaxTokens,
-		TopP:           p.TopP,
-		TimeoutSeconds: p.TimeoutSeconds,
-	})
-}

internal/profile/repository_test.go

@@ -858,6 +858,107 @@ top_p: .inf
 	})
 }
 
+func TestProfileRepositoriesValidateDerivedDefinitions(t *testing.T) {
+	tests := []struct {
+		name        string
+		files       map[string]string
+		wantError   error
+		wantBaseID  string
+		wantProfile bool
+	}{
+		{
+			name: "alias is locally valid and normalizes base id",
+			files: map[string]string{"alias.yaml": `
+id: selected-profile
+base_profile: "  base-profile  "
+`},
+			wantBaseID:  "base-profile",
+			wantProfile: true,
+		},
+		{
+			name: "derived endpoint remains valid",
+			files: map[string]string{"invalid.yaml": `
+id: selected-profile
+base_profile: base-profile
+endpoint: /v1
+`},
+			wantError: ErrInvalidProfile,
+		},
+		{
+			name: "derived settings remain valid",
+			files: map[string]string{"invalid.yaml": `
+id: selected-profile
+base_profile: base-profile
+top_p: 1.1
+`},
+			wantError: ErrInvalidProfile,
+		},
+		{
+			name: "derived extra params remain valid",
+			files: map[string]string{"invalid.yaml": `
+id: selected-profile
+base_profile: base-profile
+extra_params:
+  timestamp: 2026-08-11T12:34:56Z
+`},
+			wantError: ErrInvalidProfile,
+		},
+		{
+			name: "derived raw key remains prohibited",
+			files: map[string]string{"invalid.yaml": `
+id: selected-profile
+base_profile: base-profile
+api_key: secret
+`},
+			wantError: ErrRawAPIKeyNotAllowed,
+		},
+		{
+			name: "derived duplicate id remains invalid",
+			files: map[string]string{
+				"first.yaml":  "id: selected-profile\nbase_profile: first-base\n",
+				"second.yaml": "id: selected-profile\nbase_profile: second-base\n",
+			},
+			wantError: ErrInvalidProfile,
+		},
+		{
+			name: "derived extra document remains invalid",
+			files: map[string]string{"invalid.yaml": `
+id: selected-profile
+base_profile: base-profile
+---
+id: other
+`},
+			wantError: ErrInvalidYAML,
+		},
+		{
+			name:      "standalone profile remains complete",
+			files:     map[string]string{"invalid.yaml": "id: selected-profile\n"},
+			wantError: ErrInvalidProfile,
+		},
+	}
+
+	for _, source := range profileRepositorySources() {
+		for _, tc := range tests {
+			t.Run(source.name+"/"+tc.name, func(t *testing.T) {
+				repo := source.newRepository(t, tc.files)
+				got, err := repo.GetProfile(context.Background(), "selected-profile")
+				if tc.wantError != nil {
+					if !errors.Is(err, tc.wantError) {
+						t.Fatalf("error = %v, want %v", err, tc.wantError)
+					}
+					return
+				}
+				if err != nil || !tc.wantProfile {
+					t.Fatalf("profile = %+v, error = %v, want valid derived definition", got, err)
+				}
+				if got.BaseProfileID != tc.wantBaseID {
+					t.Fatalf("BaseProfileID = %q, want %q", got.BaseProfileID, tc.wantBaseID)
+				}
+			})
+		}
+	}
+}
+
 func TestOverlayRepository(t *testing.T) {
 	ctx := context.Background()
 	primaryProfile := &domain.ExecutionProfile{ID: "shared", Endpoint: "http://primary", Model: "primary"}

internal/profile/resolving_repository.go

@@ -0,0 +1,160 @@
+package profile
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/promptkit/internal/domain"
+	"gitea.maximumdirect.net/eric/promptkit/internal/jsonvalue"
+)
+
+const maximumProfileChainLength = 32
+
+type resolvingRepository struct {
+	source Repository
+}
+
+// NewResolvingRepository resolves inherited profile definitions from source.
+func NewResolvingRepository(source Repository) Repository {
+	return &resolvingRepository{source: source}
+}
+
+func (r *resolvingRepository) GetProfile(ctx context.Context, id string) (*domain.ExecutionProfile, error) {
+	if r == nil || r.source == nil {
+		return nil, fmt.Errorf("%w: profile repository is required", ErrInvalidProfile)
+	}
+	requestedID := strings.TrimSpace(id)
+	if requestedID == "" {
+		return nil, fmt.Errorf("%w: profile id is required", ErrInvalidProfile)
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+
+	profile, err := r.getRawProfile(ctx, requestedID)
+	if err != nil {
+		return nil, err
+	}
+	if profile == nil {
+		return nil, fmt.Errorf("%w: selected profile %q is nil", ErrInvalidProfile, requestedID)
+	}
+
+	chain := []*domain.ExecutionProfile{profile}
+	chainIDs := []string{requestedID}
+	visited := map[string]struct{}{requestedID: {}}
+	current := profile
+
+	for {
+		baseID := strings.TrimSpace(current.BaseProfileID)
+		if baseID == "" {
+			break
+		}
+		if err := ctx.Err(); err != nil {
+			return nil, err
+		}
+		if _, seen := visited[baseID]; seen {
+			return nil, fmt.Errorf("%w: profile inheritance cycle %s", ErrInvalidProfile, joinProfileChain(chainIDs, baseID))
+		}
+		if len(chain) >= maximumProfileChainLength {
+			return nil, fmt.Errorf("%w: profile inheritance chain exceeds %d profiles: %s", ErrInvalidProfile, maximumProfileChainLength, joinProfileChain(chainIDs, baseID))
+		}
+
+		base, err := r.getRawProfile(ctx, baseID)
+		if err != nil {
+			if errors.Is(err, ErrProfileNotFound) {
+				return nil, fmt.Errorf("%w: base profile %q is missing in chain %s", ErrInvalidProfile, baseID, joinProfileChain(chainIDs, baseID))
+			}
+			return nil, fmt.Errorf("%w: failed to load base profile %q in chain %s: %w", ErrInvalidProfile, baseID, joinProfileChain(chainIDs, baseID), err)
+		}
+		if base == nil {
+			return nil, fmt.Errorf("%w: base profile %q is nil in chain %s", ErrInvalidProfile, baseID, joinProfileChain(chainIDs, baseID))
+		}
+
+		chain = append(chain, base)
+		chainIDs = append(chainIDs, baseID)
+		visited[baseID] = struct{}{}
+		current = base
+	}
+
+	resolved, err := mergeProfileChain(chain)
+	if err != nil {
+		return nil, fmt.Errorf("%w: resolved profile chain %s: %w", ErrInvalidProfile, strings.Join(chainIDs, " -> "), err)
+	}
+	if err := validateResolvedProfile(resolved); err != nil {
+		return nil, fmt.Errorf("%w: resolved profile chain %s: %w", ErrInvalidProfile, strings.Join(chainIDs, " -> "), err)
+	}
+	return resolved, nil
+}
+
+func (r *resolvingRepository) getRawProfile(ctx context.Context, id string) (*domain.ExecutionProfile, error) {
+	profile, err := r.source.GetProfile(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	return profile, nil
+}
+
+func joinProfileChain(chain []string, next string) string {
+	return strings.Join(append(append([]string(nil), chain...), next), " -> ")
+}
+
+func mergeProfileChain(chain []*domain.ExecutionProfile) (*domain.ExecutionProfile, error) {
+	resolved := &domain.ExecutionProfile{ID: chain[0].ID}
+	for index := len(chain) - 1; index >= 0; index-- {
+		definition := chain[index]
+		if strings.TrimSpace(definition.BackendID) != "" {
+			resolved.BackendID = definition.BackendID
+		}
+		if strings.TrimSpace(definition.Endpoint) != "" {
+			resolved.Endpoint = definition.Endpoint
+		}
+		if strings.TrimSpace(definition.Model) != "" {
+			resolved.Model = definition.Model
+		}
+		if definition.Temperature != 0 {
+			resolved.Temperature = definition.Temperature
+		}
+		if definition.MaxTokens != 0 {
+			resolved.MaxTokens = definition.MaxTokens
+		}
+		if definition.TopP != 0 {
+			resolved.TopP = definition.TopP
+		}
+		if definition.TimeoutSeconds != 0 {
+			resolved.TimeoutSeconds = definition.TimeoutSeconds
+		}
+		if strings.TrimSpace(definition.ServiceTier) != "" {
+			resolved.ServiceTier = definition.ServiceTier
+		}
+		if strings.TrimSpace(definition.ReasoningEffort) != "" {
+			resolved.ReasoningEffort = definition.ReasoningEffort
+		}
+		if strings.TrimSpace(definition.APIKeyEnv) != "" {
+			resolved.APIKeyEnv = definition.APIKeyEnv
+		}
+		resolved.APIKeyRequired = resolved.APIKeyRequired || definition.APIKeyRequired
+		if len(definition.ExtraParams) != 0 {
+			extraParams, err := jsonvalue.CopyMap(definition.ExtraParams)
+			if err != nil {
+				return nil, err
+			}
+			resolved.ExtraParams = extraParams
+		}
+	}
+	resolved.ID = chain[0].ID
+	resolved.BaseProfileID = ""
+	return resolved, nil
+}
+
+func validateResolvedProfile(profile *domain.ExecutionProfile) error {
+	if profile == nil {
+		return errors.New("resolved profile is required")
+	}
+	profile.BaseProfileID = ""
+	return NormalizeAndValidateDefinition(profile)
+}

internal/profile/resolving_repository_test.go

@@ -0,0 +1,418 @@
+package profile
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io/fs"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"testing/fstest"
+
+	"gitea.maximumdirect.net/eric/promptkit/internal/domain"
+)
+
+func TestResolvingRepositoryMergesProfileChain(t *testing.T) {
+	repo := &resolvingTestRepository{profiles: map[string]*domain.ExecutionProfile{
+		"leaf": {
+			ID:              "leaf",
+			BaseProfileID:   "middle",
+			BackendID:       "leaf-backend",
+			TopP:            0.8,
+			TimeoutSeconds:  45,
+			ReasoningEffort: "high",
+		},
+		"middle": {
+			ID:             "middle",
+			BaseProfileID:  "root",
+			Endpoint:       "https://middle.example/v1",
+			Model:          "middle-model",
+			MaxTokens:      256,
+			APIKeyEnv:      "MIDDLE_API_KEY",
+			APIKeyRequired: true,
+			ExtraParams:    map[string]any{"middle": map[string]any{"value": "middle"}},
+		},
+		"root": {
+			ID:          "root",
+			BackendID:   "root-backend",
+			Endpoint:    "https://root.example/v1",
+			Model:       "root-model",
+			Temperature: 0.3,
+			ServiceTier: "priority",
+			ExtraParams: map[string]any{"root": "value"},
+		},
+	}}
+
+	got, err := NewResolvingRepository(repo).GetProfile(context.Background(), "leaf")
+	if err != nil {
+		t.Fatalf("resolve profile: %v", err)
+	}
+	want := &domain.ExecutionProfile{
+		ID:              "leaf",
+		BackendID:       "leaf-backend",
+		Endpoint:        "https://middle.example/v1",
+		Model:           "middle-model",
+		Temperature:     0.3,
+		MaxTokens:       256,
+		TopP:            0.8,
+		TimeoutSeconds:  45,
+		ServiceTier:     "priority",
+		ReasoningEffort: "high",
+		APIKeyEnv:       "MIDDLE_API_KEY",
+		APIKeyRequired:  true,
+		ExtraParams:     map[string]any{"middle": map[string]any{"value": "middle"}},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("resolved profile:\n got %#v\nwant %#v", got, want)
+	}
+}
+
+func TestResolvingRepositoryRejectsMissingSourceAndProfileID(t *testing.T) {
+	if _, err := NewResolvingRepository(nil).GetProfile(context.Background(), "profile"); !errors.Is(err, ErrInvalidProfile) {
+		t.Fatalf("nil source error = %v, want ErrInvalidProfile", err)
+	}
+
+	repo := &resolvingTestRepository{profiles: map[string]*domain.ExecutionProfile{}}
+	if _, err := NewResolvingRepository(repo).GetProfile(context.Background(), " \t "); !errors.Is(err, ErrInvalidProfile) {
+		t.Fatalf("blank id error = %v, want ErrInvalidProfile", err)
+	}
+	if got := repo.callCount(" "); got != 0 {
+		t.Fatalf("blank id looked up source %d times", got)
+	}
+}
+
+func TestResolvingRepositoryCopiesExtraParams(t *testing.T) {
+	baseParams := map[string]any{"nested": map[string]any{"value": "base"}}
+	repo := &resolvingTestRepository{profiles: map[string]*domain.ExecutionProfile{
+		"child": {ID: "child", BaseProfileID: "base"},
+		"base": {
+			ID:          "base",
+			Endpoint:    "https://base.example/v1",
+			Model:       "model",
+			ExtraParams: baseParams,
+		},
+	}}
+	resolver := NewResolvingRepository(repo)
+
+	first, err := resolver.GetProfile(context.Background(), "child")
+	if err != nil {
+		t.Fatalf("resolve inherited map: %v", err)
+	}
+	first.ExtraParams["nested"].(map[string]any)["value"] = "mutated"
+	second, err := resolver.GetProfile(context.Background(), "child")
+	if err != nil {
+		t.Fatalf("resolve inherited map again: %v", err)
+	}
+	if got := second.ExtraParams["nested"].(map[string]any)["value"]; got != "base" {
+		t.Fatalf("later result retained mutation: %v", got)
+	}
+	if got := baseParams["nested"].(map[string]any)["value"]; got != "base" {
+		t.Fatalf("source map retained mutation: %v", got)
+	}
+
+	repo.set("child", &domain.ExecutionProfile{
+		ID:            "child",
+		BaseProfileID: "base",
+		ExtraParams:   map[string]any{"child": "replacement"},
+	})
+	replaced, err := resolver.GetProfile(context.Background(), "child")
+	if err != nil {
+		t.Fatalf("resolve replacement map: %v", err)
+	}
+	if !reflect.DeepEqual(replaced.ExtraParams, map[string]any{"child": "replacement"}) {
+		t.Fatalf("extra params = %#v, want complete child replacement", replaced.ExtraParams)
+	}
+}
+
+func TestResolvingRepositoryUsesRawOverlayForEachLookup(t *testing.T) {
+	leafSource := NewFSRepository(profileTestFS(map[string]string{
+		"leaf.yaml": "id: leaf\nbase_profile: base\n",
+	}), ".")
+	fallback := NewFSRepository(profileTestFS(map[string]string{
+		"base.yaml": "id: base\nendpoint: https://fallback.example/v1\nmodel: fallback-model\n",
+	}), ".")
+	overlay := NewOverlayRepository(leafSource, fallback)
+	resolver := NewResolvingRepository(overlay)
+
+	got, err := resolver.GetProfile(context.Background(), "leaf")
+	if err != nil {
+		t.Fatalf("resolve fallback base: %v", err)
+	}
+	if got.Model != "fallback-model" {
+		t.Fatalf("fallback base model = %q", got.Model)
+	}
+
+	shadowing := NewOverlayRepository(NewFSRepository(profileTestFS(map[string]string{
+		"leaf.yaml": "id: leaf\nbase_profile: base\n",
+		"base.yaml": "id: base\nendpoint: https://primary.example/v1\nmodel: primary-model\n",
+	}), "."), fallback)
+	got, err = NewResolvingRepository(shadowing).GetProfile(context.Background(), "leaf")
+	if err != nil {
+		t.Fatalf("resolve shadowed base: %v", err)
+	}
+	if got.Model != "primary-model" || got.Endpoint != "https://primary.example/v1" {
+		t.Fatalf("shadowed base = %+v", got)
+	}
+}
+
+func TestResolvingRepositoryReportsSafetyAndSourceErrors(t *testing.T) {
+	sourceErr := errors.New("source failure")
+	tests := []struct {
+		name     string
+		repo     *resolvingTestRepository
+		id       string
+		want     []error
+		wantNot  error
+		contains []string
+	}{
+		{
+			name:    "missing selected profile preserves not found",
+			repo:    &resolvingTestRepository{profiles: map[string]*domain.ExecutionProfile{}},
+			id:      "missing",
+			want:    []error{ErrProfileNotFound},
+			wantNot: ErrInvalidProfile,
+		},
+		{
+			name: "missing base is invalid but not not found",
+			repo: &resolvingTestRepository{profiles: map[string]*domain.ExecutionProfile{
+				"leaf": {ID: "leaf", BaseProfileID: "missing"},
+			}},
+			id:       "leaf",
+			want:     []error{ErrInvalidProfile},
+			wantNot:  ErrProfileNotFound,
+			contains: []string{"missing", "leaf -> missing"},
+		},
+		{
+			name: "direct cycle",
+			repo: &resolvingTestRepository{profiles: map[string]*domain.ExecutionProfile{
+				"a": {ID: "a", BaseProfileID: "a"},
+			}},
+			id:       "a",
+			want:     []error{ErrInvalidProfile},
+			contains: []string{"a -> a"},
+		},
+		{
+			name: "indirect cycle",
+			repo: &resolvingTestRepository{profiles: map[string]*domain.ExecutionProfile{
+				"a": {ID: "a", BaseProfileID: "b"},
+				"b": {ID: "b", BaseProfileID: "c"},
+				"c": {ID: "c", BaseProfileID: "a"},
+			}},
+			id:       "a",
+			want:     []error{ErrInvalidProfile},
+			contains: []string{"a -> b -> c -> a"},
+		},
+		{
+			name: "nil result",
+			repo: &resolvingTestRepository{profiles: map[string]*domain.ExecutionProfile{
+				"leaf": nil,
+			}},
+			id:   "leaf",
+			want: []error{ErrInvalidProfile},
+		},
+		{
+			name: "incomplete resolved profile",
+			repo: &resolvingTestRepository{profiles: map[string]*domain.ExecutionProfile{
+				"leaf": {ID: "leaf", BaseProfileID: "base"},
+				"base": {ID: "base", Model: "model"},
+			}},
+			id:   "leaf",
+			want: []error{ErrInvalidProfile},
+		},
+		{
+			name: "base source error is retained",
+			repo: &resolvingTestRepository{
+				profiles: map[string]*domain.ExecutionProfile{"leaf": {ID: "leaf", BaseProfileID: "base"}},
+				errors:   map[string]error{"base": sourceErr},
+			},
+			id:   "leaf",
+			want: []error{ErrInvalidProfile, sourceErr},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := NewResolvingRepository(tc.repo).GetProfile(context.Background(), tc.id)
+			for _, want := range tc.want {
+				if !errors.Is(err, want) {
+					t.Fatalf("error = %v, want %v", err, want)
+				}
+			}
+			if tc.wantNot != nil && errors.Is(err, tc.wantNot) {
+				t.Fatalf("error = %v, must not match %v", err, tc.wantNot)
+			}
+			for _, fragment := range tc.contains {
+				if !strings.Contains(err.Error(), fragment) {
+					t.Fatalf("error = %v, want %q", err, fragment)
+				}
+			}
+		})
+	}
+}
+
+func TestResolvingRepositoryEnforcesChainLength(t *testing.T) {
+	for _, count := range []int{maximumProfileChainLength, maximumProfileChainLength + 1} {
+		t.Run(fmt.Sprintf("%d profiles", count), func(t *testing.T) {
+			profiles := make(map[string]*domain.ExecutionProfile, count)
+			for index := 1; index <= count; index++ {
+				id := fmt.Sprintf("profile-%d", index)
+				definition := &domain.ExecutionProfile{ID: id}
+				if index == count {
+					definition.Endpoint = "https://root.example/v1"
+					definition.Model = "model"
+				} else {
+					definition.BaseProfileID = fmt.Sprintf("profile-%d", index+1)
+				}
+				profiles[id] = definition
+			}
+
+			got, err := NewResolvingRepository(&resolvingTestRepository{profiles: profiles}).GetProfile(context.Background(), "profile-1")
+			if count == maximumProfileChainLength {
+				if err != nil || got == nil {
+					t.Fatalf("profile = %+v, error = %v, want accepted chain", got, err)
+				}
+				return
+			}
+			if !errors.Is(err, ErrInvalidProfile) {
+				t.Fatalf("error = %v, want ErrInvalidProfile", err)
+			}
+		})
+	}
+}
+
+func TestResolvingRepositoryIsFreshAndCancellationAware(t *testing.T) {
+	repo := &resolvingTestRepository{profiles: map[string]*domain.ExecutionProfile{
+		"leaf": {ID: "leaf", BaseProfileID: "base"},
+		"base": {ID: "base", Endpoint: "https://base.example/v1", Model: "first", ExtraParams: map[string]any{"nested": map[string]any{"value": "first"}}},
+	}}
+	resolver := NewResolvingRepository(repo)
+
+	first, err := resolver.GetProfile(context.Background(), "leaf")
+	if err != nil || first.Model != "first" {
+		t.Fatalf("first result=(%+v, %v)", first, err)
+	}
+	repo.set("base", &domain.ExecutionProfile{ID: "base", Endpoint: "https://base.example/v1", Model: "second", ExtraParams: map[string]any{"nested": map[string]any{"value": "second"}}})
+	second, err := resolver.GetProfile(context.Background(), "leaf")
+	if err != nil || second.Model != "second" {
+		t.Fatalf("second result=(%+v, %v)", second, err)
+	}
+
+	canceled, cancel := context.WithCancel(context.Background())
+	cancel()
+	if _, err := resolver.GetProfile(canceled, "leaf"); !errors.Is(err, context.Canceled) {
+		t.Fatalf("canceled lookup error = %v", err)
+	}
+	if got := repo.callCount("leaf"); got != 2 {
+		t.Fatalf("calls after canceled lookup = %d, want 2", got)
+	}
+
+	duringTraversal, cancelDuringTraversal := context.WithCancel(context.Background())
+	repo.afterGet = func(id string) {
+		if id == "leaf" {
+			cancelDuringTraversal()
+		}
+	}
+	if _, err := resolver.GetProfile(duringTraversal, "leaf"); !errors.Is(err, context.Canceled) {
+		t.Fatalf("during traversal error = %v", err)
+	}
+	if got := repo.callCount("base"); got != 2 {
+		t.Fatalf("base calls after cancellation = %d, want 2", got)
+	}
+
+	terminalLookup, cancelTerminalLookup := context.WithCancel(context.Background())
+	repo.afterGet = func(id string) {
+		if id == "base" {
+			cancelTerminalLookup()
+		}
+	}
+	if _, err := resolver.GetProfile(terminalLookup, "leaf"); !errors.Is(err, context.Canceled) {
+		t.Fatalf("terminal lookup cancellation error = %v", err)
+	}
+	if got := repo.callCount("base"); got != 3 {
+		t.Fatalf("base calls after terminal cancellation = %d, want 3", got)
+	}
+
+	repo.afterGet = nil
+	var wg sync.WaitGroup
+	errors := make(chan error, 8)
+	for index := 0; index < cap(errors); index++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			resolved, err := resolver.GetProfile(context.Background(), "leaf")
+			if err != nil {
+				errors <- err
+				return
+			}
+			resolved.ExtraParams["nested"].(map[string]any)["value"] = "mutated"
+		}()
+	}
+	wg.Wait()
+	close(errors)
+	for err := range errors {
+		t.Errorf("concurrent resolution: %v", err)
+	}
+	latest, err := resolver.GetProfile(context.Background(), "leaf")
+	if err != nil || latest.ExtraParams["nested"].(map[string]any)["value"] != "second" {
+		t.Fatalf("latest result=(%+v, %v)", latest, err)
+	}
+}
+
+type resolvingTestRepository struct {
+	mu       sync.Mutex
+	profiles map[string]*domain.ExecutionProfile
+	errors   map[string]error
+	calls    map[string]int
+	afterGet func(string)
+}
+
+func (r *resolvingTestRepository) GetProfile(ctx context.Context, id string) (*domain.ExecutionProfile, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	r.mu.Lock()
+	if r.calls == nil {
+		r.calls = make(map[string]int)
+	}
+	r.calls[id]++
+	err := r.errors[id]
+	profile := r.profiles[id]
+	afterGet := r.afterGet
+	r.mu.Unlock()
+	if afterGet != nil {
+		afterGet(id)
+	}
+	if err != nil {
+		return nil, err
+	}
+	if profile == nil {
+		if _, exists := r.profiles[id]; exists {
+			return nil, nil
+		}
+		return nil, ErrProfileNotFound
+	}
+	copy := *profile
+	return &copy, nil
+}
+
+func (r *resolvingTestRepository) set(id string, profile *domain.ExecutionProfile) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.profiles[id] = profile
+}
+
+func (r *resolvingTestRepository) callCount(id string) int {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.calls[id]
+}
+
+func profileTestFS(files map[string]string) fs.FS {
+	fsys := make(fstest.MapFS, len(files))
+	for name, content := range files {
+		fsys[name] = profileMapFile(content)
+	}
+	return fsys
+}

internal/usecase/prepared_execution_test.go

@@ -3,7 +3,6 @@ package usecase
 import (
 	"context"
 	"errors"
-	"os"
 	"reflect"
 	"testing"
 
@@ -241,49 +240,76 @@ func excessivelyDeepPreparedJSONValue() any {
 	return value
 }
 
-func TestRunnerRunPreparedRechecksEnvironmentCredentialBeforeAdmission(t *testing.T) {
+func TestRunnerRunPreparedCredentialAvailabilityBeforeAdmission(t *testing.T) {
 	const environmentName = "PROMPTKIT_PREPARED_EXECUTION_TEST_KEY"
-	t.Setenv(environmentName, "available-during-preparation")
+	tests := []struct {
-
+		name           string
-	profile := defaultExecutionProfile()
+		apiKeyRequired bool
-	profile.APIKeyEnv = environmentName
+		profileEnv     bool
-	validator := &recordingValidationPreparer{plan: &recordingPreparedValidation{}}
+		overrideEnv    bool
-	admitter := &fakeRunAdmitter{}
+		wantFailure    bool
-	llmClient := &fakeLLM{resp: &domain.GenerateResponse{Content: "unexpected"}}
+	}{
-	runner := NewRunner(
+		{name: "optional environment becomes unavailable", profileEnv: true},
-		&fakePromptRepo{def: promptDef(domain.FormatText, domain.ValidationNone, 0)},
+		{
-		&fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{"exec": profile}},
+			name:           "required request environment becomes unavailable",
-		nil,
+			apiKeyRequired: true,
-		defaultArtifactReader(),
+			overrideEnv:    true,
-		defaultRenderer(),
+			wantFailure:    true,
-		llmClient,
+		},
-		validator,
-		admitter,
-	)
-	prepared, err := runner.PrepareExecution(context.Background(), domain.RunRequest{
-		PromptID:  "p",
-		ProfileID: "exec",
-		Inputs:    singleInputRef(),
-	})
-	if err != nil {
-		t.Fatalf("prepare execution: %v", err)
-	}
-	if err := os.Unsetenv(environmentName); err != nil {
-		t.Fatalf("unset credential environment: %v", err)
 	}
 
-	result, err := runner.RunPrepared(context.Background(), prepared)
+	for _, tc := range tests {
-	if result != nil {
+		t.Run(tc.name, func(t *testing.T) {
-		t.Fatalf("credential failure returned partial result: %+v", result)
+			t.Setenv(environmentName, "available-during-preparation")
-	}
+
-	if !errors.Is(err, ErrInvalidRequest) || !errors.Is(err, ErrAPIKeyEnvMissing) {
+			profile := defaultExecutionProfile()
-		t.Fatalf("credential error identities are missing: %v", err)
+			profile.APIKeyRequired = tc.apiKeyRequired
-	}
+			if tc.profileEnv {
-	if len(admitter.backendIDs) != 0 || llmClient.calls != 0 {
+				profile.APIKeyEnv = environmentName
-		t.Fatalf("credential failure reached admission or generation: admission=%v generation=%d", admitter.backendIDs, llmClient.calls)
+			}
-	}
+			validator := &recordingValidationPreparer{plan: &recordingPreparedValidation{}}
-	if _, err := runner.RunPrepared(context.Background(), prepared); !errors.Is(err, ErrInvalidRequest) {
+			admitter := &fakeRunAdmitter{}
-		t.Fatalf("credential failure did not consume execution: %v", err)
+			llmClient := &fakeLLM{resp: &domain.GenerateResponse{Content: "ok"}}
+			runner := NewRunner(
+				&fakePromptRepo{def: promptDef(domain.FormatText, domain.ValidationNone, 0)},
+				&fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{"exec": profile}},
+				nil,
+				defaultArtifactReader(),
+				defaultRenderer(),
+				llmClient,
+				validator,
+				admitter,
+			)
+			request := domain.RunRequest{PromptID: "p", ProfileID: "exec", Inputs: singleInputRef()}
+			if tc.overrideEnv {
+				request.Execution = &domain.ExecutionTargetOverride{APIKeyEnv: environmentName}
+			}
+			prepared, err := runner.PrepareExecution(context.Background(), request)
+			if err != nil {
+				t.Fatalf("prepare execution: %v", err)
+			}
+			t.Setenv(environmentName, "")
+
+			result, err := runner.RunPrepared(context.Background(), prepared)
+			if tc.wantFailure {
+				if result != nil || !errors.Is(err, ErrInvalidRequest) || !errors.Is(err, ErrAPIKeyEnvMissing) {
+					t.Fatalf("required credential result = (%+v, %v)", result, err)
+				}
+				if len(admitter.backendIDs) != 0 || llmClient.calls != 0 {
+					t.Fatalf("required credential reached admission or generation: admission=%v generation=%d", admitter.backendIDs, llmClient.calls)
+				}
+			} else {
+				if result == nil || err != nil {
+					t.Fatalf("optional credential result = (%+v, %v), want success", result, err)
+				}
+				if len(admitter.backendIDs) != 1 || llmClient.calls != 1 {
+					t.Fatalf("optional credential admission=%v generation=%d, want one each", admitter.backendIDs, llmClient.calls)
+				}
+			}
+			if _, err := runner.RunPrepared(context.Background(), prepared); !errors.Is(err, ErrInvalidRequest) {
+				t.Fatalf("execution outcome did not consume handle: %v", err)
+			}
+		})
 	}
 }
 

internal/usecase/runner.go

@@ -624,12 +624,12 @@ func validateAPIKey(apiKeyEnv string, apiKey string, apiKeyRequired bool) error
 	if strings.TrimSpace(apiKey) != "" {
 		return nil
 	}
+	if !apiKeyRequired {
+		return nil
+	}
 	envName := strings.TrimSpace(apiKeyEnv)
 	if envName == "" {
-		if apiKeyRequired {
+		return ErrAPIKeyRequired
-			return ErrAPIKeyRequired
-		}
-		return nil
 	}
 	if strings.TrimSpace(os.Getenv(envName)) == "" {
 		return fmt.Errorf("%w: api key environment variable %q is not set", ErrAPIKeyEnvMissing, envName)

internal/usecase/runner_test.go

@@ -1787,22 +1787,26 @@ func TestRunnerRunAPIKeyEnvResolvesFromEnvironment(t *testing.T) {
 	}
 }
 
-func TestRunnerRunAPIKeyEnvMissingEnvironmentValueFailsClearly(t *testing.T) {
+func TestRunnerRunOptionalAPIKeyEnvMissingEnvironmentValueReachesLLM(t *testing.T) {
+	const environmentName = "PROMPTKIT_MISSING_KEY"
+	t.Setenv(environmentName, "")
+
 	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: "PROMPTKIT_MISSING_KEY"},
+		"exec": {ID: "exec", Endpoint: "http://profile/v1", Model: "profile-model", APIKeyEnv: environmentName},
 	}}
-	runner := NewRunner(promptRepo, execRepo, nil, defaultArtifactReader(), defaultRenderer(), &fakeLLM{resp: &domain.GenerateResponse{Content: "ok"}}, nil, nil)
+	llmClient := &fakeLLM{resp: &domain.GenerateResponse{Content: "ok"}}
+	runner := NewRunner(promptRepo, execRepo, nil, defaultArtifactReader(), defaultRenderer(), llmClient, nil, nil)
 
-	_, err := runner.Run(context.Background(), domain.RunRequest{PromptID: "p", ProfileID: "exec", Inputs: singleInputRef()})
+	result, err := runner.Run(context.Background(), domain.RunRequest{PromptID: "p", ProfileID: "exec", Inputs: singleInputRef()})
-	if !errors.Is(err, ErrInvalidRequest) {
+	if err != nil || result == nil {
-		t.Fatalf("expected ErrInvalidRequest, got %v", err)
+		t.Fatalf("optional credential run = (%+v, %v), want success", result, err)
 	}
-	if !errors.Is(err, ErrAPIKeyEnvMissing) {
+	if llmClient.calls != 1 {
-		t.Fatalf("expected ErrAPIKeyEnvMissing, got %v", err)
+		t.Fatalf("LLM calls = %d, want 1", llmClient.calls)
 	}
-	if !strings.Contains(err.Error(), "PROMPTKIT_MISSING_KEY") {
+	if llmClient.lastReq.Target.APIKeyEnv != environmentName {
-		t.Fatalf("expected missing env name in error, got %v", err)
+		t.Fatalf("LLM api_key_env = %q, want %q", llmClient.lastReq.Target.APIKeyEnv, environmentName)
 	}
 }
 

prepared_execution_contract_test.go

@@ -5,7 +5,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"os"
 	"reflect"
 	"strings"
 	"sync"
@@ -524,19 +523,25 @@ func TestPreparedExecutionCredentialCapacityAndTimingBoundaries(t *testing.T) {
 		engine, err := promptkit.NewEngine(
 			promptkit.Config{},
 			promptkit.WithPromptFS(contractPromptFS("prepared", "profile", "content"), "."),
-			promptkit.WithProfileFS(preparedCredentialProfileSource(environmentName), "."),
+			promptkit.WithProfiles(promptkit.Profile{
+				ID:             "profile",
+				Endpoint:       "http://example.test/v1",
+				Model:          "model",
+				APIKeyRequired: true,
+			}),
 			promptkit.WithLLMClient(client),
 		)
 		if err != nil {
 			t.Fatalf("construct credential engine: %v", err)
 		}
-		prepared, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{PromptID: "prepared"})
+		prepared, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
+			PromptID:  "prepared",
+			Execution: &promptkit.ExecutionTargetOverride{APIKeyEnv: environmentName},
+		})
 		if err != nil {
 			t.Fatalf("prepare credential execution: %v", err)
 		}
-		if err := os.Unsetenv(environmentName); err != nil {
+		t.Setenv(environmentName, "")
-			t.Fatalf("unset credential environment: %v", err)
-		}
 
 		result, err := engine.RunPrepared(context.Background(), prepared)
 		if result != nil ||
@@ -755,16 +760,6 @@ model: ` + model + `
 	}
 }
 
-func preparedCredentialProfileSource(environmentName string) fstest.MapFS {
-	return fstest.MapFS{
-		"profile.yaml": &fstest.MapFile{Data: []byte(`id: profile
-endpoint: http://example.test/v1
-model: model
-api_key_env: ` + environmentName + `
-`)},
-	}
-}
-
 func preparedSchemaSource() fstest.MapFS {
 	return fstest.MapFS{
 		"schema.json": &fstest.MapFile{Data: []byte(`{

profile_inheritance_contract_test.go

@@ -0,0 +1,243 @@
+package promptkit_test
+
+import (
+	"context"
+	"errors"
+	"io/fs"
+	"strings"
+	"sync"
+	"testing"
+	"testing/fstest"
+
+	"gitea.maximumdirect.net/eric/promptkit"
+)
+
+func TestProfileInheritanceBuiltInAliasWorkflow(t *testing.T) {
+	engine, err := promptkit.NewEngine(promptkit.Config{
+		PromptDir: frameworkPromptDir,
+		SchemaDir: frameworkSchemaDir,
+	}, promptkit.WithProfiles(promptkit.Profile{
+		ID:              "weather-light",
+		BaseProfileID:   "deepseek-4-flash",
+		ReasoningEffort: "high",
+		TimeoutSeconds:  120,
+	}))
+	if err != nil {
+		t.Fatalf("construct alias engine: %v", err)
+	}
+
+	base, err := engine.InspectProfile(context.Background(), "deepseek-4-flash")
+	if err != nil {
+		t.Fatalf("inspect base: %v", err)
+	}
+	child, err := engine.InspectProfile(context.Background(), "weather-light")
+	if err != nil {
+		t.Fatalf("inspect alias: %v", err)
+	}
+	if child.ProfileID != "weather-light" ||
+		child.EffectiveModelParams.BackendID != base.EffectiveModelParams.BackendID ||
+		child.EffectiveModelParams.Model != base.EffectiveModelParams.Model ||
+		child.EffectiveModelParams.ReasoningEffort != "high" ||
+		child.EffectiveModelParams.TimeoutSeconds != 120 {
+		t.Fatalf("alias inspection = %+v, base = %+v", child, base)
+	}
+
+	prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{
+		PromptID:  frameworkMarkdownSummaryPromptID,
+		ProfileID: "weather-light",
+		Inputs: map[string]promptkit.ArtifactRef{
+			"transcript": promptkit.Inline("Rin opens the gate."),
+			"glossary":   promptkit.Inline("gate: A guarded passage."),
+		},
+	})
+	if err != nil {
+		t.Fatalf("prepare alias: %v", err)
+	}
+	if prepared.SelectedProfileID != "weather-light" {
+		t.Fatalf("SelectedProfileID = %q", prepared.SelectedProfileID)
+	}
+
+	timeout := 15
+	reasoning := "low"
+	overridden, err := engine.Prepare(context.Background(), promptkit.RunRequest{
+		PromptID:  frameworkMarkdownSummaryPromptID,
+		ProfileID: "weather-light",
+		Execution: &promptkit.ExecutionTargetOverride{
+			TimeoutSeconds:  &timeout,
+			ReasoningEffort: &reasoning,
+		},
+		Inputs: map[string]promptkit.ArtifactRef{
+			"transcript": promptkit.Inline("Rin opens the gate."),
+			"glossary":   promptkit.Inline("gate: A guarded passage."),
+		},
+	})
+	if err != nil {
+		t.Fatalf("prepare override: %v", err)
+	}
+	if overridden.EffectiveModelParams.TimeoutSeconds != timeout ||
+		overridden.EffectiveModelParams.ReasoningEffort != reasoning {
+		t.Fatalf("runtime override target = %+v", overridden.EffectiveModelParams)
+	}
+}
+
+func TestProfileInheritanceYAMLAliasOfBuiltIn(t *testing.T) {
+	engine, err := promptkit.NewEngine(promptkit.Config{},
+		promptkit.WithPromptFS(fstest.MapFS{}, "."),
+		promptkit.WithProfileFS(fstest.MapFS{
+			"alias.yaml": &fstest.MapFile{Data: []byte("id: yaml-alias\nbase_profile: deepseek-4-flash\n")},
+		}, "."),
+	)
+	if err != nil {
+		t.Fatalf("construct YAML alias engine: %v", err)
+	}
+	inspection, err := engine.InspectProfile(context.Background(), "yaml-alias")
+	if err != nil {
+		t.Fatalf("inspect YAML alias: %v", err)
+	}
+	if inspection.ProfileID != "yaml-alias" || inspection.EffectiveModelParams.Model == "" {
+		t.Fatalf("YAML alias inspection = %+v", inspection)
+	}
+}
+
+func TestProfileInheritanceRetainsRequiredCredentialBehavior(t *testing.T) {
+	engine, err := promptkit.NewEngine(promptkit.Config{},
+		promptkit.WithPromptFS(fstest.MapFS{}, "."),
+		promptkit.WithBackend(promptkit.Backend{
+			ID:        "credential-backend",
+			Endpoint:  "https://credential.example/v1",
+			APIKeyEnv: "OPTIONAL_BACKEND_KEY",
+		}),
+		promptkit.WithProfiles(
+			promptkit.Profile{
+				ID:             "credential-base",
+				BackendID:      "credential-backend",
+				Model:          "model",
+				APIKeyRequired: true,
+			},
+			promptkit.Profile{ID: "credential-child", BaseProfileID: "credential-base"},
+		),
+	)
+	if err != nil {
+		t.Fatalf("construct credential inheritance engine: %v", err)
+	}
+	inspection, err := engine.InspectProfile(context.Background(), "credential-child")
+	if err != nil {
+		t.Fatalf("inspect credential child: %v", err)
+	}
+	if !inspection.APIKeyRequired || inspection.EffectiveModelParams.APIKeyEnv != "" {
+		t.Fatalf("credential inspection = %+v", inspection)
+	}
+}
+
+func TestProfileInheritancePreservesPublicErrorIdentities(t *testing.T) {
+	newEngine := func(t *testing.T, profiles fs.FS) *promptkit.Engine {
+		t.Helper()
+		options := []promptkit.Option{promptkit.WithPromptFS(fstest.MapFS{}, ".")}
+		if profiles != nil {
+			options = append(options, promptkit.WithProfileFS(profiles, "."))
+		}
+		engine, err := promptkit.NewEngine(promptkit.Config{}, options...)
+		if err != nil {
+			t.Fatalf("construct engine: %v", err)
+		}
+		return engine
+	}
+
+	tests := []struct {
+		name     string
+		profiles fs.FS
+		profile  string
+		contains []string
+		want     error
+		wantNot  error
+	}{
+		{
+			name:    "missing selected profile",
+			profile: "missing",
+			want:    promptkit.ErrProfileNotFound,
+			wantNot: promptkit.ErrProfileLoad,
+		},
+		{
+			name: "missing base",
+			profiles: fstest.MapFS{
+				"child.yaml": &fstest.MapFile{Data: []byte("id: child\nbase_profile: missing\n")},
+			},
+			profile:  "child",
+			contains: []string{"child", "missing"},
+			want:     promptkit.ErrProfileLoad,
+			wantNot:  promptkit.ErrProfileNotFound,
+		},
+		{
+			name: "cycle",
+			profiles: fstest.MapFS{
+				"a.yaml": &fstest.MapFile{Data: []byte("id: a\nbase_profile: b\n")},
+				"b.yaml": &fstest.MapFile{Data: []byte("id: b\nbase_profile: a\n")},
+			},
+			profile:  "a",
+			contains: []string{"a", "b"},
+			want:     promptkit.ErrProfileLoad,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result, err := newEngine(t, tc.profiles).InspectProfile(context.Background(), tc.profile)
+			if result != nil || !errors.Is(err, tc.want) || (tc.wantNot != nil && errors.Is(err, tc.wantNot)) {
+				t.Fatalf("inspection=(%+v, %v), want %v without %v", result, err, tc.want, tc.wantNot)
+			}
+			for _, fragment := range tc.contains {
+				if !strings.Contains(err.Error(), fragment) {
+					t.Fatalf("error = %v, want %q", err, fragment)
+				}
+			}
+		})
+	}
+}
+
+func TestProfileInheritanceFreezesPreparedExecution(t *testing.T) {
+	profiles := &mutableInheritanceProfileFS{files: fstest.MapFS{
+		"child.yaml": &fstest.MapFile{Data: []byte("id: child\nbase_profile: base\n")},
+		"base.yaml":  &fstest.MapFile{Data: []byte("id: base\nendpoint: https://base.example/v1\nmodel: first-model\n")},
+	}}
+	client := &fakeLLMClient{response: &promptkit.GenerateResponse{Content: "ok"}}
+	engine, err := promptkit.NewEngine(promptkit.Config{},
+		promptkit.WithPromptFS(contractPromptFS("prepared", "child", "content"), "."),
+		promptkit.WithProfileFS(profiles, "."),
+		promptkit.WithLLMClient(client),
+	)
+	if err != nil {
+		t.Fatalf("construct engine: %v", err)
+	}
+
+	prepared, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{PromptID: "prepared"})
+	if err != nil {
+		t.Fatalf("prepare execution: %v", err)
+	}
+	profiles.set("base.yaml", "id: base\nendpoint: https://base.example/v1\nmodel: second-model\n")
+
+	result, err := engine.RunPrepared(context.Background(), prepared)
+	if err != nil || result == nil || len(client.requests) != 1 || client.requests[0].Target.Model != "first-model" {
+		t.Fatalf("prepared execution=(%+v, %v), requests=%+v", result, err, client.requests)
+	}
+	inspection, err := engine.InspectProfile(context.Background(), "child")
+	if err != nil || inspection.EffectiveModelParams.Model != "second-model" {
+		t.Fatalf("fresh inspection=(%+v, %v)", inspection, err)
+	}
+}
+
+type mutableInheritanceProfileFS struct {
+	mu    sync.RWMutex
+	files fstest.MapFS
+}
+
+func (f *mutableInheritanceProfileFS) Open(name string) (fs.File, error) {
+	f.mu.RLock()
+	defer f.mu.RUnlock()
+	return f.files.Open(name)
+}
+
+func (f *mutableInheritanceProfileFS) set(name, content string) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.files[name] = &fstest.MapFile{Data: []byte(content)}
+}

profiles.go

@@ -2,17 +2,16 @@ package promptkit
 
 import (
 	"context"
-	"errors"
 	"fmt"
-	"strings"
 
 	"gitea.maximumdirect.net/eric/promptkit/internal/domain"
 	"gitea.maximumdirect.net/eric/promptkit/internal/jsonvalue"
 	"gitea.maximumdirect.net/eric/promptkit/internal/profile"
 )
 
-// OpenAICompatibleProfile returns an ordinary in-memory Profile for an
+// OpenAICompatibleProfile returns an in-memory Profile for an OpenAI-compatible
-// OpenAI-compatible chat-completions endpoint.
+// chat-completions endpoint. A non-blank BaseProfileID permits its target
+// fields to be inherited when the profile is selected or inspected.
 //
 // It does not register global state, maintain a model catalog, or resolve
 // credentials. If APIKeyRequired is true, callers satisfy it with
@@ -25,6 +24,7 @@ import (
 func OpenAICompatibleProfile(cfg OpenAICompatibleProfileConfig) Profile {
 	return Profile{
 		ID:              cfg.ID,
+		BaseProfileID:   cfg.BaseProfileID,
 		BackendID:       cfg.BackendID,
 		Endpoint:        cfg.Endpoint,
 		Model:           cfg.Model,
@@ -87,8 +87,9 @@ func toDomainProfile(publicProfile Profile) (domain.ExecutionProfile, error) {
 		return domain.ExecutionProfile{}, err
 	}
 	prof := domain.ExecutionProfile{
-		ID:              strings.TrimSpace(publicProfile.ID),
+		ID:              publicProfile.ID,
-		BackendID:       strings.TrimSpace(publicProfile.BackendID),
+		BaseProfileID:   publicProfile.BaseProfileID,
+		BackendID:       publicProfile.BackendID,
 		Endpoint:        publicProfile.Endpoint,
 		Model:           publicProfile.Model,
 		Temperature:     publicProfile.Temperature,
@@ -100,34 +101,8 @@ func toDomainProfile(publicProfile Profile) (domain.ExecutionProfile, error) {
 		APIKeyRequired:  publicProfile.APIKeyRequired,
 		ExtraParams:     extraParams,
 	}
-	if err := normalizeAndValidatePublicProfile(&prof); err != nil {
+	if err := profile.NormalizeAndValidateDefinition(&prof); err != nil {
 		return domain.ExecutionProfile{}, err
 	}
 	return prof, nil
 }
-
-func normalizeAndValidatePublicProfile(prof *domain.ExecutionProfile) error {
-	if strings.TrimSpace(prof.ID) == "" {
-		return errors.New("id is required")
-	}
-	prof.Endpoint = strings.TrimSpace(prof.Endpoint)
-	if strings.TrimSpace(prof.BackendID) == "" && prof.Endpoint == "" {
-		return errors.New("backend or endpoint is required")
-	}
-	if prof.Endpoint != "" {
-		endpoint, err := domain.NormalizeOpenAICompatibleBaseEndpoint(prof.Endpoint)
-		if err != nil {
-			return err
-		}
-		prof.Endpoint = endpoint
-	}
-	if strings.TrimSpace(prof.Model) == "" {
-		return errors.New("model is required")
-	}
-	return domain.ValidateExecutionTargetSettings(domain.ExecutionTarget{
-		Temperature:    prof.Temperature,
-		MaxTokens:      prof.MaxTokens,
-		TopP:           prof.TopP,
-		TimeoutSeconds: prof.TimeoutSeconds,
-	})
-}

public_contract_test.go

@@ -784,9 +784,12 @@ func TestBackendRegistrationRejectsInvalidAndDuplicateDefinitions(t *testing.T)
 			{ID: " custom ", Endpoint: "http://one.example/v1"},
 			{ID: "custom", Endpoint: "http://two.example/v1"},
 		}},
-		{name: "reserved built-in id", backends: []promptkit.Backend{{
+		{name: "reserved OpenRouter ID", backends: []promptkit.Backend{{
 			ID: promptkit.BackendOpenRouter, Endpoint: "http://replacement.example/v1",
 		}}},
+		{name: "reserved Rakestrawhome ID", backends: []promptkit.Backend{{
+			ID: promptkit.BackendRakestrawHome, Endpoint: "http://replacement.example/v1",
+		}}},
 	}
 
 	for _, tt := range tests {

types.go

@@ -322,7 +322,10 @@ type ExecutionTarget struct {
 	// ReasoningEffort is the effective opaque provider-specific reasoning
 	// setting. An empty value instructs model clients to omit reasoning.
 	ReasoningEffort string `json:"reasoning_effort"`
-	// APIKeyEnv is an environment-variable name, not its credential value.
+	// APIKeyEnv is the resolved name of an optional environment lookup source,
+	// not its credential value. The built-in client omits Authorization when no
+	// usable direct or environment credential is available; injected clients may
+	// resolve this metadata differently.
 	APIKeyEnv string `json:"api_key_env"`
 	// ExtraParams contains copied JSON-compatible provider parameters.
 	ExtraParams map[string]any `json:"extra_params"`
@@ -426,9 +429,10 @@ type ExecutionTargetOverride struct {
 	// inherited value and disables reasoning for this run. Non-blank values
 	// are opaque and are not validated against a fixed vocabulary.
 	ReasoningEffort *string
-	// APIKeyEnv replaces the profile or backend environment-variable name when
+	// APIKeyEnv replaces the profile or backend optional environment lookup
-	// non-blank. A direct RunRequest.APIKey still takes precedence over
+	// source when non-blank. A direct RunRequest.APIKey still takes precedence.
-	// environment lookup.
+	// The built-in client omits Authorization when neither source has a usable
+	// value; injected clients may resolve this metadata differently.
 	APIKeyEnv string
 	// ExtraParams, when non-empty, replaces the complete profile or backend map.
 	// Values must be JSON-compatible: nil, booleans, finite numbers, strings,
@@ -439,31 +443,43 @@ type ExecutionTargetOverride struct {
 
 // Profile is an in-memory execution profile for library consumers.
 //
-// It is equivalent to a loaded profile file after validation. Raw API keys do
+// A standalone Profile is equivalent to a loaded profile file after local
-// not belong in profiles; use APIKeyRequired to require callers to provide a
+// validation. A derived profile names BaseProfileID and can inherit target
-// RunRequest.APIKey or explicit request ExecutionTargetOverride.APIKeyEnv, or
+// fields when selected or inspected. Raw API keys do not belong in profiles;
-// use profile YAML api_key_env with file and FS profile sources. Profile has no
+// use APIKeyRequired to require callers to provide a RunRequest.APIKey or
-// stable JSON representation.
+// explicit request ExecutionTargetOverride.APIKeyEnv, or use profile YAML
+// api_key_env with file and FS profile sources. Profile has no stable JSON
+// representation.
 //
-// WithProfiles validates and copies Profile values during NewEngine. Zero
+// WithProfiles locally validates and copies Profile values during NewEngine.
-// Temperature, MaxTokens, and TopP values and blank ServiceTier and
+// It checks base-reference existence and resolved target completeness when a
-// ReasoningEffort values leave those provider controls unspecified. A zero
+// derived profile is selected or inspected. Zero Temperature, MaxTokens, and
-// TimeoutSeconds retains the framework deadline, while an empty ExtraParams map
+// TopP values and blank ServiceTier and ReasoningEffort values leave those
-// inherits backend request defaults. Use ExecutionTargetOverride pointer fields
+// provider controls unspecified. A zero TimeoutSeconds retains the framework
-// to request an explicit numeric zero.
+// deadline, while an empty ExtraParams map inherits backend request defaults.
+// Use ExecutionTargetOverride pointer fields to request an explicit numeric
+// zero.
 type Profile struct {
 	// ID is the required non-blank profile identifier. WithProfiles trims it.
 	ID string
+	// BaseProfileID optionally names one base profile. WithProfiles trims it. A
+	// non-blank value permits required target fields to be inherited when the
+	// profile is selected or inspected, which is also when reference existence
+	// and resolved completeness are checked. A blank value leaves this as a
+	// standalone profile.
+	BaseProfileID string
 	// BackendID optionally selects an engine backend. WithProfiles trims it.
 	// Backend membership is checked when a request selects the profile; an
 	// unknown ID makes preparation fail with ErrProfileLoad.
 	BackendID string
-	// Endpoint is the model-provider base URL. It is required only when
+	// Endpoint is the model-provider base URL. A standalone Profile requires an
-	// BackendID is blank and otherwise overrides the backend endpoint when
+	// endpoint when BackendID is blank; a derived Profile may inherit either
+	// field. A non-blank endpoint overrides the backend endpoint when
 	// non-blank. WithProfiles trims it and requires an absolute HTTP or HTTPS URL
 	// with a host and no user information, query, or fragment.
 	Endpoint string
-	// Model is the required non-blank provider model identifier.
+	// Model is the provider model identifier. It is required for a standalone
+	// Profile and may be inherited by a derived Profile.
 	Model string
 	// Temperature is from 0 through 2. Zero leaves the provider control
 	// unspecified.
@@ -481,7 +497,8 @@ type Profile struct {
 	ReasoningEffort string
 	// APIKeyRequired clears a backend's inherited API-key environment name and
 	// requires a non-blank RunRequest.APIKey unless the request explicitly
-	// supplies ExecutionTargetOverride.APIKeyEnv. It does not store a credential.
+	// supplies ExecutionTargetOverride.APIKeyEnv. When false, a named
+	// environment source remains optional. It does not store a credential.
 	APIKeyRequired bool
 	// ExtraParams contains provider-specific JSON-compatible values. An empty
 	// map inherits backend request defaults, when any. WithProfiles validates
@@ -494,13 +511,16 @@ type Profile struct {
 // profile.
 //
 // It contains ordinary profile fields for OpenAI-compatible chat-completions
-// endpoints. APIKeyRequired follows Profile.APIKeyRequired. Raw API keys do not
+// endpoints. BaseProfileID and APIKeyRequired follow Profile. Raw API keys do
-// belong in this config. OpenAICompatibleProfileConfig has no stable JSON
+// not belong in this config. OpenAICompatibleProfileConfig has no stable JSON
 // representation and is not validated until its resulting Profile is supplied
 // through WithProfiles to NewEngine.
 type OpenAICompatibleProfileConfig struct {
 	// ID becomes Profile.ID.
 	ID string
+	// BaseProfileID becomes Profile.BaseProfileID. A non-blank value permits the
+	// resulting Profile to inherit target fields when it is selected or inspected.
+	BaseProfileID string
 	// BackendID becomes Profile.BackendID.
 	BackendID string
 	// Endpoint becomes Profile.Endpoint.
@@ -665,10 +685,10 @@ type StructuredOutputJSONSpec struct {
 // and retained copies. It is responsible for the cancellation behavior of any
 // work it starts and for synchronizing access to retained or shared data.
 //
-// A returned error makes Run or RunPrepared return ErrLLMGenerate while
+// An arbitrary returned error makes Run or RunPrepared return ErrLLMGenerate
-// preserving the client error through errors.Is. A nil response with a nil
+// while preserving the client error through errors.Is rather than translating
-// error also produces ErrLLMGenerate. Promptkit copies the non-nil response
+// it. A nil response with a nil error also produces ErrLLMGenerate. Promptkit
-// before returning from either method.
+// copies the non-nil response before returning from either method.
 type LLMClient interface {
 	Generate(context.Context, GenerateRequest) (*GenerateResponse, error)
 }