audita/docs/roadmap/configkit.md

# ConfigKit Adoption Outline

**Updated:** 2026-11-10

**Status:** Target decisions resolved and implementation complete. The
[master roadmap](library-adoption.md) owns shared policy and dependency selection;
the [implementation plan](implementation.md) owns sequencing.

## Baseline and Target

Before this work, Audita used ConfigKit v0.7.1 through its former import path. Its
[configuration contract](../config.md) describes application file discovery,
overlays, defaults, inheritance, secret references, and explicit CLI settings.

Adopt ConfigKit v1.2.0 and its stable public API as the configuration foundation.
Use its native loading, discovery, presence, composition, resolution, diagnostics,
and inspection mechanisms. Audita supplies domain types and validation; retain
custom loading behavior only for a demonstrated domain requirement. Standard
operator access is implemented through the [CommandKit outline](commandkit.md).

The main upstream references are the
[v1 API migration](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.0.0.md),
[v1.2 release](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.2.0.md),
and [configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md).

## Agreed Direction and Migration Work

### Application Schema Version — Resolved

Use `version: 3` for Audita's application configuration in the next major
release, with a hard cutover. The new contract includes the selected native
PromptKit ownership boundaries and the final stage-specific glossary design.
Finalize that combined schema before release so operators migrate once.

Reject obsolete application schema versions with migration guidance. Do not
retain version-2 loading, automatic conversion, or dual-schema compatibility.
Update application defaults, examples, and schema validation together when the
new schema is implemented. The no-main-file behavior below remains supported;
embedded defaults must supply the current application version.

This is Audita's application schema version, independent of library releases and
ConfigKit or PromptKit source headers. It does not require a version header on
every imported fragment. Hard-cutover guidance must explain the actual field and
ownership changes, including glossary-stage configuration, rather than merely
instructing operators to change the version number.

### Discovery Locations and Import Selection — Resolved

For Audita's main application configuration, an explicit `--config` selects
exactly that file. A missing, inaccessible, or invalid explicit file is an error;
do not fall back to discovery.

Without an explicit file, search in this order using ConfigKit's native presets
and filename rules with application name `audita`:

1. `WorkingDirectory` for project-local configuration.
2. `UserConfigDirectory` for personal configuration.
3. `UnixSystemDirectories` for system configuration.

Select the first matching file. Do not merge every discovered file or continue
searching after a selected file fails to load. Additional composition is explicit
through native imports and overlays. Recommend explicit configuration paths for
automation so its selection does not depend on the working directory.

Enable native imports for operator configuration sources, retaining upstream
defaults and declaration-level controls. Imports compose peer documents, not
higher-priority override layers. Missing optional imports may be absent;
operators use `required: true` for essential inputs. Invalid declarations,
unreadable selected files, and composition conflicts retain native errors.

