Resolve profiles through built-in backends

docs/formats.md

@@ -136,7 +136,7 @@ A profile supplies model execution settings:
 
 ```yaml
 id: local-summary
-endpoint: http://localhost:8000/v1
+backend: openrouter
 model: example-model
 temperature: 0.2
 max_tokens: 500
@@ -144,7 +144,6 @@ top_p: 0.95
 timeout_seconds: 90
 service_tier: flex
 reasoning_effort: medium
-api_key_env: EXAMPLE_API_KEY
 extra_params:
   provider_option: enabled
 ```
@@ -152,7 +151,8 @@ extra_params:
 | Field | Required | Meaning |
 | --- | --- | --- |
 | `id` | yes | Non-empty profile identifier. IDs must be unique within one source. |
-| `endpoint` | yes | Non-empty OpenAI-compatible base URL, including an API version path when required. |
+| `backend` | unless `endpoint` is present | Backend registry ID. It is trimmed and registry membership is checked when the profile is prepared. |
+| `endpoint` | unless `backend` is present | Non-empty OpenAI-compatible base URL, including an API version path when required. When both connection fields are present, this overrides the backend endpoint without changing backend identity. |
 | `model` | yes | Non-empty provider model name. |
 | `temperature` | no | Number from 0 through 2. |
 | `max_tokens` | no | Integer zero or greater. |
@@ -166,6 +166,9 @@ extra_params:
 Raw `api_key` is prohibited in profile YAML. Store only an environment
 variable name in `api_key_env`.
 
+Promptkit does not infer a backend from a model or endpoint. Endpoint-only
+profiles remain supported and have no effective backend ID.
+
 `extra_params` accepts null, booleans, finite numbers, strings, arrays, and
 objects with string keys. Keys must be non-empty. With the built-in client,
 they also cannot collide with the standard fields listed in the
@@ -176,8 +179,9 @@ they also cannot collide with the standard fields listed in the
 Execution settings resolve in this order:
 
 1. framework defaults;
-2. the selected profile; and
-3. request `ExecutionTargetOverride` values.
+2. the selected backend, when the profile names one;
+3. the selected profile; and
+4. request `ExecutionTargetOverride` values.
 
 The framework defaults are:
 
@@ -194,8 +198,10 @@ explicit zero is preserved. In particular, an explicit request
 `timeout_seconds` of zero disables the per-generation deadline while leaving
 the caller context and transport timeout intact.
 
-Non-empty request strings replace profile strings. A non-empty request
-`ExtraParams` map replaces the profile map rather than merging keys.
+Non-empty profile strings replace backend defaults, and non-empty request
+strings replace both. Backend identity is retained when either layer overrides
+the endpoint. A non-empty `extra_params` map at each layer replaces the entire
+lower-precedence map rather than merging keys.
 The [outbound integration contract](integrations/openai-compatible-chat.md)
 defines how the effective settings are serialized.
 
@@ -217,9 +223,11 @@ invalid matching profile is an error and does not fall back. In-memory
 
 ## Built-In Profile Catalog
 
-Built-ins use the OpenRouter-compatible endpoint and
-`OPENROUTER_API_KEY`. A custom or in-memory profile with the same ID takes
-precedence.
+Every built-in selects the `openrouter` backend. The engine's built-in backend
+registry supplies `https://openrouter.ai/api/v1` and the environment-variable
+name `OPENROUTER_API_KEY`, so individual profiles contain only model and
+generation settings. A custom or in-memory profile with the same profile ID
+takes precedence.
 
 | Provider | ID | Model |
 | --- | --- | --- |
@@ -270,6 +278,10 @@ prompt, profile, schema, or example files:
 - a request can provide a direct `APIKey` or override `APIKeyEnv`; 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.
 Direct keys are excluded from JSON results and redacted by public string
 formatters. Environment-variable names may appear in prepared metadata, but