# ConfigKit v0.1.0

This is the first source release of ConfigKit, an opinionated Go library for strict,
explainable YAML configuration loading.

## Summary

ConfigKit provides one typed loading lifecycle for file, byte, reader, and
defaults-only inputs. It supports bounded explicit imports, strict composition,
selected profiles, explicit CLI overrides, application-owned defaults and recorded
resolution, semantic validation, provenance, redacted effective output, and safe
historical explanation.

Typed environment-name secret references and an explicit secrets-directory bootstrap
keep credential acquisition separate from ordinary loading. Maintained consumer
examples demonstrate simple and composed application shapes without exposing the
private YAML parser dependency.

See the [configuration contract](../config.md) and
[consumer adoption guide](../consumers/README.md) for current behavior and examples.

## Compatibility

This is the initial public release, so there is no earlier ConfigKit release to
upgrade from. The module requires Go 1.25 or newer and supports Linux and macOS on
amd64 and arm64. Candidate validation uses patched Go 1.25 and Go 1.26 toolchains;
native Linux and macOS evidence is required in addition to cross-builds.

Configuration intentionally uses a strict YAML subset. Duplicate keys, aliases,
anchors, merge keys, unsupported tags and scalar forms, trailing documents, and
unknown typed fields are rejected. Composition rejects overlapping non-mapping
definitions; replacement occurs only through selected profiles, explicit CLI
overrides, or recorded application resolution.

The private parser dependency remains explicitly pinned to
`go.yaml.in/yaml/v4 v4.0.0-rc.6`, which was still the newest available v4 release when
the candidate was prepared. No upstream YAML declarations are part of ConfigKit's
public API.

## Upgrade

No action is required for an earlier ConfigKit version because this is the first
release. New consumers can add the module with:

```sh
go get gitea.maximumdirect.net/eric/ConfigKit@v0.1.0
```

The authoritative host may require its normal private-module credentials. Consumers
adapting existing application configuration should review the intentional migration
differences in the [consumer adoption guide](../consumers/README.md), particularly
strict YAML, string schema versions, explicit empty/null behavior, canonical module
objects, `int64` dynamic integers, explicit CLI records, and typed secret references.

## Changes

- Added opaque file, byte, reader, and defaults-only sources with fixed resource
  limits and safe structured diagnostics.
- Added an owned strict YAML model, typed schema binding, detached defaults and
  results, canonical projection, and private parser isolation.
- Added explicit path/glob imports, deterministic strict composition, canonical
  source identity and containment, and selected profile overlays.
- Added layered presence, origins, chronological history, version checks, recorded
  defaulting and normalization, and read-only semantic validation.
- Added secret classification, deterministic redacted effective YAML, typed
  environment references, and bounded explicit secrets-directory bootstrap reports.
- Added parser-neutral explicit CLI overrides and safe structured/human historical
  value explanations, including removed and superseded values.
- Added maintained Narratio-, Notarius-, WeatherReporter-, and Seriatim-shaped
  examples and migration coverage using only ConfigKit and the standard library.
- Added race and bounded fuzz coverage plus a two-toolchain, offline, cross-platform
  source-release checker and maintainer runbook.