From dd1915735f259f60d4498f5c814ca56c310dd1d1 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 15:17:46 +0000 Subject: [PATCH] Clarify precedence for discovered collections --- docs/config.md | 6 ++++++ docs/consumers/upgrading-promptkit.md | 10 +++++++--- docs/roadmap/remediation.md | 4 ++++ 3 files changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/config.md b/docs/config.md index 08bf203..3ec56a1 100644 --- a/docs/config.md +++ b/docs/config.md @@ -98,6 +98,12 @@ checkout directory name does not determine the namespace. New checkouts are available on the next invocation without editing this file; a running server does not reload them. See the [maintained collection examples](../examples/discovery/collections/). +Entries imported by one discovery file are composed together as peers. +Conflicting definitions of the same qualified resource ID fail to load; +filename, checkout, and glob order do not set precedence. To override a +discovered record, select a separate framework file later in +`promptkit_sources` and supply the complete replacement record. + ### Explicit imports and selected overlays Application files declare imports under root `config.imports`. Native `path`, diff --git a/docs/consumers/upgrading-promptkit.md b/docs/consumers/upgrading-promptkit.md index 41e671d..31bd8a6 100644 --- a/docs/consumers/upgrading-promptkit.md +++ b/docs/consumers/upgrading-promptkit.md @@ -82,9 +82,13 @@ Convert framework source controls from `configkit:` to `config:` and add header, if present, is `version: 2`. Use sibling inheritance such as `extends: {id: base}`. -Composition now replaces a whole record when a later source selects the same -ID; supply the complete intended replacement, or create a distinct inherited -record. Null profile endpoint, credential, or provider-map settings can fall +Across ordered `promptkit_sources` entries, a later framework underlay replaces +the whole record for the same ID. Supply the complete intended replacement, +or create a distinct inherited record. Checkouts imported by the same +[discovery file](../config.md#collection-checkout-discovery) are peers: +conflicting definitions of the same ID fail instead of overriding one another. + +Null profile endpoint, credential, or provider-map settings can fall back to the selected backend; review behavior rather than assuming null clears backend values. Keep JSON schemas self-contained instead of depending on remote schema references. Application selectors remain separate from these framework diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index d64246c..537f615 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -71,6 +71,10 @@ adopted attribution format. ## R4: Distinguish discovery peers from ordered framework layers (Stages 6–7) +**Complete.** The migration guide and configuration reference distinguish +peer conflicts from ordered replacement. The same two definitions were +verified to conflict as peers and replace as separate selectors. + The [upgrade guide](../consumers/upgrading-promptkit.md) says a later source selecting the same ID replaces the whole record. That holds for a later framework underlay, not for two checkout entries selected by the same