Settle collection configuration decisions around simplicity

docs/roadmap/configuration-collections-mounted-fragments.md

@@ -6,11 +6,26 @@ ConfigKit capabilities are implemented on its development branch, reviewed at
 The recommended direction uses collection-local mapping keys, one installed
 definition per prompt, and an optional flat prompt `version` field. The latest
 review agrees on shared source checks using `IfPresent` and a distinct collection
-`release_version` field; remaining PromptKit decisions are listed below. The
+`release_version` field. The six configuration decisions below are accepted;
-parent [namespace roadmap](namespaces.md) owns the shared decisions. Unselected
+exact public API shapes remain delivery details. The parent [namespace roadmap](namespaces.md) owns the shared decisions. Unselected
 proposals 1 and 2 have been retired; their history and the separately captured
 upstream request are recorded below.
 
+## Configuration Simplicity
+
+This development round simplifies configuration authoring and consumption:
+
+- Load prompt, profile, and backend libraries as YAML configuration, removing
+  mandatory catalog Go-module imports and bundled profiles.
+- Remove the unused prompt-version selection scheme and its request API fields.
+- Let publishers opt into specification checks by declaring a source-root
+  `version`, commonly in a collection entry. Neither entries nor individual
+  fragments must declare it; authors need not add headers to every file.
+
+Prefer conventions and small convenience APIs over mandatory workflows.
+Preserve consumer choice over sources, layout, namespaces, and precedence without
+adding speculative options or stronger compatibility/provenance guarantees.
+
 ## Recommendation
 
 Use ConfigKit's implemented input destinations and relative import destinations.
