Document PromptKit configuration ownership and capture

This commit is contained in:
2026-10-04 14:12:11 +00:00
parent 169a94f7ea
commit 4aba4f5672
6 changed files with 215 additions and 62 deletions

View File

@@ -93,16 +93,24 @@ application fallback profile assets, and optional backend configuration
through the same construction path for inspection and execution. PromptKit
owns source precedence, strict group composition, and recursive field overlay:
omitted operator fields retain lower-layer values, while supplied fields
replace them. A malformed final effective definition fails construction. The
operator configuration and deployment workflow are defined in
replace them. The application group retains registered filesystem roots; the
operator may be one file with native imports or a recursively discovered
directory. Imports resolve resources from their declaring file. Prompt and
profile definitions are validated after source composition, so a malformed
lower-layer value superseded by a valid overlay is not separately audited. A
malformed final effective definition fails construction. The operator
configuration and deployment workflow are defined in
[Configuration](../config.md#promptkit-profiles) and
[Operations](../operations.md#promptkit-profile-deployment).
PromptKit and ConfigKit own `extends` inheritance under the
[pinned format rules](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
Notarius records the selected leaf identity and resolved target without parsing
or merging inheritance. An unset filesystem `api_key_env` is optional and may
reach the provider without authorization, which can result in a 401 or 403.
or merging inheritance. `api_key_env` names the environment variable; inspection
does not check whether it is set. PromptKit's effective `api_key_required`
metadata is supported in file-backed profiles and reported as metadata, not
as an availability check. Whether a usable credential reaches the provider
remains an execution concern.
PromptKit accepts only the `developer`, `system`, `user`, and
`assistant` text-chat roles after normalizing case and surrounding whitespace.
@@ -129,6 +137,11 @@ PromptKit obtains its maintained OpenRouter and Rakestrawhome backend and
profile catalogs from independently versioned transitive modules. Notarius
does not import or register either catalog; PromptKit retains catalog source,
identity, precedence, credential, and capacity ownership.
The selected integration modules are
[`promptkit-backend-openrouter/v3`](../oss/attribution.md#promptkit-openrouter-catalog)
and
[`promptkit-backend-rakestrawhome/v3`](../oss/attribution.md#promptkit-rakestrawhome-catalog),
both pinned at `v3.20260930.0` for this compatibility boundary.
External catalog profile names and settings can change between dependency
releases, including removal without aliases. Review directly selected IDs and
@@ -153,6 +166,16 @@ implicitly supported. A dependency upgrade requires reviewing the adapter,
profile-source construction, and this compatibility statement against the
pinned upstream documentation.
Captured inspection describes one engine's immutable effective view. Source
edits require constructing a new engine to become visible. Effective and
explanation reports retain PromptKit's redacted configuration and source
history contracts; the profile command is a separate Notarius-owned projection
of copied, provider-neutral metadata. None of these views reads credential
values or predicts provider defaults. See the public [CLI reference](../cli.md#config-effective),
[explanation](../cli.md#config-explain), and
[profile](../cli.md#config-profile) entries for their syntax and output
contracts.
## Notarius Ownership
[LLM Runtime Internals](../internal/llm.md) describes how Notarius mounts