Finalize ConfigKit architecture documentation

docs/internal/configuration.md

@@ -8,17 +8,17 @@ either interface.
 
 ## Boundary
 
-The configuration package turns a selected YAML file and supported environment
-values into a validated, independently owned configuration. It then resolves a
+The configuration package turns a selected ConfigKit-composed YAML document
+into a validated, independently owned configuration. It then resolves a
 requested pipeline against a module catalog before the framework prepares or
 runs anything.
 
 | Boundary | Inputs | Outputs | Does not own |
 | --- | --- | --- | --- |
-| Loading | Selected file path and environment lookup | Parsed file model and a populated **Config** | Choosing the file path or reporting a command result. |
+| Loading | Selected file path, profile, overrides, and invocation directory | **LoadedConfig** with ConfigKit inspection metadata and a populated **Config** | Choosing the file path or reporting a command result. |
 | Validation | **Config** | Structural configuration errors with pipeline, lane, or binding context | Module availability, capabilities, or construction. |
 | Resolution | Valid **Config**, selected pipeline and lanes, runtime reference changes, LLM override, and module catalog | **EffectiveConfig** with a **ResolvedPipeline** | Materializing reference bytes, preparing modules, execution, or filesystem state. |
-| Summary | **Config** or **EffectiveConfig** | Detached redacted payload suitable for debug summaries | Redacting arbitrary process state or provider traffic. |
+| Inspection | **LoadedConfig** and an optional JSON Pointer | Redacted effective YAML or explanation text | Pipeline selection, module preparation, or provider work. |
 
 The CLI discovers a configuration file, invokes this package, and supplies the
 result to the framework. Configuration never reads an input file, constructs a
@@ -28,23 +28,15 @@ at their respective [CLI](cli.md), [pipeline](pipeline.md), and
 
 ## Loading And Validation
 
-The CLI loads configuration in this order:
-
-1. parse the selected YAML file strictly into the file model;
-2. start from **Default**;
-3. apply the file model; and
-4. apply the supported environment overrides.
-
-This establishes the public precedence order without giving environment input a
-second file schema. Loading and application reject malformed YAML, unsupported
-file versions, unknown fields, invalid values, and identifiers that are empty
-or collide after whitespace normalization. The file application also makes the
-effective extraction-worker default follow the effective LLM limit. A present
-PromptKit local-backend object requires and trims its endpoint, defaults its
-omitted concurrency limit to zero, and is copied so the parsed file model
-cannot alias the populated **Config**. A pipeline `llm_profile` is
-presence-aware: omission remains empty, while a present blank value is
-rejected and a non-empty file value is trimmed before it reaches **Config**.
+ConfigKit acquires the selected root, imports, optional selected profile, and
+explicit CLI overrides in precedence order. Its document definition supplies
+typed defaults, source-aware path normalization, and structural validation
+before conversion to the independently owned runtime **Config**. Only
+`NOTARIUS_CONFIG` participates in discovery; retired field-level environment
+variables do not participate in loading. Version 5 decoding rejects scalar
+module bindings and scalar external references. ConfigKit retains redacted,
+historical inspection metadata while **LoadedConfig** keeps that implementation
+detail private behind effective and explanation writers.
 
 **Config.Validate** checks configuration-only invariants before resolution. It
 rejects incompatible profile sources, invalid state-surface values, unsupported
@@ -57,13 +49,14 @@ It deliberately does not require modules to be registered: that requires a
 catalog and belongs to resolution.
 
 The exact user-selectable values and validation rules are defined in
-[Configuration](../config.md). Keep additions to the file model, an
-environment override, its validation, and that reference in the same change.
+[Configuration](../config.md). Keep document schema, source-aware normalization,
+runtime conversion, and that reference aligned in the same change.
 
 ## Effective Resolution
 
-**Config.Resolve** first recomputes derived concurrency defaults and validates
-the configuration. It normalizes the requested pipeline ID, copies the selected
+**Config.Resolve** derives an absent extraction-worker value in an owned copy
+and validates the configuration. A programmatically supplied worker value is
+always explicit. It normalizes the requested pipeline ID, copies the selected
 profile, and passes the non-empty command-level LLM profile override, requested
 lane selection, and reference changes to the framework resolver.
 
@@ -110,43 +103,37 @@ bytes, a debug payload, or all runtime state. The CLI records it as invocation
 provenance before execution; cache and checkpoint identity have additional
 owners in [Run State Internals](state.md).
 
-Configuration summaries must use **Redacted**, **RedactedSummaryPayload**, or
-**RedactedResolvedPipelinePayload**, never a direct configuration marshal.
-Those methods copy every binding and nested option container, replace values
-whose key is credential-shaped with **[REDACTED]**, and omit materialized
-reference content while retaining safe binding and reference provenance. The
-payload must not alias the source configuration or resolved pipeline.
-PromptKit's local endpoint and concurrency limit are preserved as non-secret
-configuration metadata in the independently owned summary; the object contains
-no credential value. This redaction is deliberately narrow: it protects
-configuration summaries and does not authorize recording arbitrary environment
-values or provider requests.
+Configuration publication uses ConfigKit's redacted effective YAML. Resolved
+pipeline publication uses **RedactedResolvedPipelinePayload**, which copies
+bindings and nested option containers, replaces credential-shaped values with
+**[REDACTED]**, and omits materialized reference content while retaining safe
+provenance. This redaction is deliberately narrow and does not authorize
+recording arbitrary environment values or provider requests.
 
 ## Invariants To Preserve
 
-- Defaults, YAML values, and environment values are applied in one direction;
-  later sources may override only their supported operational settings.
+- ConfigKit composition applies defaults, imports, an optional profile, and
+  explicit overrides in one direction with retained origin metadata.
 - A configuration is structurally valid before it is resolved, and a resolved
   pipeline is compatible with the supplied catalog before preparation begins.
 - Whitespace-normalized identifiers are unique wherever they identify a
   pipeline, step, lane, worker, or reference slot.
-- Resolution and summary generation return detached data. Redaction must cover
-  every configured and resolved binding, including nested validator bindings.
+- Runtime conversion and resolved-pipeline publication return detached data.
 - The resolved digest changes when resolved composition changes and never
   includes itself.
 
 ## Focused Tests
 
-- **internal/core/config/file_config_contract_test.go** covers strict file
-  parsing, normalization, file application, and structural rejection.
-- **internal/core/config/env_contract_test.go** covers supported operational
-  overrides and their precedence.
+- **internal/core/config/document_test.go** and
+  **operational_document_test.go** cover ConfigKit document loading,
+  normalization, imports, profiles, and overrides.
 - **internal/core/config/validation_contract_test.go** covers configuration
   invariants and contextual failures.
 - **internal/core/config/effective_config_contract_test.go** covers defaults,
   selections, overrides, resolution context, digest changes, and ownership.
-- **internal/core/config/redaction_test.go** covers recursive credential
-  redaction, reference-content exclusion, and non-aliasing payloads.
+- **internal/core/config/loaded_config_test.go** covers safe effective and
+  explanation rendering; **redaction_test.go** covers resolved-pipeline
+  redaction and reference-content exclusion.
 
 Run **go test ./internal/core/config** after changing this boundary. Changes to
 the handoff or resolved-composition semantics also need the focused framework