ConfigKit/docs/consumers

Consumer Adoption Guide

ConfigKit removes parser setup, strict decoding, presence bookkeeping, import and profile traversal, precedence, provenance, secret lookup, and safe inspection from applications. Consumers still own their configuration structs, defaults, semantic validation, schema-version policy, CLI parsing, runtime matching and conversion, resource checks, remote acquisition, and service initialization.

The maintained examples/consumers package demonstrates four sanitized shapes using only ConfigKit and the Go standard library:

Shape	Demonstrated fit	Application code deliberately retained
Narratio-like	Fresh defaults, explicit partial imports, artifact maps, recorded inherited defaults, normalization, and source ownership	Artifact meaning and the separate model_profile domain field
Notarius-like	Canonical object bindings, a string-backed schema version accepting string or integer YAML, strict dynamic options, and int64 dynamic integers	Catalog selection, allowed option keys, range-checked conversion to runtime int
WeatherReporter-like	Defaults-only loading, report maps, canonical module objects, typed option unions, explicit CLI records, and typed secret startup	Report/module compatibility, rejection of explicitly empty domain lists, CLI parsing, and startup ordering
Seriatim-like	Independent strict ordered speaker and autocorrect rule files	First-match and ordered replacement algorithms; no central application configuration file

The YAML under testdata is loaded by the executable examples and ordinary tests. It contains no private application data, credentials, network calls, or dependency on a sibling checkout.

The Notarius-shaped fixtures deliberately load both version: 4 and version: "4" into the same string-backed application field. Its version checker still owns the supported identifier; fractional numeric input and unsupported integer identifiers remain negative examples.

Happy path

An application defines ordinary types and passes one explicit source. Optional features appear only when the application needs them:

result, err := configkit.Load[Config](configkit.File(path), configkit.Options[Config]{
    Definition: rules,
    Imports:    useDeclaredImports,
    Profile:    selectedConfigProfile,
    Overrides:  explicitlySetFlags,
})
if err != nil {
    return err
}
return start(result.Config)

Simple consumers use neither imports nor profiles. A complex consumer can opt into both without redefining their syntax. ConfigKit profiles are configuration overlays; they do not select or replace an application's LLM, model, pipeline, report, or execution profile concepts.

Known module catalogs should use canonical object entries with a module identifier and typed options. A small union struct is sufficient when the available option fields are known; validation selects which fields apply to each module. Runtime- selected catalogs may retain map[string]any, whose integers are int64; applications validate keys and ranges and convert only at their runtime boundary. Neither shape needs YAML reserialization, a parser hook, a ConfigKit registry, or a generic subtree conversion API.

Intentional migration changes

The examples preserve domain meaning while adopting one configuration convention:

• Explicit empty strings, lists, zeroes, false values, and nulls remain intentional. ConfigKit accepts an empty list structurally; WeatherReporter-shaped validation rejects an explicitly or programmatically supplied empty module/template list as a domain rule. Loaded and constructed values use the same validator.
• Canonical module and object bindings replace string shorthand. Unknown fields and incompatible option shapes fail at their semantic paths.
• Schema versions remain string-backed in application types. A configured VersionRule accepts string or strict decimal-integer YAML at its exact path and supplies the spelling to both the checker and a plain string destination.
• Integers inside dynamic options are portable int64 values. Runtime int conversion is explicit and range checked.
• Strict YAML intentionally rejects duplicate keys, aliases, merge keys, unsupported tags/scalars, trailing documents, and unknown typed fields. Diagnostics expose stable classifications and safe paths, not copied parser text.
• General environment-variable configuration overlays retire. Application CLI parsers translate only explicitly set configuration flags into Override records. Separate invocation state remains outside configuration.
• Credential fields migrate to environment-name Secret references. Applications explicitly call LoadSecretsDir before Load when they choose file bootstrap; blocked empty variables remain blocked, and ordinary Load never changes the process environment.

These examples are migration evidence, not completed changes to Narratio, Notarius, WeatherReporter, or Seriatim. Updating those repositories, their deployed YAML, CLI wiring, runtime catalogs, and operational documentation remains separate downstream work.

Maintained API examples

Every nontrivial initial API sketch has a compiled example or a focused behavioral owner:

Roadmap surface	Maintained owner
Load, NoSource, validation, versions, resolution, SecretEnv, overrides, and explanation	Executable examples in example_test.go
Source/import/profile pipeline rules and artifact defaults	Narratio-shaped executable example and fixture
Canonical module objects and dynamic option handling	WeatherReporter- and Notarius-shaped examples and migration tests
LoadSecretsDir, bootstrap reporting, typed lookup, CLI explanation	Example_weatherStartup
Results, metadata, diagnostics, effective output, and writer failures	Focused root-package load, provenance, rendering, and explanation tests

The package-level import-boundary test covers the consumer examples too: supported usage names no YAML dependency, parser type, parser option, or parser error chain.