Document shared loading and integration upgrades

This commit is contained in:
2026-11-21 19:48:59 +00:00
parent 6a090ba571
commit 2a086b6389
11 changed files with 170 additions and 49 deletions

View File

@@ -477,8 +477,8 @@ records preserve their returned order. No records are
output begins with the scope heading and prints the same source fields,
quoting labels and paths. These fields come from ConfigKit's source records;
producing the report does not reload files or rerun version checks. See the
[ConfigKit v1.2.1 source
records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/records.go)
[ConfigKit v1.4.0 source
records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3/records.go)
for native evidence definitions.
### Explain a configuration path
@@ -502,7 +502,12 @@ occurred in history; `--under POINTER` selects a subtree, and `--explicit=true`
or `--explicit=false` filters current paths by native explicitness. Historical-only
paths do not match an explicitness filter. These options require `--list`.
The report contains the scope and each selected path's current presence and,
when present, its explicitness. Path discovery does not include values or history.
when present, its explicitness. Path discovery does not include values or
history. Focused scopes list their native candidates, such as paths beneath
`/promptkit`; explicit `--path`
queries use native whole-load paths, including outside the focus where supported.
A scope is not an access-control boundary. Sources and diagnostics retain the
whole load's evidence.
Pointer tokens use JSON Pointer escaping: `~1` represents `/` and `~0`
represents `~`. A malformed pointer is a usage error with status `2` and is
@@ -599,7 +604,10 @@ concise report contains `additions`, `changes`, and `deletions`. Additions and
changes keep the configuration's path structure and show right-side values
from the comparison. Deletions are JSON Pointer paths. Explicit null is a
value, not a deletion. Changed lists and regions replaced as a whole are shown
as whole values.
as whole values. Focused scopes render the selected subtree and compare native
views; differences at an atomic ancestor can remain in the result. An absent
focused effective value can fail output delivery, while an explicit null remains
null.
ConfigKit considers sensitivity on both sides. A secret value can change even
when both redacted snapshots look the same. For those ConfigKit-backed
@@ -666,7 +674,7 @@ request overrides. Backend reports describe configured backend fields. An
`api_key_env` value names an environment variable; it is not a credential
value or a claim that one is available. Neither report resolves references or
performs a network probe. See the [PromptKit resource inspection
contracts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/resource_inspection.go).
contracts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/resource_inspection.go).
Omitting the ID is a usage error. Configuration loading follows the
[configuration failure classification](#configuration-failure-classification);
lookup failures and cancellation are operational.
@@ -722,7 +730,7 @@ text output use YAML. Preparation can read resources and include rendered
application content in the report. It does not guarantee that a later model
call will succeed. Application loaders and callbacks may have their own
effects. The [PromptKit Prepare
API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/engine.go)
API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/engine.go)
owns the prepared value and upstream preparation behavior. Configuration failures
follow the [configuration failure classification](#configuration-failure-classification);
other preparation failures are operational.
@@ -758,8 +766,8 @@ identity rather than changing the discovered requirements. An enabled profile
namespace qualifies an explicitly supplied short profile ID; it does not
rewrite the prompt's stored default reference. Requirements inspection does
not require the selected profile to be execution-ready. See the [PromptKit
v0.23.2 consumer
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md)
v0.24.0 consumer
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md)
for configuration, selection, and requirements behavior. For built-in flags
other than `--llm-var`, repeating a flag uses its last value.
Application-defined flags follow their own repetition rules.
@@ -870,7 +878,7 @@ applicable. It does not make a model call or retain a prepared execution
snapshot. A successful report describes this preparation invocation; it does
not certify provider acceptance or guarantee later execution. See PromptKit's
[`Engine.ValidateRequest`
API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/engine.go).
API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/engine.go).
Configuration errors returned by request construction or engine loading follow
the [configuration failure classification](#configuration-failure-classification).
@@ -936,8 +944,8 @@ The entries are:
A catalog result is an inventory, not a readiness check or execution result.
The owning provider controls membership and order. Namespace filters are
passed to PromptKit without local membership interpretation. See the
[PromptKit v0.23.2 consumer
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md)
[PromptKit v0.24.0 consumer
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md)
for resource and selection definitions. Catalog loading failures follow the
[configuration failure classification](#configuration-failure-classification).
@@ -1108,9 +1116,9 @@ separately from delivery failures through the [reporting
API](consumers/guide.md#invocation-reporting).
Native configuration, selection, and diagnostic meanings remain owned by
PromptKit. See the [v0.23.2 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md),
[smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/smoke_diagnostics.go),
and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/engine.go).
PromptKit. See the [v0.24.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md),
[smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/smoke_diagnostics.go),
and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/engine.go).
## Outcome status