Add collection migration example and guide

docs/consumers/configuration-migration.md

@@ -0,0 +1,165 @@
+# 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
+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
+signatures and errors.
+
+## Select And Compose The Configuration You Need
+
+Supply each backend, profile, prompt, schema, and collection source that the
+application intends to use. Promptkit does not discover directories or install
+provider definitions implicitly. An application may select an explicit
+collection input with `CollectionInput`:
+
+```go
+input, err := promptkit.CollectionInput(
+	"openrouter",
+	configkit.File("config/openrouter.yaml"),
+)
+if err != nil {
+	return err
+}
+engine, err := promptkit.NewEngine(promptkit.Config{
+	Sources: promptkit.ConfigurationSources{
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{input}}},
+	},
+})
+```
+
+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.
+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.
+
+For example, change a version-keyed definition:
+
+```yaml
+prompts:
+  report:
+    "2.0":
+      messages:
+        - role: user
+          content: Review this report.
+      output:
+        format: text
+        validation_mode: none
+```
+
+to one direct definition. Its optional `version` is only a label:
+
+```yaml
+prompts:
+  report:
+    version: "2.0"
+    messages:
+      - role: user
+        content: Review this report.
+    output:
+      format: text
+      validation_mode: none
+```
+
+## Identity Mapping
+
+The reviewed catalog identities have slash-free profile keys. Their documented
+mapping is:
+
+| Previous identity | Namespaced identity or action |
+| --- | --- |
+| Backend `openrouter` | `openrouter/default` |
+| Backend `rakestrawhome` | `rakestrawhome/default` |
+| Each OpenRouter catalog profile `p` | `openrouter/p`, retaining the exact local key `p` |
+| Profile `rakestrawhome-gemma-4-31b` | `rakestrawhome/rakestrawhome-gemma-4-31b` |
+| Built-in `promptkit-openrouter-standard` | No automatic replacement; optionally define caller profile `openrouter/standard` |
+| Built-in `promptkit-openrouter-auto` | No automatic replacement; optionally define caller profile `openrouter/auto` |
+
+These are conversion examples, not aliases or bundled resources. Mounting old
+`/v3` assets does not update backend references, profile inheritance, prompt
+defaults, or diagnostic defaults inside them. Edit those values to the exact
+qualified IDs you chose.
+
+For example, an optional caller-owned standard profile may extend a selected
+Gemini profile in the same `openrouter` collection:
+
+```yaml
+collections:
+  openrouter:
+    profiles:
+      standard:
+        extends: gemini-flash-latest
+```
+
+An optional auto profile may instead select the exact backend and model values:
+
+```yaml
+collections:
+  openrouter:
+    profiles:
+      auto:
+        backend: openrouter/default
+        model: openrouter/auto
+```
+
+Neither optional profile name is a Promptkit contract. Keep provider model
+strings and settings as selected by the application, including any meaningful
+prefixes. If a backend declares diagnostic defaults, update them to exact
+qualified IDs; an unselected diagnostic default is not automatically made
+resolvable by migration.
+
+## Prompt Selection API
+
+Prompt selection is ID-only. Remove version selectors from calls to `Run`,
+`Prepare`, `PrepareExecution`, `ValidateRequest`, `InspectRequirements`, and
+`SmokeTest`. Remove the `PromptVersion` field from `RunRequest`,
+`RequirementInspectionRequest`, and `SmokeTestRequest`; `InspectPrompt` now
+has the form `InspectPrompt(ctx, promptID)`. For example, select the prompt
+explicitly in the request rather than setting a version selector:
+
+```go
+request := promptkit.RunRequest{
+	PromptID:  "support/report",
+	ProfileID: "support/standard",
+}
+_, err = engine.Run(ctx, request)
+if err != nil {
+	return err
+}
+```
+
+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.
+
+The public inventory APIs can help an operator inspect a captured effective
+configuration: `ListProfiles`, `ListPrompts`, and `ListBackends` return exact
+identities, while `ListNamespaces` and `ListCollections` expose resource-bearing
+namespaces and effective collection declarations. Inventory does not select
+which configuration version the application should deploy.
+
+## Deployment Selection Remains With The Application
+
+Applications decide which checked-in, embedded, operator-supplied, or
+programmatic inputs to compose for each deployment. They also decide when to
+construct a replacement engine after changing those sources. Promptkit does
+not fetch catalog updates, select provider availability, validate upstream
+catalog release status, or automatically migrate arbitrary consumer files.
+The maintained [offline collection example](../../examples/go-library/prepare/main.go)
+shows explicit source selection, local imports, layering, a scoped view, and
+operator inventory without a provider call.

docs/consumers/pkg-promptkit.md

@@ -15,6 +15,12 @@ Import the package as:
 import "gitea.maximumdirect.net/eric/promptkit"
 ```
 
+The maintained [offline preparation example](../../examples/go-library/prepare/main.go)
+demonstrates explicit collection composition and inventory. Applications
+adapting older provider or versioned-prompt configuration can use the
+[configuration migration guide](configuration-migration.md) for the required
+caller-owned choices.
+
 The following Go fragments are illustrative and omit surrounding package,
 import, and error-handling code. Use the maintained examples for complete
 programs.