The PromptKit outline owns [automatic prompt sources](promptkit.md#automatic-prompt-sources--resolved).
Those imports compose in a separate engine underlay, using the selected
application main's recorded context under the shared rule below. Keep application
and PromptKit schemas separate while sharing native loading mechanisms.

### Companion Resource Base and Overlays — Resolved

Use the selected main application configuration file's directory as the lookup
base for automatic glossary and prompt companions and named overlays. This applies
to both explicit `--config` and native discovery. Follow ConfigKit's resolved
context: host symlinks use the canonical target directory; a wider containment
root does not move the lookup base. Transitive imports retain their declaring
file's native context, and embedded inputs retain their own filesystem namespace.

For application-owned glossary import declarations, use a non-file underlay
`Input` with `Imports: true` and `MainRelative: configkit.MainRelative()`.
ConfigKit binds it during the single `LoadLayered` call. PromptKit's separate
loader uses the application result's recorded main context, as specified in its
[automatic source contract](promptkit.md#automatic-prompt-sources--resolved).
Do not duplicate main discovery or perform a preliminary full configuration load.

Select native `overlays/<name>.yml` beside the main file. Let `LoadLayered` derive
its overlay context; do not supply an invocation-directory `OverlayFilesystem`
or `OverlayFallback`. No overlay selection loads no overlay; an active selection
requires a usable context and the named file. Aggregate `overlays.yml` is deferred
upstream and is outside this adoption. ConfigKit v1.2.0 satisfies the upstream
API requirement for this decision.

### No Configuration File Found — Resolved

Use ConfigKit's optional-search behavior when automatic discovery finds no file:
continue with embedded defaults, underlays, and explicit CLI settings, then
validate what the requested command needs. Require sufficient configuration for
the operation, not the existence of a main configuration file.

Resource inspection can work without a main file. Processing can run when its
required selections and inputs are otherwise supplied through supported
mechanisms. Report missing command-specific settings clearly; do not invent an
implicit model or profile selection to make incomplete execution settings pass.
Inspection must accurately show that no main file was selected.

When no main context exists, skip automatic optional glossary and prompt
companion imports; retain embedded defaults and explicitly supplied settings.
Do not install a working-directory fallback or infer a base from unsuccessful
search candidates. Use ConfigKit's native absent-base behavior for the glossary
underlay and omit automatic operator prompt inputs in the separate engine load.
An explicitly selected overlay without a usable context fails. Preserve genuine
absent-main evidence rather than manufacturing a placeholder source. Explicit
file errors and failures loading a selected discovered file remain terminal.

### Target Boundaries

The application uses the `go.maximumdirect.net/configkit` module and native
recorded resolution, discovery, source diagnostics, and safe effective output.
Source composition and inheritance precede typed decoding and explicit CLI
assignment; application resolution and validation follow. CLI assignments do
not repair earlier decoding failures, change inheritance relationships, or
propagate parent edits through resolved children. Native source provenance uses
`main` in place of `base`. Genuine source-root controls use `config:`.

PromptKit [owns backend and credential resources](promptkit.md#backend-and-credential-ownership--resolved).
Audita's v3 schema has no separate backend or LLM credential registry. Native
[automatic resource sources](promptkit.md#automatic-prompt-sources--resolved)
use the application main context while retaining their separate schema and tiers.

The v3 schema includes the glossary roadmap's [scope and inheritance model](glossary-stages.md#configuration-scope--resolved),
[typed handoff](glossary-stages.md#list-inputs-and-configuration-handoff--resolved),
and [optional stage identity](glossary-stages.md#stage-identity-and-attribution--resolved).
Glossary definitions use native composition, [default underlay sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved),
and [collection-scoped identity](glossary-stages.md#entry-identity--resolved).
Pipeline stages remain an ordinary ordered list, including repetitions and
explicit empty-pipeline behavior. The application supplies domain resolution
rules within the native lifecycle, with no second runtime defaulting pass.

## Documentation and Acceptance

Update [configuration](../config.md), relevant [CLI](../cli.md) behavior,
[change recipes](../internal/cli-config.md), maintained examples, migration
guidance, and attribution as the corresponding behavior lands. Public docs
remain descriptions of implemented behavior until then.

Acceptance should demonstrate native file selection, source composition,
overlays, explicit false/zero/empty values, derived settings, and secret handling
through real ConfigKit loading. Cover the changed inheritance/assignment order,
source errors, useful failure evidence, and secret-safe inspection. Reuse upstream
coverage for generic grammar rather than copying its test matrix. Verify the
standard ckconfig surface through the assembled CLI and run the full application
suite at the coordinated migration boundary.

Check explicit-file selection without fallback, native working/user/system
search precedence, and terminal errors for a selected invalid file. Verify
optional and required imports and peer-composition errors through Audita's
integration. Verify that discovery exhaustion permits inspection and sufficiently
configured processing, while incomplete processing reports its missing inputs.
Cover absent-main provenance and filesystem context for selected overlays or
relative resources without weakening explicit-file error behavior.
Verify that explicit and discovered mains outside the working directory anchor
companions and overlays beside the selected file. Cover a broader containment
root, native source evidence, and absent-main skipping without a working-directory
fallback. Verify PromptKit receives the same application context while retaining
its separate schema and precedence, through processing and inspection alike.

Verify acceptance of the final version-3 schema and rejection of obsolete
application versions. Check that no-main-file loading uses version-3 defaults,
and that maintained examples and migration guidance cover the final library
ownership and glossary-stage changes without a legacy compatibility path.

The earlier passing configuration suite is useful baseline evidence, not proof
that operators see unchanged semantics. Native semantics and clear migration are
the target; preserving incidental old output or validation order is not.

## Upstream Requests

The main-relative companion/overlay request is fulfilled by ConfigKit v1.2.0.
No further ConfigKit change request is currently identified. Prefer adapting
Audita to its stable supported API. Record any necessary exception with a concrete domain
requirement and the smallest integration boundary that satisfies it.