Clarify collection contracts and migration docs

docs/formats.md

@@ -10,12 +10,14 @@ owns outbound wire behavior. [ConfigKit](https://gitea.maximumdirect.net/eric/Co
 owns the generic YAML grammar, imports, layering, inheritance, and diagnostics.
 This reference describes what Promptkit does with the final effective values.
 
-A configuration document has keyed top-level `backends`, `profiles`, and
-`prompts` mappings. Their keys are literal IDs, not filename-derived identities.
-Each prompt ID maps directly to one definition; an optional `version` string is
+A configuration document may contain keyed top-level `backends`, `profiles`,
+and `prompts` mappings, plus a `collections` mapping of namespaced resource
+groups. Resource keys are literal IDs, not filename-derived identities. Each
+prompt ID maps directly to one definition; an optional `version` string is
 descriptive metadata, not a selection key. Keys and references must be nonblank
 and remain exact: Promptkit does not trim or re-key them. Old embedded `id` and
-`base_profile` fields are invalid. Unknown fields are errors.
+`base_profile` fields are invalid. Unknown fields are errors. Promptkit installs
+no provider or profile catalog; callers select the definitions they need.
 
 ```yaml
 backends:
@@ -36,8 +38,66 @@ prompts:
     output:
       format: text
       validation_mode: none
+collections:
+  support:
+    release_version: "1.4.0"
+    backends:
+      offline:
+        endpoint: https://example.invalid/v1
+    profiles:
+      base:
+        backend: support/offline
+        model: offline-model
+      fast:
+        extends: base
+        timeout_seconds: 30
+    prompts:
+      answer:
+        default_profile: support/fast
+        messages:
+          - role: user
+            content: Answer the selected caller input.
+        output:
+          format: text
+          validation_mode: none
 ```
 
+## Source Headers, Collections, And Resource IDs
+
+An input may omit a source header. When present, the source-root `version` is
+reserved for ConfigKit's specification header and accepts only the exact string
+`"1"` or strict decimal integer `1`; null and other values are invalid. This
+header is distinct from a prompt's nested `version` label and a collection's
+`release_version`. ConfigKit checks and consumes accepted headers on non-main
+inputs; a declaration on the main input remains visible in explicit
+configuration inspection. Headerless inputs still undergo ordinary final-value
+validation. ConfigKit owns generic import and source-history behavior.
+
+The root resource mappings contain unqualified IDs. Each `collections` entry
+has a namespace key and may contain `release_version` plus the same three
+resource mappings. Collection resource keys are local keys; their runtime IDs
+are `<namespace>/<local-key>`. Root and collection keys may be the same. A
+namespace and local key must be nonblank and slash-free, and references must
+name their intended exact ID; mounting a source does not rewrite references.
+For example, the `support/fast` profile above stores `support/offline` as its
+backend ID. In `collections.support.profiles.fast`, ConfigKit `extends: base`
+refers to a sibling profile in that same mapping. It is not a qualified or
+cross-collection reference.
+
+`release_version` and prompt `version` are optional opaque labels. Absent or
+null means no label; an explicitly empty string is retained as a declared
+label. Neither label selects a resource or changes execution. Runtime lookups
+use the captured effective resource indexes. `InspectConfiguration` is an
+explicit operator view of effective settings and provenance; source history is
+not a second runtime resolver, and the retained effective shape is not flattened
+or rewritten into those indexes.
+
+For examples of explicitly selecting native collection inputs and inspecting
+inventories, see the [consumer guide](consumers/pkg-promptkit.md) and its
+[maintained preparation example](../examples/go-library/prepare/main.go). For
+breaking identity and prompt-selection changes, see the
+[configuration migration guide](consumers/configuration-migration.md).
+
 Every effective backend, profile, and prompt definition is validated when
 `NewEngine` constructs the engine, even if it is never selected. A profile may
 be partial: an endpoint and model need only be complete after request overrides
@@ -282,20 +342,25 @@ An explicitly selected missing/unreadable root fails; an empty root contributes
 nothing. Imports are disabled by these helpers unless the caller enables them
 on an input. Single files can use ConfigKit inputs directly.
 
-Backends, profiles, and prompts all follow these same source rules. A later
-profile or backend can change individual fields of a lower definition. A
-request `ProfileID` takes precedence over a prompt `default_profile`; if
+Root backends, profiles, and prompts, as well as collection declarations and
+their resource mappings, follow these same source rules. `CollectionInput`
+mounts one explicitly selected source at a collection destination and enables
+ConfigKit imports for that input; it does not discover or select sources.
+A later profile or backend can change individual fields of a lower definition.
+A request `ProfileID` takes precedence over a prompt `default_profile`; if
 neither is selected, preparation fails. Exact profile inspection selects one
 explicit ID and does not consult a prompt default.
 
 ### Profile Inheritance
 
 ConfigKit resolves `extends` on effective profile definitions. One profile
-may inherit another keyed profile; presence, explicit null, and recursively
-merged maps determine the final fields. References are literal IDs, including
-IDs containing punctuation. There is no Promptkit-specific depth limit or
-second base-chain resolver. Missing references and cycles fail at construction.
-For generic inheritance and layer mechanics, consult
+may inherit a sibling profile by local key in the same root or collection
+mapping; collection inheritance cannot cross namespaces. Presence, explicit
+null, and recursively merged maps determine the final fields. Other resource
+references are exact IDs and use their qualified form when they select a
+collection resource. There is no Promptkit-specific depth limit or second
+base-chain resolver. Missing references and cycles fail at construction. For
+generic inheritance and layer mechanics, consult
 [ConfigKit](https://gitea.maximumdirect.net/eric/ConfigKit).
 
 ## Schemas