Clarify source selector clearing behavior

This commit is contained in:
2026-11-18 00:29:33 +00:00
parent 65bd2da51a
commit 932fd6da25
2 changed files with 34 additions and 10 deletions

View File

@@ -59,7 +59,7 @@ promptkit_sources:
schema_dir: ./examples/schemas
```
Omitting the field or setting it to `[]` (or `null`) selects no
An empty or null final resolved `promptkit_sources` list selects no
application-supplied framework sources; Promptkit's selected catalog and
maintained definitions still apply. A later sequence item overlays an earlier
one. Files within a selected directory are composed together, so conflicting
@@ -96,6 +96,16 @@ precedence boundaries. The [collection example](../examples/config.collections.y
declares `file` identity with `upsert`, combines imported file selectors, and
lets an overlay add another. CLI list overrides still replace the whole list.
At application precedence boundaries, omission preserves lower-precedence
selectors. Under ordinary list replacement, `[]` clears the selection and
`null` resolves to no selectors. Under authored `append` or `upsert`, `[]`
contributes no records and `null` is invalid. To clear a collection with an
inherited policy, declare `mode: replace` at
`destination: [promptkit_sources]` in the higher-precedence source and supply
`promptkit_sources: []`. See
[ConfigKit's collection policy contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md#yaml-declarations-and-policy-lifetime)
for policy lifetime and combination rules.
These application root `config` controls do not change the separate
Promptkit v0.12.0 framework format: its selected framework files use the
[Promptkit contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
@@ -105,11 +115,13 @@ and its older ConfigKit controls.
root. The name must use letters, digits, `_`, or `-`; it is not a path. Empty
and exact lowercase `default` select no overlay. There is no fallback,
case folding, inherited stack, or automatic selection; a missing selected
overlay fails. Mappings merge and explicit nulls replace; sequence behavior
depends on any authored collection policy. Defaults-only loading can enable
imports, but an absent main has no import declarations. This CLI supplies no
independent overlay root, so an active overlay cannot be located without a
selected main context. That is not a general ConfigKit restriction.
overlay fails. Mappings merge; sequence contributions and nulls at collection
destinations follow the effective collection policy described above. Other
explicit nulls replace lower values subject to the application schema.
Defaults-only loading can enable imports, but an absent main has no import
declarations. This CLI supplies no independent overlay root, so an active
overlay cannot be located without a selected main context. That is not a general
ConfigKit restriction.
The [composed example](../examples/config.composed.yml) imports the application
[source-selection fragment](../examples/config-fragments/sources.yml) and has