@@ -141,12 +156,13 @@ entry := configkit.Input{
 }
 ```
 
-Put peer collection entries into one `Underlay` group's `Inputs`. Configure
+For independent peer collections, one `Underlay` group's `Inputs` is a useful
-`LayeredOptions.SourceVersionMode` as `SourceVersionModeIfPresent` and
+starting point, not a required grouping. Consumers choose precedence and groups.
+Configure `LayeredOptions.SourceVersionMode` as `SourceVersionModeIfPresent` and
 `Definition.Version.Path` as `configkit.Keys("version")`, with PromptKit's
 supported-specification checker. The application main input remains at the
-root and declares `version: 1` in the examples below. Namespace selection and
+root and declares `version: 1` in the examples below; both the main input and
-source selection require no manifest parsing in PromptKit.
+its declaration are optional. Namespace and source selection require no manifest parsing in PromptKit.
 
 | Selected source | Effective destination |
 | --- | --- |
@@ -160,8 +176,11 @@ Directly selected fragments with `Input.Destination` remain possible. Entry
 imports are the recommended packaging convention because publishers can describe
 their layout. Filenames and directory basenames do not define resource identity;
 no implicit directory discovery, namespace inference, or collection installer is
-introduced. A helper may construct inputs from explicit source selections but
+introduced. A small helper should construct inputs from an explicitly selected
-must not inspect manifests to compute their destinations.
+source and namespace, without inspecting manifests to compute destinations. `collection.yml`
+is a convention, not a required filename. Direct fragments and programmatic
+sources remain supported through the source API; no parallel collection loader
+or mandatory filesystem layout is introduced.
 
 Use later underlay groups or main for intentional application/operator overrides.
 Placement does not establish precedence. Do not also recursively scan files
@@ -256,25 +275,17 @@ The resource's qualified ID is its sole configuration identity. There is no
 version-key mapping, implicit `latest`, version ordering, or parallel installed
 history. Updating the optional version changes metadata on the same prompt.
 
-Recommend a nonblank opaque string when a prompt version is supplied, with no
+An optional prompt version is an opaque string with no SemVer, nonblank, or
-SemVer constraint. Omission or explicit null means no declared version; null
+normalization requirement. Omission or explicit null means no declared label;
-can clear a lower-layer or inherited label. Quote numeric-looking labels such
+null can clear a lower-layer or inherited label. Quote numeric-looking labels
-as `"1"`. Do not synthesize a version for an unversioned prompt. These detailed
+such as `"1"`. Preserve supplied strings, including empty strings, and distinguish
-value rules are recommendations; the agreed requirement is that the field be
+an absent label in inspection. Do not synthesize a version.
-optional.
 
-Execution and inspection without a requested version select the installed
+Remove request-side prompt-version fields, version selection, ordering, and
-prompt directly. As an API migration recommendation, retain an optional
+version defaults as part of the breaking change. Do not reinterpret those fields
-requested version as an exact assertion against the installed label: a match
+as exact-match assertions. Execution and inspection resolve the installed prompt
-succeeds; a mismatch or an unversioned definition fails the assertion. It never
+by ID alone. Listings expose one prompt per ID with its optional descriptive
-searches for another version. Removing request-side version fields altogether
+label separately. A label neither controls execution nor proves unchanged content.
-is a simpler alternative but requires more consumer changes; settle the public
-API shape before implementation. Listings should identify one prompt per ID
-and expose the optional declared version separately from identity.
-
-This deliberately replaces the earlier multi-version preservation assumption.
-The selected direction identifies prompts by ID and exposes an optional version
-label; the request-version and listing API details remain open below.
 
 ## ConfigKit Composition Boundary
 
@@ -322,17 +333,14 @@ now ordinary optional fields, would inherit and overlay like other fields;
 
 Cross-collection profiles are no longer immediate siblings. Consequently,
 `extends: provider/brief` cannot reach that collection under current ConfigKit
-inheritance. Recommend local sibling inheritance for the initial proposal;
+inheritance. Use existing local sibling inheritance for this development round;
-applications can still execute or select the qualified `provider/brief`
+applications can still select the qualified `provider/brief` profile directly.
-profile directly. Migrating existing cross-collection inheritance requires
+Authors needing a customized derivative may publish an expanded definition.
-flattening those authored definitions or making a separate upstream change.
+Expansion is a migration option, not a mandatory authoring workflow.
 
-An alternative is generic explicit-path inheritance in ConfigKit, with its own
+Generic cross-path inheritance remains possible future ConfigKit work if a
-syntax, cycle rules, and provenance contract. That would preserve reusable
+concrete consumer need justifies it. It is not a prerequisite of this round.
-cross-collection bases, but crosses a currently deferred ConfigKit boundary
+PromptKit must not add its own inheritance resolver after ConfigKit handoff.
-and is additional work beyond mounting. PromptKit must not resolve such
-relationships itself after handoff. Decide whether this capability is required
-before selecting a migration plan.
 
 ## Specification Versions And Collection Inventory
 
@@ -341,20 +349,21 @@ before selecting a migration plan.
 Use one `Definition.Version` policy, with source-local path `version`, for the
 candidate PromptKit specification. Initially accept specification text `1` from
 string or strict decimal-integer declarations; reject explicit null and other
-unsupported declarations through the ConfigKit checker. The handling of an
+unsupported declarations through the ConfigKit checker. Accept an absent main
-absent main declaration remains an explicit decision below. Accept additional
+declaration, including an absent main input. Accept additional versions only when PromptKit actually supports their format semantics: accepting
-versions only when PromptKit actually supports their format semantics: accepting
 a header does not migrate its payload or independently validate a fragment's
 complete schema. The retired proposals were alternatives, not released formats
 sharing specification version 1.
 
-The selected initial direction is `SourceVersionModeIfPresent`:
+Use `SourceVersionModeIfPresent` without adding a PromptKit mode-selection
+option in this round. A stricter option can be considered for a demonstrated
+consumer need. The upstream modes remain distinct:
 
 | Mode | Implemented behavior | Role in this proposal |
 | --- | --- | --- |
 | `Default` | Existing main-only effective-path check and protected-path behavior | Not the proposed shared-source policy |
 | `IfPresent` | Checks present declarations; skips absent non-main declarations | Initial choice for compact fragments |
-| `Required` | Requires declarations on every participating document | Possible stricter consumer option; not entry-only checking |
+| `Required` | Requires declarations on every participating document | Upstream capability; exposing a PromptKit option is deferred |
 
 Participating documents include actual main and underlay inputs, transitive and
 glob imports, and the selected overlay. Defaults, synthetic CLI overrides,
@@ -370,9 +379,12 @@ Do not confuse header consumption with permission to override the remaining
 protected application field.
 
 `IfPresent` does not require a collection entry header and does not infer a
-fragment's compatibility from its entry. It checks the declarations actually
+fragment's compatibility from its entry. A publisher can declare compatibility
-present. Requiring headers only on entry files is not supported by the load-wide
+in the entry while leaving imported files headerless; the assembled configuration
-mode. Do not emulate it using a preliminary manifest load or validation of
+still undergoes normal validation. A declaration is not a guarantee of future
+compatibility or independent schema validation of every imported fragment.
+ConfigKit checks the declarations actually present. Requiring headers only on
+entry files is not supported by the load-wide mode. Do not emulate it using a preliminary manifest load or validation of
 source history. If that stronger guarantee becomes essential, seek an explicit
 upstream contract instead.
 
@@ -387,20 +399,17 @@ Migration must rename it rather than simply enable the new mode.
 
 This reservation affects resource fragments whose local key is literally
 `version`: a root mapping with that name is interpreted as a malformed header.
-Recommend expressing such a resource within a nested resource mapping in the
+Allow that resource name through a nested resource mapping, for example
-collection entry, for example `prompts: {version: ...}`, rather than globally
+`prompts: {version: ...}` in a collection entry. Reserve the header position,
-banning that public resource ID. The exact author-facing convention remains
+not the public resource name. Existing `configkit` and `extends` structural
-open below. Existing `configkit` and `extends` structural reservations also
+reservations also remain applicable; destinations do not bypass them.
-remain applicable; destinations do not bypass them.
 
 An absent header in an actual main document still reaches the checker under
-`IfPresent`. `NoSource` also invokes the existing absent-main checker behavior,
+`IfPresent`; `NoSource` invokes the absent-main checker as well. PromptKit's
-even under `Required`. Consequently, the mode alone does not determine whether
+checker accepts omission in both cases. Consumers may assemble only underlays,
-PromptKit supports construction without a main declaration. Recommend an
+fragments, or programmatic inputs without manufacturing a main document or
-explicit main specification declaration for the new standard, including for a
+header. Do not inject a declaration or report undeclared sources as checked.
-programmatically supplied main, without silently injecting one. An alternative
+Present unsupported declarations still fail; final schema validation still runs.
-is to accept absent main declarations deliberately for underlay-only callers;
-settle that compatibility choice before implementing the checker.
 
 ### Inspection And Effective Collection Inventory
 
@@ -446,19 +455,20 @@ Proposal 2's generic extension is preserved in the ConfigKit repository as
 explicit record-identity registration, composition and overlay by identity,
 record inheritance, deterministic ordering, and coherent inspection. That
 request is for upstream evaluation, not an accepted ConfigKit capability or a
-prerequisite of this roadmap. Retirement does not resolve the six remaining
+prerequisite of this roadmap. The subsequently accepted PromptKit decisions
-PromptKit decisions below.
+are recorded below.
 
 ## Migration
 
 Migration must choose one installed definition for each former multi-version
 prompt, move any retained version into its optional field, and relocate
 qualified resource keys into collection/local-key mappings. Update destination
-declarations, stored references, request-version handling, inventories, and
+declarations, stored references, inventories, and configuration-inspection paths. Rename collection release metadata to
-configuration-inspection paths. Rename collection release metadata to
 `release_version`, configure the shared checker and mode, and account for the
-source-root header reservation and the selected main-absence policy. Preserve
+source-root header reservation and optional main declarations. Remove obsolete
-provider model strings and source resource bases. Namespace mounting does not
+request-version fields and version-selection logic from consumer examples and
+public APIs rather than retaining them as assertions. Preserve provider model
+strings and source resource bases. Namespace mounting does not
 automatically relocate schema or artifact stores or rewrite references when a
 collection is renamed.
 
@@ -481,9 +491,10 @@ PromptKit acceptance should exercise typed assembly of multiple collections,
 relative/nested imports, source-local header checking and consumption, ordinary
 release and prompt metadata, unqualified resources, scoped selection, optional
 prompt versions, inventory without release metadata, source-relative content,
-intentional partial overrides, and the chosen main-absence policy. Add request
+intentional partial overrides, headerless entries/fragments, omitted main inputs
-version assertions if retained. Do not duplicate ConfigKit's generic source
+and headers, and resources named `version` in nested mappings. Verify ID-only
-validation or enforce domain rules through historical source inspection.
+lookup and descriptive labels without version selection or request assertions.
+Do not duplicate ConfigKit's generic source validation or enforce domain rules through historical source inspection.
 
 Review verification on 2026-10-16 against ConfigKit `e66c371`: focused public API
 and consumer-example tests passed. A temporary typed consumer also passed
@@ -496,41 +507,35 @@ fragments through entry imports and matched the illustrated effective tree;
 local links and whitespace checks passed. These checks verify upstream behavior
 and the candidate schema, not an implemented PromptKit engine feature.
 
-## Remaining PromptKit Decisions
+## Accepted Configuration Decisions
 
-The agreed direction uses the implemented mount/import APIs, a shared
+The following decisions settle the six questions previously listed here:
-specification policy with `IfPresent`, and distinct `release_version` metadata.
-These are no longer pending upstream feature requests. The following choices
-remain before the PromptKit contract is complete:
 
-1. **Main declaration:** recommend requiring an explicit supported declaration
+1. **Main declaration:** optional, including for programmatic or underlay-only
-   in a real or programmatic main input. Alternatively, accept absent main for
+   construction. Validate supplied declarations without injecting missing ones.
-   existing underlay-only callers, with the weaker guarantee documented. Neither
+2. **Public mode selection:** use `IfPresent`; defer a stricter PromptKit option
-   option follows automatically from ConfigKit's mode, and no version should be
+   until a consumer need justifies it. No per-file header requirement.
-   silently injected.
+3. **Reserved header naming:** reserve source-root `version`, while allowing a
-2. **Public mode selection:** use `IfPresent` initially. Decide whether callers
+   resource named `version` through a nested resource mapping.
-   may opt into `Required` through PromptKit's source configuration API. Exposing
+4. **Request versions:** remove request-side version fields and selection
-   it gives deployments an all-document declaration requirement; keeping one
+   machinery. Retain optional descriptive prompt labels only.
-   initial mode reduces API surface. It cannot mean entry-only enforcement.
+5. **Cross-collection inheritance:** use current ConfigKit inheritance; direct
-3. **Reserved header naming:** recommend allowing a local resource ID `version`
+   profile references and authored expansion remain available. Defer a generic
-   through nested mappings in the entry document while reserving source-root
+   upstream extension without adding a PromptKit resolver.
-   `version` for the specification. Alternatively, reserve that resource name
+6. **Consumer API and packaging:** provide a small source/namespace convenience
-   in the new format for a uniform fragment convention, at the cost of a new ID
+   API; recommend entry files and relative imports without requiring a filename,
-   restriction. Do not let an incidental parser limitation silently decide it.
+   layout, main input, or single peer group. Preserve direct fragment loading,
-4. **Request versions:** recommend retaining optional exact assertions against
+   programmatic sources, and consumer-controlled precedence. Inventory reports
-   the one installed prompt's label. Removing request-side version fields is
+   effective collections with optional release metadata.
-   simpler if consumers do not need this compatibility guard. Also finalize the
-   proposed absent/null/nonblank-string rules and listing representation.
-5. **Cross-collection inheritance:** recommend local sibling inheritance and
-   flattening authored cross-collection bases for the initial migration.
-   Request generic cross-path inheritance upstream only if concrete catalog
-   migration needs justify it; do not resolve it inside PromptKit.
-6. **Consumer API and packaging:** recommend an explicitly selected entry path
-   and namespace, with publisher-owned relative imports and one peer group.
-   Finalize the helper signatures, conventional entry filename, inventory types,
-   and migration examples. Direct mounted fragments remain a useful alternative
-   for applications that already assemble sources themselves.
 
-The parent roadmap records this selected direction. Resolve the remaining
+## Remaining Delivery Details
-PromptKit choices here and update current contracts when implementation lands;
+
-retiring the alternatives does not authorize feature implementation.
+No unresolved configuration-policy decision remains from those six questions.
+Implementation still needs to select a released ConfigKit dependency containing
+the required capabilities, finalize helper signatures and inventory/optional-label
+representations, and provide migration examples. These are delivery details,
+not reasons to introduce additional workflows or speculative API options.
+
+Stricter header modes and cross-path inheritance are deferred capabilities, not
+implementation prerequisites. Update current contracts when behavior lands;
+this roadmap records future work and does not itself implement the feature.

docs/roadmap/namespaces.md

@@ -4,12 +4,20 @@ Status: feature roadmap; not implemented. The reserved-slash naming convention,
 reference-resolution rules, decisions 1–3 (scope shape, validation, and integrated
 discovery filtering), and decision 4's move to application/operator-supplied
 configuration are accepted target behavior. Decision 5 selects mounted collections
-and shared source-version checking; its remaining policy and API choices are
+and optional source-version checking. Its six configuration decisions are
-tracked in the collection roadmap, subject to the ConfigKit boundary. Exact Go
+accepted in the collection roadmap, subject to the ConfigKit boundary. Exact Go
 names and option types remain delivery details.
 
 ## Purpose
 
+Simplifying configuration is a primary goal of this round: YAML collections
+replace mandatory catalog Go-module imports, unused prompt-version selection is
+removed, and specification declarations are optional. Publishers may declare a
+specification in an entry document without adding headers to every file.
+Conventions should ease authoring without prescribing consumer layout or
+precedence. The [collection roadmap](configuration-collections-mounted-fragments.md)
+owns the configuration decisions and delivery details.
+
 Let consumers select a namespace once and use convenient local names within
 that namespace across PromptKit operations. An assembled engine may contain
 multiple application prompt libraries and provider profile catalogs with
@@ -84,8 +92,8 @@ still the identifier passed to the provider; qualifying the profile ID does
 not modify that value. Both example profiles may retain the configured model
 `google/gemma-4-31b-it`. Different profiles may select the same model with
 different settings. Prompt version labels remain separate from namespaces. The
-selected collection format installs one definition per prompt ID; optional
+selected collection format installs one definition per prompt ID and removes
-request-version handling remains a decision in the collection roadmap.
+request-side version selection and assertions. Optional labels are descriptive.
 
 Retain unqualified and dotted IDs. Existing slash-containing IDs need review:
 those with one slash and nonempty components become qualified identities, while
@@ -137,8 +145,8 @@ The accepted resolution rules, independent of the final scope API, are:
 
 Keep qualification consistent across execution, preparation, request validation,
 prompt/profile inspection, and applicable smoke-test selections. Namespace
-selection must not change request override precedence, the chosen request-version
+selection must not change request override precedence or provider model strings.
-semantics, or provider model strings.
+Prompts resolve by ID alone.
 
 ### Local And Qualified References In One Operation
 
@@ -180,7 +188,7 @@ namespaces are outside the accepted grammar.
 Collection namespace/release metadata and an API for reporting effective
 collection declarations are desired additions. They are distinct from resource
 namespace enumeration. Their configuration shape and specification-version
-handling remain pending in [decision 5](#5-collection-metadata-and-specification-versioning-open).
+handling are accepted in [decision 5](#5-collection-metadata-and-specification-versioning-accepted).
 
 ## Composition And Compatibility
 
@@ -240,7 +248,8 @@ would supply reusable scope and resolution semantics.
 ## Work Not Included In The Initial Proposal
 
 - Package installation, collection registries, and dependency resolution.
-- Caller-selected collection mount points or import alias rewriting.
+- Automatic rewriting of stored references when mounting or renaming collections.
+  Explicit source destinations and namespace selection are supported by proposal 3.
 - Implicit namespace search paths or fallback to whichever resource exists.
 - Namespace-based access control or filesystem isolation.
 - Changes to model names, inference behavior, or configuration precedence.
@@ -250,24 +259,24 @@ if a concrete consumer need emerges.
 
 ## Delivery Outline
 
-1. Resolve decision 5's ConfigKit integration question and audit existing
+1. Adopt the ConfigKit capabilities selected in decision 5 and audit existing
-   identifier usage against the accepted grammar. Record migration mappings,
+   identifier usage against the accepted grammar. Record migration mappings and
-   application provisioning guidance, and any separately required ConfigKit
+   application provisioning guidance. Finalize Go names and option types for
-   work. Finalize Go names and option types for accepted decisions 1–3.
+   the accepted namespace and collection APIs.
 2. Remove automatic catalog inclusion, catalog-module dependencies, and built-in
    profiles under decision 4. Use caller-selected configuration sources and
    update examples/tests to supply their own definitions.
 3. Implement the smallest public scope surface with shared name qualification
    and existing engine collaborators. Cover supported operations consistently.
 4. Add integrated namespace filtering and representative consumer examples.
-   Implement collection metadata/inventory only after decision 5 is resolved.
+   Implement collection metadata/inventory under the accepted decision 5.
 5. Verify compatibility and scoped resolution through focused offline tests,
    following the [testing policy](../policy/testing.md). Update GoDoc, the
    format reference, consumer guide, and relevant internal documentation as
    behavior lands; retire this roadmap when its work is complete.
 
-Acceptance cases for the settled rules; collection metadata/versioning cases
+Acceptance cases for the settled rules; the collection roadmap owns additional
-follow the eventual decision 5:
+configuration and metadata acceptance cases:
 
 - Two prompt scopes resolve the same local name to their respective prompts;
   a missing name never resolves from the other scope or an unqualified entry.
@@ -308,8 +317,8 @@ follow the eventual decision 5:
 
 Decisions 1–3 are accepted; their alternatives are retained as considered but
 not selected. Decision 4 records the accepted change in collection ownership
-and supersedes the earlier catalog-only migration proposal. Decision 5 retains
+and supersedes the earlier catalog-only migration proposal. Decision 5 records
-the unresolved metadata/versioning question and its alternatives.
+the accepted collection configuration direction and links its delivery details.
 
 ### 1. Public Scope Shape (Accepted)
 
@@ -486,9 +495,9 @@ provisioning but preserve some provider-data coupling. The accepted direction
 places optional defaults in consuming applications and removes those core
 dependencies instead.
 
-### 5. Collection Metadata And Specification Versioning (Open)
+### 5. Collection Metadata And Specification Versioning (Accepted)
 
-**Selected direction: [mounted collections](configuration-collections-mounted-fragments.md).**
+**Accepted direction: [mounted collections](configuration-collections-mounted-fragments.md).**
 Proposal 3 is the active configuration roadmap. It uses collection-local mapping
 keys, one installed definition per prompt, and an optional flat prompt version.
 Input destinations, relative imports, and shared source-version checks are
@@ -515,8 +524,15 @@ collection declarations captured by the engine, not historical manifests or
 proof of unchanged published releases. Source explanation remains ConfigKit's
 inspection concern.
 
-**Still open:** the [six remaining PromptKit decisions](configuration-collections-mounted-fragments.md#remaining-promptkit-decisions)
+The [six configuration decisions](configuration-collections-mounted-fragments.md#accepted-configuration-decisions)
-cover main declaration requirements, exposing stricter checking, resources named
+are now accepted: optional main declarations, if-present checking without a new
-`version`, request-version assertions, cross-collection inheritance, and consumer
+strict-mode option, no global ban on resources named `version`, removal of
-APIs/packaging. Selecting proposal 3 and retiring its alternatives does not settle
+request-version machinery, existing ConfigKit inheritance, and flexible source
-those choices. Removal of bundled catalogs and built-in profiles remains accepted.
+assembly with a small convenience API. Entry names and layouts are conventions;
+consumers retain source and precedence choices. Cross-path inheritance and
+stricter header options are deferred, not prerequisites.
+
+No configuration-policy question remains open from that discussion. Exact API
+signatures, metadata representations, dependency release selection, and migration
+examples remain [delivery details](configuration-collections-mounted-fragments.md#remaining-delivery-details).
+Removal of bundled catalogs and built-in profiles remains accepted.