Document the consumer migration to identified resources

docs/consumers/configuration-migration.md

@@ -1,8 +1,9 @@
 # Configuration And API Migration
 
-Promptkit no longer installs a provider catalog or selects prompt definitions
-by descriptive version labels. Applications now choose configuration inputs
-explicitly, and execution selects one prompt by its exact ID. This guide
+This breaking pre-v1 minor migration changes the v0.16-era keyed resources to
+identified lists, adopts ConfigKit v1, and removes prompt-version labels.
+Promptkit does not install a provider catalog; applications choose configuration
+inputs explicitly, and execution selects one prompt by its exact ID. This guide
 explains the shape changes and decisions an application must make; it is not an
 automatic migration tool. The [framework format reference](../formats.md) owns
 the current configuration contract, and the root package GoDoc owns exact API
@@ -30,21 +31,19 @@ engine, err := promptkit.NewEngine(promptkit.Config{
 })
 ```
 
-Collection resource keys are local keys, while their runtime identities are
-qualified. For example, `collections.openrouter.profiles.gemini-flash-latest`
-is selected as `openrouter/gemini-flash-latest`. Stored backend, prompt-default,
-and other resource references must use their exact intended IDs; Promptkit does
-not rewrite references when a source is mounted. Profile `extends` remains a
-sibling local key in the same collection, not a cross-collection reference.
+Collection resource IDs are local IDs, while their runtime identities are
+qualified. For example, a profile with `id: gemini-flash-latest` in collection
+`openrouter` is selected as `openrouter/gemini-flash-latest`. Stored backend,
+prompt-default, and other resource references must use their exact intended IDs;
+Promptkit does not rewrite references when a source is mounted. `extends`
+selects a sibling ID in the same list, not a cross-collection reference.
 Review collisions and all references when moving resources into collections.
 
-The root `version` is an optional ConfigKit source header. A collection's
-`release_version` and a prompt's `version` are optional descriptive labels;
-neither selects a resource or changes execution. Preserve a label only when it
-is useful to your application. A formerly version-keyed prompt mapping must be
-reduced to one deliberately chosen definition per prompt ID, with its old label
-retained as prompt metadata if desired. Promptkit cannot choose a winner from a
-consumer's version history.
+The optional source-root `version` header now accepts `2` or `"2"`; headerless
+sources remain valid. A collection's `release_version` remains an optional
+label. Prompt-version labels have been removed: choose one definition per ID
+and store any application-specific release label outside Promptkit. In a
+standalone imported prompt item, root `version` is a source header, not a label.
 
 For example, change a version-keyed definition:
 
@@ -60,12 +59,11 @@ prompts:
         validation_mode: none
 ```
 
-to one direct definition. Its optional `version` is only a label:
+to one identified definition:
 
 ```yaml
 prompts:
-  report:
-    version: "2.0"
+  - id: report
     messages:
       - role: user
         content: Review this report.
@@ -74,6 +72,51 @@ prompts:
       validation_mode: none
 ```
 
+The same conversion applies to backends and profiles. Sibling inheritance uses
+identity references, and a later same-ID record replaces the whole lower record:
+
+```yaml
+profiles:
+  - id: base
+    endpoint: https://example.invalid/v1
+    model: example-model
+  - id: fast
+    extends: {id: base}
+    timeout_seconds: 30
+```
+
+To customize a lower resource's fields, add a distinct inherited variant as
+above; when replacing the same ID, supply the complete intended record. Generic
+append, replace, imports, and inheritance are described by the
+[ConfigKit v1 configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md).
+Source-root controls are now `config:`, not `configkit:`. Imports are optional
+unless the selected import declares `required: true`.
+
+Update ConfigKit imports to `go.maximumdirect.net/configkit` at v1.0.0: its Go
+types are incompatible with the old module path. Promptkit now requires Go
+1.27.0 or newer. Source builders take ordered slices with explicit IDs:
+
+```go
+endpoint, model := "https://example.invalid/v1", "example-model"
+base := "base"
+source := promptkit.ProfileSource("application", []promptkit.ProfileConfig{
+	{ID: "base", Endpoint: &endpoint, Model: &model},
+	{ID: "fast", Extends: &base},
+})
+```
+
+Replace former maps passed to `BackendSource` in the same way, setting each
+`BackendConfig.ID`. Duplicates are retained for loading to reject. Resource
+inspection paths now address list indexes, for example
+`configkit.Keys("profiles").Index(0).Key("model")`. Configuration inspection
+and diffs expose composed values and provenance, while `InspectProfile` and
+other interpreted views expose Promptkit normalization and defaults; the views
+are not promised to be identical.
+
+Remove `PromptVersion` and `PromptIdentity.Version` uses and the corresponding
+`prompt_version` JSON members. Prompt hashes are opaque equality values and may
+change when the removed field no longer participates in hashing.
+
 ## Identity Mapping
 
 The reviewed catalog identities have slash-free profile keys. Their documented
@@ -100,8 +143,8 @@ Gemini profile in the same `openrouter` collection:
 collections:
   openrouter:
     profiles:
-      standard:
-        extends: gemini-flash-latest
+      - id: standard
+        extends: {id: gemini-flash-latest}
 ```
 
 An optional auto profile may instead select the exact backend and model values:
@@ -110,7 +153,7 @@ An optional auto profile may instead select the exact backend and model values:
 collections:
   openrouter:
     profiles:
-      auto:
+      - id: auto
         backend: openrouter/default
         model: openrouter/auto
 ```
@@ -142,10 +185,8 @@ if err != nil {
 ```
 
 If the former format contained multiple versions under one ID, choose the one
-definition the application should install, and optionally keep its label in
-the prompt's `version` field. That label remains descriptive metadata and is
-reported by inspection or results where applicable; it never chooses the
-definition.
+definition the application should install. Promptkit no longer retains or
+returns its former descriptive label.
 
 The public inventory APIs can help an operator inspect a captured effective
 configuration: `ListProfiles`, `ListPrompts`, and `ListBackends` return exact