diff --git a/docs/config.md b/docs/config.md index 015733f..ea30611 100644 --- a/docs/config.md +++ b/docs/config.md @@ -4,6 +4,8 @@ This reference describes the version-2 configuration loader in `internal/core/co Use the maintained [local](../examples/minimal-config.yml) and [service](../examples/production-config.yml) examples with their PromptKit [profiles](../examples/profiles/) and optional [testing overlay](../examples/overlays/testing.yml). +The [ConfigKit inheritance example](../examples/configkit-inheritance.yml) +shows a local child backend reusing and overriding sibling settings. Choose real models for your endpoint; a testing profile makes no cost or quality guarantee. See the [migration guide](migrations/v2.md) for retired inputs. @@ -20,6 +22,33 @@ and secret-directory bootstrap are disabled. Unknown fields and missing, null, or non-integer `version: 2` are errors. Version-1 files require migration; no compatibility loader or implicit environment configuration remains. +After overlay and explicit CLI override precedence is applied, ConfigKit resolves +native sibling inheritance before typed decoding. Any input mapping may use +`extends: `; the child keeps its key, inherits parent settings, and +overrides them with its own settings. Selected overlay and CLI values therefore +participate in inheritance at their normal precedence. The generic syntax and +resolution rules are defined by ConfigKit v0.5.0's +[sibling inheritance contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/config.md#sibling-inheritance). + +`extends` is reserved structural input in base files, imports, overlays, and +other application input mappings, including mapping values supplied by explicit +CLI setting overrides. ConfigKit consumes it before typed decoding. A previously +valid backend whose ID is literally `extends` cannot be represented under this +rule. Rename that backend to a non-conflicting ID and update every PromptKit +profile that selects it. This compatibility impact means the upgrade does not +promise that every previously valid configuration remains valid. PromptKit +profile documents keep their existing syntax and do not gain ConfigKit +inheritance. + +Inherited values count as explicit input, including zero, false, empty, and +null. Existing field rules still apply: for example, inherited backend +concurrency must be positive, while an inherited queue capacity of zero is +valid. Parent backends undergo the same decoding and application validation as +other backends, whether or not a selected profile uses them. A child +`credential: null` removes the child's inherited credential; it does not remove +the parent's credential reference, which remains subject to ordinary secret +resolution. + Validation runs after overlays, explicit overrides, and derived settings have resolved. An override can therefore repair an invalid lower-precedence setting when that setting can be decoded. ConfigKit retains field origins and derivations diff --git a/docs/internal/cli-config.md b/docs/internal/cli-config.md index 2e4db4d..dca5c6b 100644 --- a/docs/internal/cli-config.md +++ b/docs/internal/cli-config.md @@ -35,9 +35,11 @@ From the repository root, validate the maintained configuration examples: ```sh go run ./cmd/audita config validate --config examples/minimal-config.yml +go run ./cmd/audita config validate --config examples/configkit-inheritance.yml AUDITA_SERVICE_KEY=synthetic-example go run ./cmd/audita config validate --config examples/production-config.yml AUDITA_SERVICE_KEY=synthetic-example go run ./cmd/audita config validate --config examples/production-config.yml --overlay testing go run ./cmd/audita config print-effective --config examples/minimal-config.yml --view profiles +go run ./cmd/audita config print-effective --config examples/configkit-inheritance.yml --view explain ``` Only referenced credentials read environment values; use a controlled synthetic diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index cac8079..c4900ed 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -2,10 +2,11 @@ **Last updated:** 2026-10-03 -**Status:** Planned; implementation has not begun. The dependency-only review -passed Audita's existing offline test suite in a disposable checkout. That is -baseline compatibility evidence, not completion of the feature. The -[implementation plan](implementation.md) owns the ordered work and verification. +**Status:** Complete. The implementation and tests are committed through +`8175ed8`. Final documentation and example changes were included in the full +build, test, example-validation, and local-link checks before the documentation +completion commit. The [implementation plan](implementation.md) records the +ordered work and verification. ## Purpose and Baseline diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 1a6e67b..2473665 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,7 +1,7 @@ # Implementation Plan: ConfigKit v0.5.0 Adoption **Last updated:** 2026-10-03 -**Status:** Ready for implementation. +**Status:** Complete. **Audience:** Luna coding agent. ## Scope and Execution @@ -195,6 +195,8 @@ risk, then commit the runtime/CLI verification unit. ## Stage 5 — Document Native Inheritance and Close the Adoption Unit +**Completion:** Complete. + **Primary files:** `docs/config.md`, `examples/configkit-inheritance.yml`, `docs/internal/cli-config.md`, and `docs/roadmap/configkit.md`. Update another canonical document only where an implemented statement actually changes. diff --git a/examples/configkit-inheritance.yml b/examples/configkit-inheritance.yml new file mode 100644 index 0000000..41a0d69 --- /dev/null +++ b/examples/configkit-inheritance.yml @@ -0,0 +1,14 @@ +version: 2 +backends: + local-base: + endpoint: http://127.0.0.1:11434/v1 + concurrency: 4 + queue_capacity: 0 + local: + extends: local-base + concurrency: 2 +llm: + proposal_profile: local-proposal + validation_profile: local-validation +pipeline: + modules: [grammar]