Document keyed configuration and migrated consumer workflows

docs/consumers/pkg-promptkit.md

@@ -78,6 +78,32 @@ explicitly selected missing or unreadable root is an error. Each helper finds
 caller may enable imports on individual inputs. A nil `Sources.Main` is an
 empty main source, not another directory lookup.
 
+For a programmatic document with explicit null or a prompt definition, use a
+labeled mapping as an input. A mapping owns a snapshot of supported values:
+
+```go
+document := configkit.Mapping("application configuration", map[string]any{
+	"profiles": map[string]any{
+		"local-summary": map[string]any{
+			"backend": "local", "model": "example-model",
+			"temperature": nil, // Suppress an inherited provider control.
+		},
+	},
+})
+input := configkit.Input{Source: document}
+// Add input to a later underlay, or set Sources.Main = &input.
+```
+
+`ProfileSource` and `BackendSource` are smaller typed conveniences when null
+is not needed. A caller underlay can overlay catalog backend fields just as it
+can overlay profiles; there is no registration-only backend namespace.
+
+When configuration or message files change, build and validate a new engine,
+then switch the application to that engine for subsequent work. Existing
+engines and prepared handles retain their captured definitions; schema and
+request artifact resources still follow their runtime lifecycle. Inspection
+does not watch or reload sources automatically.
+
 ## Inspect The Captured Configuration
 
 Use [`Engine.InspectConfiguration`](../../configuration_inspection.go) for an
@@ -323,6 +349,38 @@ For programmatic profiles, use [`ProfileSource`](../../profiles.go) with keyed
 `ProfileConfig` values. Nil fields are omitted; pointers preserve explicit
 zero, false, and blank values. Raw `configkit.Mapping` expresses explicit null.
 
+### Migrate From The Previous Configuration API
+
+Replace `Config.PromptDir` and `Config.ProfileDir` with selected ConfigKit
+inputs in `Config.Sources`. The removed `WithPromptFS`, `WithPromptFile`,
+`WithProfileFS`, `WithProfileFile`, `WithFallbackProfileFS`, `WithProfiles`,
+and `WithBackend` options have no compatibility wrappers. Use
+`DirectoryInputs` or `FilesystemInputs` for a strict-composition file group,
+ConfigKit file inputs for individual files, and `ProfileSource`,
+`BackendSource`, or `configkit.Mapping` for programmatic values. Backend IDs
+are keys in configuration, not registrations. Choose caller underlays in
+fallback-to-operator-to-programmatic order; use `Sources.Main` for one final
+highest-priority input.
+
+Move embedded `id` and `version` fields into keyed `profiles` and `prompts`
+maps; convert `base_profile` to ConfigKit `extends`. IDs and references are
+exact literal keys, without trimming. A supplied zero, false, or empty string
+is now distinguishable from omission; null can clear or suppress an inherited
+field according to the [field table](../formats.md#defaults-and-overrides).
+Maps merge recursively across inheritance and layers. `{}` does not clear an
+inherited map: use null to clear the whole map. At request time, a literal
+`extra_params["extends"]` is ordinary provider data, not an inheritance
+instruction; a nonempty request ExtraParams map replaces configured params.
+Changing a model or backend does not clear unrelated explicit fields, though
+backend-derived defaults are applied after inheritance to the final backend.
+
+Invalid final definitions, including unused ones, now fail `NewEngine`; only
+request-dependent failures remain at preparation or execution. Prompt text
+and static templates are captured at construction, not automatically reloaded
+between runs. Replace the engine to pick up changed definitions or message
+files. The [format reference](../formats.md) owns exact field and presence
+rules; the maintained examples show complete runnable workflows.
+
 ### Choose A Profile Ownership Model
 
 Choose the profile source that matches the application's continuity needs: